REST API · v1
API Reference
Capture, recall, and verify Unified Memory Objects over a small REST API. Below: a map of every call, four use cases you can paste into a terminal, and a worked request and response for each endpoint. Base URL https://api.memoryintelligence.io.
At a glance
The whole public surface is ten calls. Click any row to jump to its worked example.
| Do this | Call | What you get |
|---|---|---|
| Capture a memory | POST/v1/process | a UMO with a receipt |
| Capture many at once | POST/v1/batch | one UMO per item |
| Capture from a file | POST/v1/upload | a UMO from PDF text |
| Browse memories | GET/v1/memories | a paginated list |
| Ask or search | POST/v1/memories/query | ranked results with citations |
| Get one memory | GET/v1/memories/{id} | a single UMO |
| Verify provenance | GET/v1/memories/{id}/proof | source, hash, receipt |
| Introspect a memory | GET/v1/memories/{id}/explain | entities and structure |
| Delete a memory | DEL/v1/memories/{id} | a deletion receipt |
| Check the service | GET/health | status, no auth |
Authentication
Every request needs your API key as a bearer token. Get one from the developer portal (free during beta). Keep it server-side; never ship it in client code.
Authorization: Bearer mi_sk_your_key_here
Response envelope
Every response is wrapped in a consistent envelope. Read your payload from data; keep request_id for support. The worked examples below show the data payload only.
{
"status": "success",
"data": { /* endpoint payload, shown below per call */ },
"request_id": "req_8f3f...",
"timestamp": "2026-07-05T19:05:05Z"
}
Errors
Errors use the same envelope with "status": "error" and a human-readable message. The common ones:
| Code | Means | Fix |
|---|---|---|
| 401 | Missing or invalid API key | Check the Authorization header and your key. |
| 404 | No memory with that id | Confirm the umo_id from a capture or list call. |
| 422 | Request body failed validation | Check required fields and types (see each call). |
| 429 | Rate limited | Back off and retry; contact us to raise limits. |
Use cases to try
Four short flows you can paste into a terminal. Set your key first: export MI_KEY="mi_sk_...".
Give an agent memory
Capture a fact once, then ask about it later and get an answer that cites its source.
umo_id it returns.curl -X POST $MI_URL/v1/process -H "Authorization: Bearer $MI_KEY" \ -H "Content-Type: application/json" -d '{"content":"We ship releases on Tuesdays."}'
umo_id.curl -X POST $MI_URL/v1/memories/query -H "Authorization: Bearer $MI_KEY" \ -H "Content-Type: application/json" -d '{"query":"when do we ship?"}'
Prove where an answer came from
Turn a recall into an auditable claim by verifying the source memory's provenance.
umo_id.curl $MI_URL/v1/memories/$UMO_ID/proof -H "Authorization: Bearer $MI_KEY"
Bulk-load a knowledge base
Seed many memories in one call, then browse them.
curl -X POST $MI_URL/v1/batch -H "Authorization: Bearer $MI_KEY" \ -H "Content-Type: application/json" -d '{"items":[{"content":"..."},{"content":"..."}]}'
Honor a delete request
Let a user remove a memory, and keep a receipt that the removal happened.
curl -X DELETE $MI_URL/v1/memories/$UMO_ID -H "Authorization: Bearer $MI_KEY"
Capture
Turn content into structured memory
Turn raw content into a Unified Memory Object. Runs the pipeline (capture, normalize, extract, enrich, parse, embed, validate) and returns the new UMO with a quality score and a provenance receipt.
| content | string required | Raw text to capture. A sentence, transcript, or document. Max 50,000 characters. |
| source | string optional | Source identifier (for example "slack"). Stored for filtering. |
| timestamp | ISO 8601 optional | Original content time. Defaults to now. Affects recency in search. |
curl -X POST https://api.memoryintelligence.io/v1/process \ -H "Authorization: Bearer $MI_KEY" \ -H "Content-Type: application/json" \ -d '{"content":"Sarah proposed provenance hashing for the deck.","source":"meeting-notes"}'
{
"umo_id": "019d9cd5-1be8-8d07-0f31-45018cfe4b68",
"quality_score": 0.72,
"created_at": "2026-07-05T19:05:05Z"
}
umo_id to reference the memory later; quality_score (0 to 1) is the pipeline's confidence in the extraction.Capture many items in one call. Send an array of content items; each becomes its own UMO.
curl -X POST https://api.memoryintelligence.io/v1/batch \ -H "Authorization: Bearer $MI_KEY" -H "Content-Type: application/json" \ -d '{"items":[{"content":"First note."},{"content":"Second note."}]}'
{ "created": 2, "umo_ids": [ "019d...", "019e..." ] }
umo_id per item in order.Capture from a media file, sent as multipart form data.
curl -X POST https://api.memoryintelligence.io/v1/upload \ -H "Authorization: Bearer $MI_KEY" -F "file=@notes.pdf"
{ "umo_id": "019d...", "source": "notes.pdf" }
Recall
Browse, search, and read memories back
A paginated list of the authenticated user's UMOs. Use for browsing, sync, or building a custom UI.
| limit | integer optional | Max results. Default 20, max 100. |
| offset | integer optional | Items to skip for pagination. Default 0. |
| source | string optional | Filter by source. |
curl -s "https://api.memoryintelligence.io/v1/memories?limit=20" \ -H "Authorization: Bearer $MI_KEY"
{ "results": [ { "umo_id": "019d...", "created_at": "..." } ], "total": 128 }
limit and offset; total tells you how many exist so you know when to stop.Ask a natural-language question or run a semantic search. Returns ranked results, each with a citation back to the source UMO.
| query | string required | Your question or search text. |
| limit | integer optional | Max results. Default 5. |
curl -X POST https://api.memoryintelligence.io/v1/memories/query \ -H "Authorization: Bearer $MI_KEY" -H "Content-Type: application/json" \ -d '{"query":"What do I know about funding?","limit":5}'
{ "results": [
{ "umo_id": "019d...", "score": 0.88, "snippet": "Sarah mentioned a seed round." }
] }
score and the source umo_id. Pass that umo_id to proof to turn the answer into evidence.Fetch a single UMO by its umo_id.
curl -s https://api.memoryintelligence.io/v1/memories/$UMO_ID \ -H "Authorization: Bearer $MI_KEY"
{ "umo_id": "019d...", "content": "...", "created_at": "..." }
404 here means the id is wrong or belongs to another account; keys only see their own memories.Verify
Prove and introspect what a memory is
The receipt for a memory: its source, content hash, and provenance chain, cryptographically verifiable.
curl -s https://api.memoryintelligence.io/v1/memories/$UMO_ID/proof \ -H "Authorization: Bearer $MI_KEY"
{ "umo_id": "019d...", "content_hash": "sha256:...", "provenance": "verified" }
Introspect a UMO: the entities, relationships, and structure the pipeline extracted.
curl -s https://api.memoryintelligence.io/v1/memories/$UMO_ID/explain \ -H "Authorization: Bearer $MI_KEY"
{ "entities": [ "Sarah", "seed round" ], "relations": [ { "subject": "Sarah", "predicate": "proposed" } ] }
Manage
Delete data, and check the service
Delete a memory. Returns a deletion receipt so the removal itself is auditable.
curl -X DELETE https://api.memoryintelligence.io/v1/memories/$UMO_ID \ -H "Authorization: Bearer $MI_KEY"
{ "umo_id": "019d...", "deleted": true, "receipt": "del_..." }
Liveness check. No auth required.
curl -s https://api.memoryintelligence.io/health
{ "status": "ok" }