Open app

API reference.

Every endpoint, request field, and error code. Plain HTTPS against api.leapmemory.com.

Authentication
One header on every request.
HTTP
Authorization: Bearer lm_sk_your_key_here

Keys are created in the dashboard under API keys. A missing, malformed, or revoked key returns 401 auth_required. Keep keys server-side; never ship one in a browser or mobile app.


Response envelope
Every response, success or error, uses one shape.
JSON
# success
{ "success": true,  "http_status": 200, "code": "ok",        "data": { ... } }

# error
{ "success": false, "http_status": 404, "code": "not_found", "message": "tenant not found" }

Branch on success, then read data or message. The code string is stable and safe to match on; message is human-readable and may change.


Key roles & scopes
What a key is allowed to do, and which tenants it can reach.
RoleCan call
adminEverything: tenant management and all memory operations.
ingestSave and delete turns and documents (/turns, /turns/batch, /documents, DELETE /turns/{turn_id}, DELETE /documents/{document_id}, DELETE /containers/{source}/{container}), end a conversation (POST /conversation/end), and write rules (POST /rules, PATCH /rules/{rule_id}, DELETE /rules/{rule_id}).
recallRead only (/recall, /briefing, /turns/status, GET /turns, GET /turns/{turn_id}, GET /rules, /entities, /entities/kinds, /entities/{entity_id}, /facts).

Keys are also scoped: a project-scoped key reaches every tenant in the project; a tenant-scoped key reaches only the tenants it lists. Calling outside a key's scope returns 403 scope_denied. A common production setup is one project-scoped admin key on your server and narrow ingest and recall keys per service.


Error codes
Stable codes for every failure mode.
HTTPCodeMeaning
401auth_requiredMissing, malformed, or revoked key.
402payment_requiredThe developer credit balance cannot cover this write, or this API key has reached the credit limit set on it. A batch or a document is charged in one go, so it is rejected whole when the balance cannot cover every piece, even if the balance is not zero. Ingest pauses until credits are added or the key's limit is raised; stored memories and recall are unaffected.
402cap_reachedThe monthly memory limit on a personal plan is reached: the Free plan, or a paid plan with overage turned off. Ingest is refused until the next cycle, an upgrade, or turning overage on. Stored memories and recall are unaffected. Developer accounts are never capped; they get 402 payment_required instead.
403role_requiredKey's role does not permit this endpoint.
403scope_deniedKey is not scoped to this tenant.
404not_foundTenant or resource does not exist or is deleted.
409conflictDuplicate tenant_id, tenant not in a usable state, or a turn still being processed.
422validation_failedA value you sent cannot be used. Covers request-body schema failures and the semantic ones a schema cannot express: container without source, either of them sent blank, a speaker_id with no ASCII letter, digit or _, start without end or end before start, an anchor_entity that is punctuation only, and a tz sent without a ts, with a ts that has no UTC offset, or that is not a known IANA zone name. The message says which value and why; retrying the same request will not change it.
500internal_errorSomething failed on our side.

GET /v1/health

No authentication. Returns 200 when the API is up. Point your uptime checks here.


Tenants
A tenant is one isolated memory store, typically one per end user. Physically separate databases per tenant: no shared tables, no shared credentials, no row filters.
POST /v1/tenants

Provision a tenant. Requires admin.

FieldTypeNotes
tenant_idRequired stringYour identifier for this user, unique within the project. 1 to 18 characters: lowercase letters, digits, - and _. It must start with a letter, cannot end with - or _, and cannot contain -- or __. Anything else returns 422 validation_failed, so map a UUID or an email address to a short id of your own.
labelOptional stringA human-readable name for the tenant, up to 200 characters. Default empty.
Shell
curl -X POST https://api.leapmemory.com/v1/tenants \
  -H "Authorization: Bearer $LM_KEY" \
  -H "Content-Type: application/json" \
  -d '{"tenant_id": "user_482"}'
Response · 201
{
  "success": true, "http_status": 201, "code": "created",
  "data": {
    "tenant_id": "user_482",
    "label": "",
    "status": "ready",
    "created_at": "2026-07-10T09:39:11.548594+00:00"
  }
}

Provisioning is synchronous: when the call returns, the tenant is ready. A duplicate tenant_id returns 409 conflict.

If that tenant_id was soft-deleted, the 409 says so, and its data is still intact. Restore it instead of creating it again, or remove it permanently with ?hard=true before reusing the name.
GET /v1/tenants

Any role. Returns the tenants visible to the key's scope. Soft-deleted tenants are excluded by default.

QueryTypeNotes
include_deletedbooleanDefault false. Set to true to list soft-deleted tenants too. They come back with status: "deleted" and can be restored.
Response · 200
{
  "success": true, "http_status": 200, "code": "ok",
  "data": { "tenants": [
    { "tenant_id": "user_482", "label": "", "status": "ready", "created_at": "...",
      "members": [], "extraction": "per_turn", "window_quiet_seconds": 600 }
  ] }
}
GET /v1/tenants/{tenant_id}

Any role within scope. Returns one tenant in the same shape as the list: tenant_id, label, status, created_at, the member list below, and its extraction settings, extraction and window_quiet_seconds, or 404.

PATCH /v1/tenants/{tenant_id}

Requires admin. Sets the tenant's label and, optionally, who is who in it.

