Items · twin memory

The items added for one end user, newest first, paged - ids, text, metadata, about and expiry, as add was given them.

POST /v1/memory/itemsAuth: read key

Lists what you added for one end user, newest first, the way you sent it. This is Mem0's get_all: use it for a "what we know about you" screen, or to check an import. To read one item whole, use item. Items that were forgotten or have expired are not listed, and nor are events from connectors. Makes no model call.

The first page, sent without before, opens with items that were accepted (add answered 202) and have not landed yet, marked landed: false, so an add is listed at once. Then come the landed items, newest first, landed: true. Waiting items are listed on the first page only, beside the limit landed ones.

Headers

Authorizationstringrequired

Bearer tm_…. A read key is enough.

X-Twin-Accountstringrequired

The end user whose items to return. See End users.

X-Request-Idstring

Your id for this request, echoed on the response.

Body

limitinteger

How many items, 1 to 200. Default 50.

beforestring

The next the previous page answered with, for the page after it.

Response

foundinteger

How many items this page holds.

itemsobject[]

Each item as add was given it: id, kind, text, title, at, author, session, about, metadata and expires, with the event_id memory filed it under, and landed: false while it waits to land, then true. A text longer than 2,000 characters is cut there, with truncated: true; item returns it whole.

nextstring

Present when there are older items. Send it as before for the next page.

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

A limit outside 1 to 200.

503unavailable

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

Request

curl https://api.twinmemory.dev/v1/memory/items \
  -H "Authorization: Bearer $TWIN_MEMORY_API_KEY" \
  -H "X-Twin-Account: user_42" \
  -H "Content-Type: application/json" \
  -d '{ "limit": 50 }'

200 OK

{
  "found": 1,
  "items": [
    {
      "id": "pref-diet",
      "kind": "note",
      "text": "Alice is vegan and allergic to peanuts.",
      "at": "2026-10-01T09:30:00+00:00",
      "author": { "id": "user_42", "name": "Alice Chen" },
      "session": "onboarding",
      "about": ["topic:diet"],
      "metadata": { "source": "signup_form" },
      "expires": null,
      "event_id": "ev_620270db0bff9328",
      "landed": true
    }
  ]
}