API Reference

Complete reference for the CLAIV Memory API.

Base URL: https://api.claiv.io

The tenant_id is inferred from your API key. You never send it in request payloads. CLAIV Memory returns context; your LLM generates the final reply.

Authentication

All API requests require a Bearer token in the Authorization header:

Authorization: Bearer YOUR_API_KEY

POST /v1/ingest

Ingest an event into the memory system. Returns immediately; enrichment happens asynchronously (1–5s).

Request Body

ParameterTypeDescription
user_idrequiredstringUnique identifier for the user
typerequiredenumOne of: "message", "tool_call", "app_event"
contentrequiredstringThe event content to ingest
thread_idstringOptional thread/conversation scope

Response

FieldTypeDescription
event_idstringUnique ID for the ingested event
dedupedbooleanWhether this event was a duplicate

Example

Request
curl -X POST https://api.claiv.io/v1/ingest \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "user-123",
    "type": "message",
    "content": "User prefers dark mode and concise responses"
  }'
Response (200)
{
  "event_id": "evt_abc123",
  "deduped": false
}
After ingest, a background worker enriches the event asynchronously (1–5 seconds). Recall may return empty results until enrichment completes.

POST /v1/recall

Retrieve relevant context for a user, packed within a token budget. Inject the returned context into your LLM's system prompt.

Request Body

ParameterTypeDescription
user_idrequiredstringUser to retrieve context for
taskrequiredstringContext/query for relevance ranking
token_budgetrequiredintegerMaximum tokens to return (200-8000)
thread_idstringOptional thread scope filter

Response

FieldTypeDescription
system_contextstringPre-built context string to inject into your LLM system prompt
memory_blocksarrayArray of structured memory objects with type, content, and relevance
citationsstring[]Event IDs that contributed to the returned context
token_estimateintegerApproximate token count of the returned context

Example

Request
curl -X POST https://api.claiv.io/v1/recall \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "user-123",
    "task": "What are the user preferences?",
    "token_budget": 2000
  }'
Response (200)
{
  "system_context": "User prefers dark mode and concise responses.",
  "memory_blocks": [
    {
      "type": "fact",
      "content": "Prefers dark mode",
      "relevance": 0.95
    },
    {
      "type": "fact",
      "content": "Likes concise responses",
      "relevance": 0.88
    }
  ],
  "citations": ["evt_abc123"],
  "token_estimate": 42
}

POST /v1/forget

Delete derived memory data for a user. Original ingested events are preserved. Returns a compliance receipt.

Request Body

ParameterTypeDescription
user_idrequiredstringUser whose derived data to delete
thread_idstringDelete only from specific thread

Response

FieldTypeDescription
receipt_idstringUnique receipt ID for compliance records
deleted_countsobjectCounts of deleted items by category (facts, episodes, embeddings)

Example

Request
curl -X POST https://api.claiv.io/v1/forget \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "user-123"
  }'
Response (200)
{
  "receipt_id": "rcpt_xyz789",
  "deleted_counts": {
    "facts": 3,
    "episodes": 1,
    "embeddings": 12
  }
}

Error Codes

CodeErrorDescription
400Bad RequestInvalid parameters (e.g., missing required fields, invalid type enum)
401UnauthorizedInvalid or missing API key
404Not FoundResource does not exist
422UnprocessableValid JSON but semantically incorrect (e.g., token_budget out of range)
429Quota ExceededPlan quota exceeded. Check Usage & Limits for reset date.
500Internal ErrorServer error. Retry with exponential backoff.

Next steps

Understanding usage tracking and quota limitsAPI key management and security best practicesCommon issues and debugging tips