FieldTypeNotes
labelstringWritten on every call. Sending an empty string clears it.
membersobject[]Everyone who speaks in this tenant, and the names that mean them. Replaces the whole list when sent; omit the field to leave it alone, send [] to clear it. Up to 40 members.
extractionstringper_turn (the default) or conversation: how this tenant's conversation turns become facts. See Conversation mode. Omit the field to leave it alone.
window_quiet_secondsintegerIn conversation mode, how long a conversation stays quiet before it is read. 60 to 86,400; the default is 600. Pick what fits your app's rhythm. Omit the field to leave it alone.
Member fieldTypeNotes
speaker_idstringThe speaker_id this member's turns carry. Each one appears once.
kindstringperson or assistant. At most one assistant.
ownerbooleanThe person this memory belongs to. Optional, at most one, always a person.
namesstring[]1 to 10 names. The first is the current name; keep old names after it when someone is renamed, so earlier mentions still resolve to them. A name can belong to one member only.
Shell
curl -X PATCH https://api.leapmemory.com/v1/tenants/user_482 \
  -H "Authorization: Bearer $LM_KEY" \
  -H "Content-Type: application/json" \
  -d '{"label": "", "members": [
        {"speaker_id": "user", "kind": "person", "owner": true, "names": ["john"]},
        {"speaker_id": "assistant", "kind": "assistant", "names": ["wren"]}]}'

A group is one tenant with several people. Give each a stable speaker_id that never changes, and send their turns with it:

JSON
{"members": [
  {"speaker_id": "m_1", "kind": "person", "names": ["priya"]},
  {"speaker_id": "m_2", "kind": "person", "names": ["omar"]},
  {"speaker_id": "assistant", "kind": "assistant", "names": ["wren"]}]}

What the list does:

  • A listed person's name resolves to that person, whoever says it. When Omar writes "Priya can't come Saturday", the fact is Priya's.
  • Speech-to-text often spells a name the way it sounded. A similar-sounding name is matched to the listed person or to the assistant.
  • Facts are written with the member's current name, never the speaker_id.
  • The assistant is never stored as a person.
  • A person's own name in a message they typed is not bound to them: "my friend John" is someone else.
  • With one person listed, the assistant's "you" means that person. With several, a reply can be to any of them, so "you" is not assumed to be the owner.

Names are normalized on write: trimmed, lowercased, deduplicated. Non-ASCII letters are preserved, so jose and josé are two entries and both can be registered. A list that cannot resolve a name to exactly one member answers 422 with the reason.

If you ingest assistant turns, set this. When your application writes both sides of a conversation with role, LeapMemory needs to know who the user is. Without the list it still refuses to record facts about the assistant, but it also cannot attribute to the user what the assistant said about them: "your leg still hurts?" becomes a fact about nobody. You do not need the list at tenant creation. Send this call the moment you learn the names, once.
Conversation mode
Remember a conversation the way someone who followed it would write it down.

With per_turn, each turn becomes facts as it arrives. With conversation, LeapMemory reads each conversation whole once it has ended, in one pass, and keeps what lasts:

  • A correction later in the conversation replaces what it corrects, so only the final version is remembered.
  • What was true only for that moment, such as being tired or on the way somewhere, stays in the conversation and out of the facts.
  • A request to the assistant stays a request, not a fact about the user.
  • The assistant's lines are read as context for what the user said.
  • A picture the user describes adds facts about what it shows, and names the people and pets the user names.

One pass covers the whole conversation, so a long conversation costs fewer model calls to remember than the same turns read one by one.

How it runs:

  • You save turns exactly as before, with /turns or /turns/batch. Each turn is stored and searchable at once, and recall returns its words right away.
  • Facts, entities and the briefing follow when the conversation ends: when your app calls POST /conversation/end, or once no turn has arrived for window_quiet_seconds.
  • Assistant turns are context in this mode, so they need no context_only.
  • Turns with a source, such as documents and mail, become facts on arrival, as they do with per_turn.
  • Conversation mode reads one person's conversations, so its tenant lists one person in members. A group tenant uses per_turn.
Shell
curl -X PATCH https://api.leapmemory.com/v1/tenants/user_482 \
  -H "Authorization: Bearer $LM_KEY" \
  -H "Content-Type: application/json" \
  -d '{"label": "", "extraction": "conversation", "window_quiet_seconds": 600}'

Switching back to per_turn applies to new turns at once, and any turn still waiting for its conversation to end becomes facts on its own within a minute.

DELETE /v1/tenants/{tenant_id}

Requires admin. Soft by default: the tenant stops serving but its storage is kept and it can be restored. Add ?hard=true to tear down every database permanently.

Shell
curl -X DELETE "https://api.leapmemory.com/v1/tenants/user_482?hard=true" \
  -H "Authorization: Bearer $LM_KEY"
Response · 200
{
  "success": true, "http_status": 200, "code": "ok",
  "data": {
    "deleted": true, "tenant_id": "user_482",
    "mode": "hard", "restorable": false
  }
}

mode reports which delete actually ran, "soft" or "hard", and restorable is true only after a soft one. Read them rather than assuming: a call without ?hard=true keeps every byte of the tenant's data.

Hard deletion is structural: the tenant's databases are dropped entirely, not scanned for rows. Nothing is recoverable afterwards. This is the compliance answer for "erase this user."
POST /v1/tenants/{tenant_id}/restore

Requires admin. Brings a soft-deleted tenant back; storage was kept alive, so restore is instant. Restoring a tenant that is not deleted returns 409.

