API reference.

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.

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.

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

Provision a tenant. Requires admin.

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",
    "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.

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

{
  "success": true, "http_status": 200, "code": "ok",
  "data": { "tenants": [
    { "tenant_id": "user_482", "status": "ready", "created_at": "..." }
  ] }
}

Any role within scope. Returns the same tenant_id / status / created_at object plus the two name lists below, or 404.

Requires admin. Sets the tenant's label and, optionally, who the two speakers are.

curl -X PATCH https://api.leapmemory.com/v1/tenants/user_482 \
  -H "Authorization: Bearer $LM_KEY" \
  -H "Content-Type: application/json" \
  -d '{"label": "", "owner_names": ["john"], "companion_names": ["wren"]}'

Names are normalized on write: trimmed, lowercased, deduplicated. Non-ASCII letters are preserved, so nuhoglu and nuhoğlu are two entries and both can be registered.

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.

{
  "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"
  }
}

Save 1–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
  }
}

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

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",
        "sentence": "Sam works at Beacon."
      }
    ],
    "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"
      }
    ],
    "anchors_found": [
      { "name": "sam", "type_name": "person", "count": 1, "span_start": 11, "span_end": 14 }
    ]
  }
}

Feed facts and top chunks into your model's context, and cite sentence when your product needs to show where a memory 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 user's own facts come first, their most established relationships and preferences ahead of everything, followed by the freshest recent context. It is computed live from the memory on every call, so it can never go stale.

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.\n- Sam owns the auth service.\n- Sam pairs with Aisha.",
    "facts_included": 3
  }
}

A brand-new tenant returns an empty text with facts_included: 0: 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.

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"]
  }
}

A failed count is often temporary: turns are retried automatically in the background, so a turn can move from failed back to indexed on its own. Treat a failure as final only when it persists.

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. 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.

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. 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"

{
  "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 } }
    ]
  }
}