Every endpoint, request field, and error code. Plain HTTPS against api.leapmemory.com.
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.
# 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.
| Role | Can call |
|---|---|
| admin | Everything: tenant management and all memory operations. |
| ingest | Save 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}). |
| recall | Read 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.
| HTTP | Code | Meaning |
|---|---|---|
| 401 | auth_required | Missing, malformed, or revoked key. |
| 402 | payment_required | The 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. |
| 402 | cap_reached | The 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. |
| 403 | role_required | Key's role does not permit this endpoint. |
| 403 | scope_denied | Key is not scoped to this tenant. |
| 404 | not_found | Tenant or resource does not exist or is deleted. |
| 409 | conflict | Duplicate tenant_id, tenant not in a usable state, or a turn still being processed. |
| 422 | validation_failed | A 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. |
| 500 | internal_error | Something failed on our side. |
No authentication. Returns 200 when the API is up. Point your uptime checks here.
Provision a tenant. Requires admin.
| Field | Type | Notes |
|---|---|---|
| tenant_id | Required string | Your 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. |
| label | Optional string | A human-readable name for the tenant, up to 200 characters. Default empty. |
curl -X POST https://api.leapmemory.com/v1/tenants \
-H "Authorization: Bearer $LM_KEY" \
-H "Content-Type: application/json" \
-d '{"tenant_id": "user_482"}'
{
"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.
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.Any role. Returns the tenants visible to the key's scope. Soft-deleted tenants are excluded by default.
| Query | Type | Notes |
|---|---|---|
| include_deleted | boolean | Default false. Set to true to list soft-deleted tenants too. They come back with status: "deleted" and can be restored. |
{
"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 }
] }
}
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.
Requires admin. Sets the tenant's label and, optionally, who is who in it.
| Field | Type | Notes |
|---|---|---|
| label | string | Written on every call. Sending an empty string clears it. |
| members | object[] | 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. |
| extraction | string | per_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_seconds | integer | In 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 field | Type | Notes |
|---|---|---|
| speaker_id | string | The speaker_id this member's turns carry. Each one appears once. |
| kind | string | person or assistant. At most one assistant. |
| owner | boolean | The person this memory belongs to. Optional, at most one, always a person. |
| names | string[] | 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. |
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:
{"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:
speaker_id.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.
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.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:
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:
window_quiet_seconds.context_only.source, such as documents and mail, become facts on arrival, as they do with per_turn.members. A group tenant uses per_turn.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.
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.
curl -X DELETE "https://api.leapmemory.com/v1/tenants/user_482?hard=true" \ -H "Authorization: Bearer $LM_KEY"
{
"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.
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.
{
"success": true, "http_status": 200, "code": "ok",
"data": { "restored": true, "tenant_id": "user_482" }
}
Save a turn. Requires ingest.
| Field | Type | Notes |
|---|---|---|
| role | Required string | Who 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. |
| content | Required string | The words, verbatim. Up to 100,000 characters. |
| speaker_id | Optional string | Distinguish 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. |
| ts | Optional datetime | When 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. |
| tz | Optional string | The 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_only | Optional boolean | Default 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. |
| source | Optional string | What 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. |
| container | Optional string | Which 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. |
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.{
"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": ""
}
}
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.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.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.
{
"success": true, "http_status": 201, "code": "accepted",
"data": {
"turns": [ { "turn_id": "...", "status": "pending", ... } ],
"count": 3
}
}
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.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.
curl -X POST https://api.leapmemory.com/v1/tenants/user_482/conversation/end \ -H "Authorization: Bearer $LM_KEY"
{
"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.
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.
| Field | Type | Notes |
|---|---|---|
| content | Required string | The 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_id | Required string | Your own id for this upload. It is how you delete it later. |
| speaker_id | Optional string | Who the document belongs to. |
| role | Optional string | Defaults to user. |
| ts | Optional datetime | When 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. |
| extract | Optional boolean | Default 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. |
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"}'
{
"success": true, "http_status": 201, "code": "accepted",
"data": {
"turns": [ { "turn_id": "...", "status": "pending", ... } ],
"count": 14,
"document_id": "supply-agreement-2026"
}
}
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.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.
curl -X DELETE https://api.leapmemory.com/v1/tenants/user_482/documents/supply-agreement-2026 \ -H "Authorization: Bearer $LM_KEY"
{
"success": true, "http_status": 200, "code": "ok",
"data": { "deleted": 14, "document_id": "supply-agreement-2026" }
}
409 and nothing is deleted: all of it goes or none of it does. Retry once ingest settles.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.
curl -X DELETE https://api.leapmemory.com/v1/tenants/user_482/containers/mail/sales@acme.com \ -H "Authorization: Bearer $LM_KEY"
{
"success": true, "http_status": 200, "code": "ok",
"data": { "deleted": 318, "source": "mail", "container": "sales@acme.com" }
}
409 and nothing is deleted.Recall memories for a query. Requires recall. Free: recall never consumes credits or counts against a plan.
| Field | Type | Notes |
|---|---|---|
| query | Required string | Natural language, up to 10,000 characters. Any language. |
| speaker_id | Optional string | Adds 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_entity | Optional string | Pin retrieval to one entity by name. A name that is punctuation or symbols only matches no entity and returns 422. |
| start, end | Optional datetime | Narrows 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_score | Optional number from 0 to 1 | Relevance 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. |
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?"}'
{
"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 }
]
}
}
| Section | What it is |
|---|---|
| facts | Distilled subject-verb-object statements with confidence, mention count, and a one-sentence statement of the fact (sentence). |
| chunks | The verbatim words as they were said, ranked by relevance score. |
| source, container | On 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_found | Entities detected in your query, with type and character span, that steered retrieval. |
| sources | On 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_count | On 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_at | On 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.
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.
curl https://api.leapmemory.com/v1/tenants/user_482/briefing \ -H "Authorization: Bearer $LM_KEY"
{
"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"
}
}
| Field | What it is |
|---|---|
| text | The 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_at | When this text was produced. null for a tenant the writing pass has not reached. |
| covers_through | The timestamp of the newest turn the text accounts for. Anything ingested after this is not in it; reach for recall to cover the gap. |
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.
recall.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.
curl https://api.leapmemory.com/v1/tenants/user_482/turns/status \ -H "Authorization: Bearer $LM_KEY"
{
"success": true, "http_status": 200, "code": "ok",
"data": {
"total": 500,
"pending": 12,
"indexed": 487,
"failed": 1,
"failed_ids": ["6a7892b0-46e9-454f-a225-fe321d006fb5"]
}
}
| Field | What it is |
|---|---|
| total | Turns stored for this tenant. |
| pending | Stored but still being digested. Not yet recallable. |
| indexed | Fully digested and recallable. |
| failed | Turns that could not be processed. Final: they are not retried automatically. The verbatim words are still stored safely. |
| failed_ids | The 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.
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.
| Query | Type | Notes |
|---|---|---|
| limit | int | 1 to 200, default 50. |
| offset | int | Default 0. total reflects the filtered set, so it paginates. |
| search | string | Lexical search over the turn's chunks, through the index's multilingual analyzer. |
| speaker | string | Exact speaker_id. |
| start / end | timestamp | Inclusive window on ts. |
| order | string | desc (default) or asc, by ts. |
{
"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.
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.
{
"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 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.
curl -X DELETE https://api.leapmemory.com/v1/tenants/user_482/turns/6a7892b0-46e9-454f-a225-fe321d006fb5 \ -H "Authorization: Bearer $LM_KEY"
{
"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.
always rules whole, up to 60, ahead of every fact.Requires recall. Ordered by position. Optional scope query filters to one label.
{
"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": "..." }
] }
}
Requires ingest. Returns 201 with the new rule_id.
| Field | Type | Notes |
|---|---|---|
| text | Required string | 1 to 2000 characters. Written into the briefing verbatim, so write it as an instruction to the model. |
| scope | string | When 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. |
| position | int | Print order, default 0. |
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."}'
Requires ingest. Send only what changes: text, scope, position. An unknown rule_id returns 404.
{ "success": true, "http_status": 200, "code": "ok",
"data": { "updated": true, "rule_id": "0f2c..." } }
Requires ingest. Removes the rule; nothing else is touched, because nothing was derived from it. Unknown id returns 404.
{ "success": true, "http_status": 200, "code": "ok",
"data": { "deleted": true, "rule_id": "0f2c..." } }
recall and are free, like recall.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.
| Query | Type | Notes |
|---|---|---|
| limit | int | 1 to 200, default 50. |
| offset | int | Default 0. total reflects the filtered set, so a search paginates. |
| kind | string | One entity type, exact match. |
| q | string | Case-insensitive substring of the name. |
{
"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.
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.
{ "success": true, "http_status": 200, "code": "ok",
"data": { "kinds": [
{ "kind": "person", "count": 41 },
{ "kind": "project", "count": 23 },
{ "kind": "animal", "count": 2 }
] } }
One entity with every fact touching it, in either direction, newest first. Unknown id returns 404.
{
"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.
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.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.
| Query | Type | Notes |
|---|---|---|
| limit | int | 1 to 200, default 50. |
| offset | int | Default 0. |
| order | string | recent (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.
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.
curl "https://api.leapmemory.com/v1/usage?from=2026-09-01&to=2026-09-30&by_tenant=true" \ -H "Authorization: Bearer $LM_KEY"
| Query | What it is |
|---|---|
| from | YYYY-MM-DD. Defaults to the first of the current month. |
| to | YYYY-MM-DD, inclusive of the day named. Defaults to today. |
| by_tenant | true adds a per-tenant breakdown. Off by default. |
{
"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 } }
]
}
}
| Field | What it is |
|---|---|
| totals.ingest | Turns written, single and batch together. This is the metered unit. |
| totals.recall | Recall calls. Free, counted so you can see the read load. |
| totals.briefing | Briefings served, including the one a connector pulls when a session opens. |
| by_endpoint | Every 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. |
| tenants | Present only with by_tenant=true. Same shape, one entry per tenant that had activity. |