Response · 200
{
  "success": true, "http_status": 200, "code": "ok",
  "data": { "restored": true, "tenant_id": "user_482" }
}

Memory
Save what was said, recall it whenever it matters.
POST /v1/tenants/{tenant_id}/turns

Save a turn. Requires ingest.

FieldTypeNotes
roleRequired stringWho spoke, e.g. user or assistant. If you send assistant turns, register the speakers first with PATCH /v1/tenants/{id}; LeapMemory never records a fact about the assistant, and the names are what let it attribute to the user what the assistant said about them. That protection applies only when role is exactly assistant, lowercase; with any other spelling, such as Assistant or bot, facts about the assistant are not blocked.
contentRequired stringThe words, verbatim. Up to 100,000 characters.
speaker_idOptional stringDistinguish speakers in multi-party conversations. Defaults to role, exactly as sent. A value you send is stored normalized: lowercased, ASCII letters, digits and _ kept, any other run of characters between them collapsed to -, and leading or trailing ones dropped, so Alice O'Brien becomes alice-o-brien. Non-ASCII letters are removed (Şükrü becomes kr), so send an ASCII id of your own for each person. A value left with nothing, such as a name written only in Cyrillic, returns 422. The stored value comes back in the response, and that is the value the speaker filter on GET /turns matches.
tsOptional datetimeWhen it was said. Defaults to now. Set it when importing history. Required, with a UTC offset such as 2026-10-23T18:06:00Z, whenever you send tz.
tzOptional stringThe writer's IANA time zone, such as Europe/Istanbul. With it, a relative time word in the facts this turn yields carries the date it means in the writer's own calendar: tomorrow said there on the evening of 23 October becomes tomorrow (2026-10-24). See dated facts. ts is the moment and tz the calendar; an offset in ts never decides the day. Leave it out when you do not know the zone: nothing is then dated, since guessing UTC would put a date a day off near midnight. Echoed back on the turn, as an empty string when absent.
context_onlyOptional booleanDefault false. When true, the turn is stored and searchable and is handed to the next turn as context, but no facts are derived from it. It is still billed as one saved memory.
sourceOptional stringWhat kind of place this came from: mail, teams, slack, or whatever your application calls its origins. Lowercased and trimmed; otherwise yours to define. The normalized value comes back in the response, and that is the one delete by container takes. Leave it out for ordinary conversation; sending it blank is an error rather than an omission.
containerOptional stringWhich one: the mailbox address, the channel name, the document. Needs source alongside it. Keeps its case, since it is a name a person reads back. Returned with every chunk in recall and on every turn read, so answers can cite the record they came from, and it is what delete by container removes. An ordinary conversation turn carries both fields as empty strings, not null.
Two fields, set once per connector rather than per message. A mail connector sends source: "mail" with the mailbox as container; a Teams connector sends the channel. speaker_id stays the person, so who spoke and where it came from never share a field.
Response · 201
{
  "success": true, "http_status": 201, "code": "accepted",
  "data": {
    "turn_id": "6a7892b0-46e9-454f-a225-fe321d006fb5",
    "role": "user",
    "speaker_id": "user",
    "status": "pending",
    "ts": "2026-07-10T09:39:14.949785Z",
    "source": "teams",
    "container": "Satış Ekibi",
    "tz": ""
  }
}
Dated facts. When a turn carries tz, each relative time expression in the facts it yields is followed by one space and, in parentheses, what it refers to, in one of three forms: (2026-10-24) for a day; (2026-10-23 23:06) only for a span of hours or minutes such as in two hours, on the writer's 24-hour clock, never with seconds or an offset; and (2026-11-01/2026-11-30) for a period such as next month or this weekend, from its first day to its last, with weeks running Monday to Sunday. A time already written next to the day stays as written: tomorrow (2026-10-24) at 3. A date the text already gives gets no second one, and LeapMemory writes no parenthesised date of this shape for any other reason, so one pattern finds them all: \s\((\d{4}-\d{2}-\d{2})(?: (\d{2}:\d{2}))?(?:/(\d{4}-\d{2}-\d{2}))?\). The dates are language-neutral; show them to people in their own language. Documents are never dated.
Ingest is asynchronous. accepted means the verbatim words are stored; extraction runs in the background and typically completes within seconds; in conversation mode, when the conversation ends. One saved memory is billed per turn. See Billing.
POST /v1/tenants/{tenant_id}/turns/batch

Save 1 to 100 turns in parallel. Requires ingest. Body is {"turns": [ ... ]} with the same fields as a single turn. Use it for importing conversation history, with ts set on each turn.

Response · 201
{
  "success": true, "http_status": 201, "code": "accepted",
  "data": {
    "turns": [ { "turn_id": "...", "status": "pending", ... } ],
    "count": 3
  }
}
The tz and ts of every turn are checked before anything is stored or charged: one invalid turn answers 422 with a message that names it (turn 2 of 3: …), and no turn of the batch is written.
If some turns in a batch fail, the call returns an error. The turns that succeeded are still stored. On developer credits they are charged, and only the failed share is refunded. The error does not say which turns landed, so check GET /turns or /turns/status before retrying: resending the whole batch stores the successful turns a second time and, on credits, charges them again.
POST /v1/tenants/{tenant_id}/conversation/end

