API overview
The base URL, how a request is authenticated and addressed, the headers every route reads, and the shape of an error.
Base URL
https://api.twinmemory.devEvery route is under /v1. Every memory route is a POST with a JSON body, including the ones that take no
arguments: overview takes {}. One client function can call all of them.
Routes
| Route | Key | What it does |
|---|---|---|
/v1/memory/add | write | Add messages, documents and notes. The same id again is an edit. |
/v1/memory/search | read | Ask a question in plain words. |
/v1/memory/grep | read | Find an exact phrase, ignoring case. |
/v1/memory/read | read | One file by its path. |
/v1/memory/ls | read | The entries of one directory. |
/v1/memory/around | read | The passages either side of one passage. |
/v1/memory/latest | read | The newest passages, or every passage in a date window. |
/v1/memory/overview | read | What one end user's memory holds: directories and counts. |
/v1/memory/items | read | The items added for one end user, newest first, paged. |
/v1/memory/item | read | One added item, whole, by its id. |
/v1/memory/history | read | Every dated value recorded for one subject. |
/v1/memory/status | read | How far each added item has got. |
/v1/memory/lineage | read | What an item became, or what a fact was read from. |
/v1/memory/versions | write | Every version of one item, and when and why it went. |
/v1/memory/forget | write | Erase items, threads, events or sessions, with a receipt. |
/v1/memory/correct | write | Retract one fact for good, with an optional replacement. |
/v1/me (GET) | any | What the key is: organisation, project, and whether it writes. |
/v1/mcp | read or write | The same tools over the Model Context Protocol. |
Authentication
Send your key as a bearer token on every request:
Authorization: Bearer tm_...A key belongs to one organisation and one of its projects. It either reads, or reads and writes:
- A read key can call every read route. Give it to an agent or MCP client that only reads.
- A read and write key can also call
add,forget,correctandversions. Your backend holds one, and so does an agent that saves.
A read key on a write route is a 403. See Authentication and keys.
Headers
| Header | Routes | Meaning |
|---|---|---|
Authorization | all | Bearer <key>. Required. |
X-Twin-Account | all | The end user whose memory the request reaches. Required. Never a body field. See End users. |
Content-Type | all | application/json. |
X-Request-Id | all | Your id for the request, up to 128 characters of letters, digits, ., _, : and -. Echoed on the response. When it is absent or not of that form, one is minted and returned. |
Idempotency-Key | add | Names the request, so a retry is the same events again. See Idempotency and retries. |
Errors
An error body is JSON with one detail field:
{
"detail": "X-Twin-Account is required: it names whose memory to answer from ('default' is the store the CLI builds)"
}A 422 from validation carries a list instead, one entry per field that failed:
{
"detail": [
{
"type": "string_too_short",
"loc": ["body", "query"],
"msg": "String should have at least 1 character",
"input": "",
"ctx": { "min_length": 1 }
}
]
}| Status | When |
|---|---|
400 | X-Twin-Account is missing or not a usable id. |
401 | The bearer is not a key this service issued. |
403 | A read key called a write route. |
404 | A read route named an end user nothing was ever written for, or correct named a fact that does not exist. |
405 | GET /v1/mcp. |
413 | The body is over 1,000,000 bytes. |
422 | A field is missing or out of bounds. |
503 | The service is at capacity, or this end user's memory is being rebuilt. Retry; a rebuild sends Retry-After: 60. |
Every message is listed in Errors.
OpenAPI
The developer API is published as an OpenAPI document. It needs no key:
curl https://api.twinmemory.dev/v1/openapi-memory.jsonIt lists the fourteen /v1/memory/* routes on this page, with the request bodies and their bounds.
MCP
The same tools are served over the Model Context Protocol at POST https://api.twinmemory.dev/v1/mcp, with the
same two headers. See the MCP route and the MCP setup guides.
Zotero
Your research library - the papers and references you save, your notes on them, attachments with their indexed text, PDF annotations and collections, in your library and your groups, in an end user's memory.
Me
What an API key is - its organisation, project, and whether it writes - checked before naming any end user.