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; deleted tenants are excluded.

{
  "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, or 404.

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

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.

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.