Tell LeapMemory a conversation has ended: a call hung up, a session closed. Requires ingest. For tenants in conversation mode. No body. Everything said before this call is read within a minute, without waiting for window_quiet_seconds. A conversation that starts after it is a new conversation, read when it ends in turn.

Call it once the conversation's last /turns call has answered, so its last line is part of what is read.

Shell
curl -X POST https://api.leapmemory.com/v1/tenants/user_482/conversation/end \
  -H "Authorization: Bearer $LM_KEY"
Response · 200
{
  "success": true, "http_status": 200, "code": "ok",
  "data": { "tenant_id": "user_482", "ended_at": "2026-10-21T09:12:03.512048+00:00" }
}

A tenant in per_turn answers 422: its turns become facts as they arrive. Where your app has no clear end, such as a message thread, window_quiet_seconds ends the conversation for you.

POST /v1/tenants/{tenant_id}/documents

Save one upload, such as a contract, a report or a catalogue, without cutting it up yourself. Requires ingest. The text is split on paragraph boundaries into pieces, each stored as an ordinary turn, so nothing is dropped and one handle covers the whole upload. A document is an origin like any other: the pieces are stored with source "document" and container set to your document_id, which is what the delete below and the fields on /turns use.

FieldTypeNotes
contentRequired stringThe document text, up to 204,800 characters. It is cut on paragraph boundaries into pieces of about 2,048 characters, and one call carries at most 100 pieces. A document whose paragraphs leave pieces part-full therefore cuts into more of them and is rejected with 422 below the character ceiling, so split long uploads at roughly 100,000 characters. The count in the response is the piece count.
document_idRequired stringYour own id for this upload. It is how you delete it later.
speaker_idOptional stringWho the document belongs to.
roleOptional stringDefaults to user.
tsOptional datetimeWhen the document is dated. Defaults to now, and applies to every piece. Set it when importing an archive, so each piece's ts and the start/end filters on the turn list carry the document's real date. The start/end filters on recall use when the pieces were indexed, not this ts. A document takes no tz and its facts are never dated: its ts is when it was uploaded or dated, not when each sentence was written. To date pieces you have the writing time for, send them through /turns/batch with ts and tz.
extractOptional booleanDefault false. Off, the document is stored and searchable but no facts are derived from it. On, facts are derived as from a conversation. Either way each piece is one saved memory and is billed as one, so extract changes what LeapMemory learns, not what you pay.
Shell
curl -X POST https://api.leapmemory.com/v1/tenants/user_482/documents \
  -H "Authorization: Bearer $LM_KEY" \
  -H "Content-Type: application/json" \
  -d '{"content": "...", "document_id": "supply-agreement-2026"}'
Response · 201
{
  "success": true, "http_status": 201, "code": "accepted",
  "data": {
    "turns": [ { "turn_id": "...", "status": "pending", ... } ],
    "count": 14,
    "document_id": "supply-agreement-2026"
  }
}
Leave extract off for reference material you want to quote, and turn it on for a document worth learning from. A document is billed as however many pieces it cuts into (the count in the response), so a 14-piece upload costs 14 saved memories, with or without extraction. Recall and search are always free, and the whole text is searchable whichever you choose. See Billing.
DELETE /v1/tenants/{tenant_id}/documents/{document_id}

Remove an upload and everything it produced. Requires ingest. Every piece goes, along with its searchable text and anything derived from it, so the document stops appearing in recall. Deleting an id that is already gone returns 0 rather than an error.

Shell
curl -X DELETE https://api.leapmemory.com/v1/tenants/user_482/documents/supply-agreement-2026 \
  -H "Authorization: Bearer $LM_KEY"
Response · 200
{
  "success": true, "http_status": 200, "code": "ok",
  "data": { "deleted": 14, "document_id": "supply-agreement-2026" }
}
A document still being ingested returns 409 and nothing is deleted: all of it goes or none of it does. Retry once ingest settles.
DELETE /v1/tenants/{tenant_id}/containers/{source}/{container}

Remove everything that came from one place, such as a mailbox you disconnected or a channel you left. Requires ingest. Every turn written with that source and container goes, with its searchable text and everything derived from it. Deleting a document is this call with source fixed to document.

Shell
curl -X DELETE https://api.leapmemory.com/v1/tenants/user_482/containers/mail/sales@acme.com \
  -H "Authorization: Bearer $LM_KEY"
Response · 200
{
  "success": true, "http_status": 200, "code": "ok",
  "data": { "deleted": 318, "source": "mail", "container": "sales@acme.com" }
}
The container is read to the end of the path, so a channel name with slashes needs no escaping. As with documents, a turn still being ingested returns 409 and nothing is deleted.
POST /v1/tenants/{tenant_id}/recall

Recall memories for a query. Requires recall. Free: recall never consumes credits or counts against a plan.

