Status · twin memory

How far each added item has got - accepted, landed, read or folded - for up to 500 ids at once.

POST /v1/memory/statusAuth: read key

An add is committed at once and does its work afterwards. Status says, for each id, how far it has got. Ask after a whole batch in one call. Makes no model call.

An item is landed within seconds. It is read within a minute or two, or, in the newest part of a conversation, once the conversation has been quiet for about 10 minutes. It is folded at most about 30 minutes after that. See Records and reading.

Phase	Meaning
`accepted`	Committed, not landed yet. Not searchable. An item with an edit still waiting is `accepted` too.
`landed`	In the ledger and the index. Searchable by its words.
`read`	Facts have been read from a window of conversation that holds it.
`folded`	And the pages built from the facts, such as `known` in search, have been rebuilt since.
`unknown`	No item or event by this id, or it was forgotten or has expired.

Headers

Authorizationstringrequired

Bearer tm_…. A read key is enough.

X-Twin-Accountstringrequired

The end user the items were added for. See End users.

X-Request-Idstring

Your id for this request, echoed on the response.

Body

idsstring[]required

1 to 500 ids: item ids as you gave them to add, event ids (ev_…), or any mix.

Response

phasesobject

Each id sent, mapped to its phase.

Errors

400bad request

X-Twin-Account is missing or not a usable id.

401unauthorized

The bearer is not a key this service issued.

404not found

no memory for end user 'user_42' yet.

422invalid

An empty ids list, or more than 500.

503unavailable

At capacity, or this end user is being rebuilt. Retry after Retry-After seconds.

Request

curl https://api.twinmemory.dev/v1/memory/status \
  -H "Authorization: Bearer $TWIN_MEMORY_API_KEY" \
  -H "X-Twin-Account: user_42" \
  -H "Content-Type: application/json" \
  -d '{ "ids": ["msg-001", "pref-diet", "nope-404"] }'

200 OK

{
  "phases": {
    "msg-001": "folded",
    "pref-diet": "landed",
    "nope-404": "unknown"
  }
}