LiticaLitica
Docs/API Reference

MCP Server

API Reference

Most agents only need the two MCP tools. The REST API underneath them is there when you want to search, audit, or bulk-ingest memory directly.

Base URL and auth

The server is at https://mcp.litica.org. Every endpoint except /health requires your API key in the X-API-Key header:

curl https://mcp.litica.org/memories/search?query=job+search \
  -H "X-API-Key: lk_your-api-key"

Writes are queued, not synchronous: add endpoints return 202 and decomposition runs in the background. Search once the write pipeline has drained.

Memories

GET/memories/search
Search memory with a natural language query. Optional top_k (default 5), agent_id (default "default"), and namespace_id. Returns ranked results as [{ id, text, created_at }].
GET/memories/{memory_id}/trace
The full story behind one memory: what it's about, how important it is, how many times it's been used, every query that pulled it up (with rank and score), and the memories it's connected to. This is the trail behind “why did this come up?”
GET/memories
List the most recent memories for an agent_id (optional top_k, namespace_id). Returns [{ id, text, created_at }].
POST/memories
Queue a single memory. Body: { content, agent_id?, namespace_id? }. Returns 202 { queued: true }.
POST/memories/batch
Queue many memories at once. Body: { contents: string[], agent_id?, namespace_id? }. Returns 202 { queued: <count> }.
GET/queries
Recent retrievals for the tenant (optional limit, default 50, max 200).
DELETE/memories/{memory_id}
Delete one memory. DELETE /memories (no id) clears all memory for a tenant + agent.

Document ingestion

Drop in a whole document and Litica decomposes it recursively into atomic, context-enriched memories you can retrieve like any other.

POST/documents
Multipart upload. Fields: file (PDF, DOCX, PPTX, TXT, or MD), agent_id, and namespace_id. Parsed to text at the edge, then queued (202). Unsupported types return 415; empty documents return 422.

Namespaces

Namespaces hold memory that multiple agents share, with per-agent read and write grants.

  • GET /namespaces — list namespaces
  • POST /namespaces — create a namespace
  • GET /namespaces/{namespace_id}/agents — list agent grants
  • POST /namespaces/{namespace_id}/agents — grant an agent read/write access
  • DELETE /namespaces/{namespace_id}/agents/{agent_id} — revoke an agent
  • DELETE /namespaces/{namespace_id} — delete a namespace

Utility

  • GET /tenant — the authenticated tenant id
  • GET /agents — agents that have written memory
  • GET /health — health check (no auth)

Working in Python? The Python SDK wraps every route here, one method per route. Building an agent instead of calling REST directly? Start with the MCP server.