FieldTypeNotes
queryRequired stringNatural language, up to 10,000 characters. Any language.
speaker_idOptional stringAdds this speaker's own memories to the search as an extra starting point. It does not filter: facts and chunks from other speakers can still come back, ranked by relevance. Each chunk carries its speaker_id, so filter on your side if you need one speaker only. Send the normalized value that came back when the turn was saved, for example alice-o-brien. Recall does not normalize it, and a value that matches no speaker adds nothing.
anchor_entityOptional stringPin retrieval to one entity by name. A name that is punctuation or symbols only matches no entity and returns 422.
start, endOptional datetimeNarrows the chunk search to chunks indexed inside the window. That is when LeapMemory processed the turn, not the turn's ts, so a back-dated import is filtered by its import time. Facts are not filtered by time, and the chunk a returned fact was drawn from can still come back from outside the window. Send both or neither, and end must not precede start; otherwise 422 validation_failed.
min_scoreOptional number from 0 to 1Relevance floor for the chunks returned. Omitted, a default floor applies. Set 0 to keep every chunk the reranker scored, up to the ten this endpoint returns, so you can filter on your own side; each chunk carries its score. A verbatim literal match, such as an exact url, id or path you stored, comes back whatever the floor, because the ranker scores such a hit low even when it is the answer.
Shell
curl -X POST https://api.leapmemory.com/v1/tenants/user_482/recall \
  -H "Authorization: Bearer $LM_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "where does Sam work?"}'
Response · 200
{
  "success": true, "http_status": 200, "code": "ok",
  "data": {
    "facts": [
      {
        "subject": "sam",
        "verb": "works-at",
        "object": "beacon",
        "type_name": "works-at",
        "confidence": 0.99,
        "mention_count": 1,
        "last_mentioned": "2026-07-10T09:39:23.295529+00:00",
        "stated_at": "2026-07-10T09:39:12+00:00",
        "sentence": "Sam works at Beacon.",
        "sources": { "user": 1 },
        "turn_ids": ["6a7892b0-46e9-454f-a225-fe321d006fb5"],
        "turn_count": 1
      }
    ],
    "chunks": [
      {
        "chunk_id": "6a7892b0-46e9-454f-a225-fe321d006fb5:0",
        "turn_id": "6a7892b0-46e9-454f-a225-fe321d006fb5",
        "content": "Sam works at Beacon. He owns the auth service and pairs with Aisha.",
        "role": "user",
        "speaker_id": "user",
        "score": 0.9945,
        "importance": 0.5,
        "created_at": "2026-07-10T09:39:23.319353Z",
        "source": "mail",
        "container": "sales@acme.com"
      }
    ],
    "anchors_found": [
      { "name": "sam", "type_name": "person", "count": 1, "span_start": 11, "span_end": 14 }
    ]
  }
}
SectionWhat it is
factsDistilled subject-verb-object statements with confidence, mention count, and a one-sentence statement of the fact (sentence).
chunksThe verbatim words as they were said, ranked by relevance score.
source, containerOn each chunk: the origin the turn was written with, so an answer can cite the mailbox, channel or document it came from. Both are empty strings, not null and not absent, for ordinary conversation turns and for anything stored before 7 Oct 2026.
anchors_foundEntities detected in your query, with type and character span, that steered retrieval.
sourcesOn each fact: how many of its mentions came from each turn role, e.g. {"user": 2, "assistant": 1}. When it is present without a user key, the person never stated it themselves, so your application can present it as the assistant's own words. It is null for facts written before this tally existed; treat null as unknown, not as the assistant's.
turn_ids, turn_countOn each fact: up to 5 of the turns it was drawn from, newest first, each readable with GET /turns/{turn_id}, and how many there are in total. Empty and 0 for a fact whose provenance predates chunk-level tracking.
stated_atOn each fact: when it was last stated in these words, the ts of that turn, in UTC. last_mentioned moves whenever the fact comes up again; stated_at is the date to compare facts by. null only for the oldest facts, stored before this field existed.

Facts are ordered by relevance to the query. When a person's situation changes, the memory keeps both statements, for example "looking for a flat in Lisbon" and, a week later, "signed the lease": both stay true as things that were said, and both can come back. Compare their stated_at and treat the later one as the current state. The earlier one is history, not an error.

Feed facts and top chunks into your model's context with each fact's stated_at, cite sentence as the fact, and read turn_ids through GET /turns/{turn_id} when your product needs to show the words it came from.

GET /v1/tenants/{tenant_id}/briefing

The tenant's ambient picture: who this person is, as one ready-to-inject text block. Requires recall. Free, like recall.

Recall answers questions; the briefing needs none. It is built for the moment before a conversation starts: load it once when a session opens, place it in your model's system context as background knowledge, and let recall handle everything specific from there. The text opens with the tenant's rules scoped always, up to 60, as a bulleted list under the line Rules that always apply:, when any exist. The prose picture follows: the user's own facts first, their most established relationships and preferences ahead of everything, then the freshest recent context. It is written offline by a background pass, not composed on the call, so reading it is a fast lookup. That pass runs once a day for tenants with new turns. A new tenant's first picture is written in the background as soon as its first turn is indexed, so the empty window is short. Use recall in that window and for anything newer than covers_through.

Shell
curl https://api.leapmemory.com/v1/tenants/user_482/briefing \
  -H "Authorization: Bearer $LM_KEY"
Response · 200
{
  "success": true, "http_status": 200, "code": "ok",
  "data": {
    "text": "Sam works at Beacon and owns the auth service, which he pairs on with Aisha. On 8 September he said the migration had shipped, so that concern has passed.",
    "written_at": "2026-09-08T04:12:55.108431+00:00",
    "covers_through": "2026-09-08T03:58:20.771904+00:00"
  }
}
FieldWhat it is
textThe briefing: the rules block, when there are rules, then the picture, which is continuous prose, not a fact list. It resolves what changed over time, so a concern the person has moved past reads as past. The picture is capped at 5,000 characters, cut at a line boundary, so it sits in a system prompt without crowding the conversation. The rules block is bounded by count (up to 60), not length, so keep rules short.
written_atWhen this text was produced. null for a tenant the writing pass has not reached.
covers_throughThe timestamp of the newest turn the text accounts for. Anything ingested after this is not in it; reach for recall to cover the gap.
Say how old it is when you place it in a prompt. The text is a snapshot, and a model reading it without a date treats it as the present moment: a cold the person had yesterday becomes a cold they have now, and often one they just mentioned. Put the age in your own wording, for example Background, written {written_at}:. Statements about a particular day carry their date inside the text as well, but the wrapper is what stops the whole picture reading as current.

A brand-new tenant returns an empty text, or only its rules block if you have added rules. With an empty text, inject nothing and the conversation starts like meeting someone new. When you place the briefing in context, frame it as quiet background the model uses only when relevant, so it informs answers without being recited.

Pull the briefing once per session, not per message. Per-message context belongs to recall.
GET /v1/tenants/{tenant_id}/turns/status

Ingest progress for a tenant: how many turns are stored, how many are fully digested, and whether any failed. Requires recall. Free, like recall.

Ingest is asynchronous: accepted means the words are stored, and extraction finishes in the background. This endpoint tells you when that work is done. After importing history, poll it and flip your product to ready when indexed equals total. It also surfaces the ids of any turns that could not be processed, so a failure is never silent.

Shell
curl https://api.leapmemory.com/v1/tenants/user_482/turns/status \
  -H "Authorization: Bearer $LM_KEY"
Response · 200
{
  "success": true, "http_status": 200, "code": "ok",
  "data": {
    "total": 500,
    "pending": 12,
    "indexed": 487,
    "failed": 1,
    "failed_ids": ["6a7892b0-46e9-454f-a225-fe321d006fb5"]
  }
}
FieldWhat it is
totalTurns stored for this tenant.
pendingStored but still being digested. Not yet recallable.
indexedFully digested and recallable.
failedTurns that could not be processed. Final: they are not retried automatically. The verbatim words are still stored safely.
failed_idsThe turn_id of each failed turn.

Retries happen only while a turn is pending. failed is final: the turn hit a permanent error or used up its retries. The verbatim words stay stored, so contact support to reprocess it.

Poll every few seconds during an import, not per message. In normal conversation a single turn is digested within seconds and polling adds nothing.
GET /v1/tenants/{tenant_id}/turns

Requires recall. Lists what is stored, newest first. Recall answers a question; this shows a person their own memory, which is what a "what do you know about me" screen needs. Free, like recall.

QueryTypeNotes
limitint1 to 200, default 50.
offsetintDefault 0. total reflects the filtered set, so it paginates.
searchstringLexical search over the turn's chunks, through the index's multilingual analyzer.
speakerstringExact speaker_id.
start / endtimestampInclusive window on ts.
orderstringdesc (default) or asc, by ts.
Response · 200
{
  "success": true, "http_status": 200, "code": "ok",
  "data": {
    "turns": [
      { "turn_id": "6a7892b0-...", "role": "user", "speaker_id": "user",
        "content": "I have a dog named Biscuit.", "status": "indexed",
        "ts": "2026-09-08T09:14:02+00:00",
        "source": "mail", "container": "sales@acme.com", "tz": "" }
    ],
    "total": 231,
    "speakers": ["user", "assistant"]
  }
}

status is pending until derivation finishes, then indexed, or failed if processing gave up. With search, at most 1,000 matching turns are considered, so total tops out at 1,000. Pending turns are listed too: they are saved, just not yet searchable. speakers lists the tenant's distinct speaker ids, so a client can offer real filters instead of guessing them. source and container are the normalized origin the turn was written with, empty strings for ordinary conversation and for anything stored before 7 Oct 2026. There is no origin filter here; to remove a whole origin use delete by container.

GET /v1/tenants/{tenant_id}/turns/{turn_id}

Requires recall. One turn, verbatim. This is what a turn_id is for: every fact in the entity card carries the turns it was drawn from, and this reads one of them back, so "where does it know this from" ends in the actual words instead of a uuid. Free, like the list.

Response · 200
{
  "success": true, "http_status": 200, "code": "ok",
  "data": { "turn_id": "6a7892b0-46e9-454f-a225-fe321d006fb5",
            "role": "user", "speaker_id": "user",
            "content": "I have a dog named Biscuit.",
            "status": "indexed", "ts": "2026-09-08T09:14:02+00:00",
            "source": "mail", "container": "sales@acme.com", "tz": "" }
}

Same turn shape the list returns, so a client parses one thing. An unknown id returns 404, and so does an id from another tenant: turns live in per-tenant databases, so there is nothing there to refuse.

DELETE /v1/tenants/{tenant_id}/turns/{turn_id}

Delete one turn and everything derived from it. Requires ingest. Removes the verbatim turn, its recallable chunks, and any facts in the memory graph that came only from this turn. A fact also supported by other turns survives, with this turn's contribution removed. Facts derived before provenance tracking carry no link to their turn, so deleting the turn leaves them in place; only a hard tenant delete removes those. The briefing is marked for rebuild, as the note below explains. Free: deletion never consumes credits.

Shell
curl -X DELETE https://api.leapmemory.com/v1/tenants/user_482/turns/6a7892b0-46e9-454f-a225-fe321d006fb5 \
  -H "Authorization: Bearer $LM_KEY"
Response · 200
{
  "success": true, "http_status": 200, "code": "ok",
  "data": { "deleted": true, "turn_id": "6a7892b0-46e9-454f-a225-fe321d006fb5" }
}

A turn that is still pending returns 409 conflict; retry once extraction settles. An unknown or already-deleted turn_id returns 404. Deleting the same turn twice is safe: the second call is the 404.

Immediate everywhere except the briefing. The turn's words, its chunks, and the facts that came only from it are removed from the primary stores and the search index in the same request, so recall stops returning them at once. The briefing is prose and no single sentence can be cut out of it, so instead it is marked for rebuild. The rebuild runs on the next daily pass once the tenant has a newly indexed turn, or already had one waiting, and composes the text from the surviving turns, so the deleted material cannot reappear. Until then the previous text keeps serving, rather than blanking someone's whole briefing over one deleted message, and it may still mention what you deleted. If no new turn arrives, the briefing is not rebuilt. Today a hard delete of the tenant is the only way to remove content from the briefing at once.

Rules
Standing instructions you author, per tenant. Not memory: never extracted, never ranked, never metered. The briefing prints the always rules whole, up to 60, ahead of every fact.
GET /v1/tenants/{tenant_id}/rules

Requires recall. Ordered by position. Optional scope query filters to one label.

Response · 200
{
  "success": true, "http_status": 200, "code": "ok",
  "data": { "rules": [
    { "rule_id": "0f2c...", "text": "The user's name is John. You are Wren.",
      "scope": "always", "position": 0,
      "created_at": "...", "updated_at": "..." }
  ] }
}
POST /v1/tenants/{tenant_id}/rules

Requires ingest. Returns 201 with the new rule_id.

FieldTypeNotes
textRequired string1 to 2000 characters. Written into the briefing verbatim, so write it as an instruction to the model.
scopestringWhen it applies. Default always, and today only always is read: at connect time the caller's project and activity are unknown, so firing a narrower rule would be a guess. Other labels are stored for when that changes.
positionintPrint order, default 0.
Shell
curl -X POST https://api.leapmemory.com/v1/tenants/user_482/rules \
  -H "Authorization: Bearer $LM_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text": "Never call before 10:00."}'
A rule is the place for what the assistant should do, and it is the answer to "the model keeps thinking a fact is about itself": say plainly who the person is and who the assistant is. Facts describe the person and are derived; rules are authored by you and never change unless you change them.
PATCH /v1/tenants/{tenant_id}/rules/{rule_id}

Requires ingest. Send only what changes: text, scope, position. An unknown rule_id returns 404.

Response · 200
{ "success": true, "http_status": 200, "code": "ok",
  "data": { "updated": true, "rule_id": "0f2c..." } }
DELETE /v1/tenants/{tenant_id}/rules/{rule_id}

Requires ingest. Removes the rule; nothing else is touched, because nothing was derived from it. Unknown id returns 404.

Response · 200
{ "success": true, "http_status": 200, "code": "ok",
  "data": { "deleted": true, "rule_id": "0f2c..." } }

Browse
Read what a memory holds without asking it a question. Recall takes a question, ranks candidates and stays silent when nothing clears the bar, which is right for an answer and wrong for a screen: a person looking at their own memory must not have part of it hidden because a relevance score was low. These four reads list. All require recall and are free, like recall.
GET /v1/tenants/{tenant_id}/entities

Everything this memory holds, newest first. An entity is a thing the memory knows about: a person, a place, a project, a feeling. Types are learned during extraction rather than chosen from a fixed list, so ask /entities/kinds for the real set before you build filters. A name the person corrected (misheard or misspelled) is not listed; its facts are on the right name.

QueryTypeNotes
limitint1 to 200, default 50.
offsetintDefault 0. total reflects the filtered set, so a search paginates.
kindstringOne entity type, exact match.
qstringCase-insensitive substring of the name.
Response · 200
{
  "success": true, "http_status": 200, "code": "ok",
  "data": {
    "entities": [
      { "entity_id": "5ab860616d3e57a9", "name": "biscuit", "kind": "animal",
        "first_seen": "2026-08-14T19:02:11+00:00",
        "last_seen": "2026-09-09T08:31:40+00:00", "mentions": 12 }
    ],
    "total": 214
  }
}

entity_id is an opaque key, and name is stored lowercased. The person themselves is an entity like any other. Their entity_id is _speaker:<speaker_id> and their kind is speaker, written on their first turn. A map drawn around "me" starts from that id.

An entity whose name the person corrected stays in this list, and in the /entities/kinds counts, as a stub with mentions: 0 and no facts. Filtering on mentions: 0 does not single these out, because a speaker entity is also written with 0.

GET /v1/tenants/{tenant_id}/entities/kinds

The entity types present in this tenant, most common first. Two tenants rarely share a set, because the types come from what was actually said, so this is how a UI offers real categories instead of guessed labels.

Response · 200
{ "success": true, "http_status": 200, "code": "ok",
  "data": { "kinds": [
    { "kind": "person", "count": 41 },
    { "kind": "project", "count": 23 },
    { "kind": "animal", "count": 2 }
  ] } }
GET /v1/tenants/{tenant_id}/entities/{entity_id}

One entity with every fact touching it, in either direction, newest first. Unknown id returns 404.

Response · 200
{
  "success": true, "http_status": 200, "code": "ok",
  "data": {
    "entity_id": "5ab860616d3e57a9", "name": "biscuit", "kind": "animal",
    "first_seen": "2026-08-14T19:02:11+00:00",
    "last_seen": "2026-09-09T08:31:40+00:00", "mentions": 12,
    "facts": [
      { "fact_id": "8d41...",
        "subject": { "entity_id": "_speaker:user", "name": "_speaker:user", "kind": "speaker" },
        "verb": "has", "type_name": "owns",
        "object": { "entity_id": "5ab860616d3e57a9", "name": "biscuit", "kind": "animal" },
        "sentence": "The user has a dog named Biscuit.",
        "confidence": 0.93, "mentions": 4,
        "last_seen": "2026-09-09T08:31:40+00:00",
        "stated_at": "2026-09-09T08:31:12+00:00",
        "status": "active",
        "valid_until": null, "closed_by": null,
        "turn_ids": ["6a7892b0-46e9-454f-a225-fe321d006fb5"], "turn_count": 1,
        "sources": { "user": 4 } }
    ]
  }
}

A fact is the relation itself, so it always has two ends: subject, verb, object, plus the sentence the memory would say. A speaker entity's name is its id, such as _speaker:user, so show your own label for the person. turn_ids are up to 5 of the turns the fact was drawn from, newest first, and turn_count is how many there are in total. Read one with GET /turns/{turn_id} to show the words behind a fact, or pass it to DELETE /turns/{turn_id} to remove them. When turn_count is more than 5, deleting the listed turns does not remove every source, so the fact stays. Up to 200 facts per entity; past that, read the map from /facts.

Superseded facts are returned, not hidden. A fact that stopped being current stays with status: "superseded" and valid_until, the time it stopped. Two reasons, told apart by closed_by: null means a later value replaced it, so it used to be true and a timeline can draw it as history; { "kind": "denied", "chunk_id": "...", "evidence": "..." } means the person rejected it, so it was never true. A fact replaced by the background consolidation pass also shows status: "superseded", with valid_until and closed_by both null. Treat status as the signal for current or not, and valid_until as the end time when it is set. Filter on status if your screen wants only what is current. See When memories change.
GET /v1/tenants/{tenant_id}/facts

Every fact in the tenant, page by page, in the same shape as the entity card. Entities joined by facts is how the memory is actually stored, so this is the map itself rather than a view built for drawing one.

QueryTypeNotes
limitint1 to 200, default 50.
offsetintDefault 0.
orderstringrecent (default), newest first. mentions puts the most repeated first.

The two orders answer two questions. mentions answers what carries weight here, where a thing said fifty times outranks a thing said once. recent answers what is in here now, and that is the browsable list: sorted by mentions, everything written today lands under years of repetition and the person concludes nothing was saved.

Each fact carries the same sources tally as recall: mentions counted by turn role, so an audit can separate what the person said from what the assistant produced. Facts closed by a later value, by the person's correction, or, before 18 Sep 2026, by the background consolidation pass stay listed here with status: "superseded". The note above shows how valid_until and closed_by tell them apart: this endpoint is the map of everything stored, including history.


GET /v1/usage

What this key's project has consumed, so you can put it in your own cost. Scoped to the key's project and nothing else. Free, and never billed.

Every call LeapMemory serves is metered. This is that meter, read back: writes, recalls, and briefings, over a window you choose. If you resell memory inside your own product, this is the number you bill against, with one exception: after a batch or document call that partly fails, the turns that succeeded are charged but not counted here. A key scoped to specific tenants sees only those tenants, and its totals are summed from them alone.

Shell
curl "https://api.leapmemory.com/v1/usage?from=2026-09-01&to=2026-09-30&by_tenant=true" \
  -H "Authorization: Bearer $LM_KEY"
QueryWhat it is
fromYYYY-MM-DD. Defaults to the first of the current month.
toYYYY-MM-DD, inclusive of the day named. Defaults to today.
by_tenanttrue adds a per-tenant breakdown. Off by default.
Response · 200
{
  "success": true, "http_status": 200, "code": "ok",
  "data": {
    "period": { "from": "2026-09-01", "to": "2026-09-30" },
    "totals": { "ingest": 1420, "recall": 903, "briefing": 210 },
    "by_endpoint": {
      "turns.ingest": 1180,
      "turns.ingest_batch": 240,
      "memories.recall": 903,
      "memories.briefing": 188,
      "memories.briefing_init": 22
    },
    "tenants": [
      { "tenant_id": "user_482", "ingest": 96, "recall": 74, "briefing": 12,
        "by_endpoint": { "turns.ingest": 96, "memories.recall": 74, "memories.briefing": 12 } }
    ]
  }
}
FieldWhat it is
totals.ingestTurns written, single and batch together. This is the metered unit.
totals.recallRecall calls. Free, counted so you can see the read load.
totals.briefingBriefings served, including the one a connector pulls when a session opens.
by_endpointEvery counter for the window, so you can reconcile a number yourself instead of trusting the fold. Only turns.ingest and turns.ingest_batch feed ingest, memories.recall feeds recall, and memories.briefing and memories.briefing_init feed briefing. Free reads and deletes, such as turns.list or turns.delete, appear here too but are part of no total. documents.ingest counts document calls while their pieces are already in turns.ingest_batch, so do not add the two.
tenantsPresent only with by_tenant=true. Same shape, one entry per tenant that had activity.
Counters only. This endpoint says nothing about invoices, credit balance, or what you owe: it is the meter, not the bill.