Anansi Docs — Memory API for AI apps

API Reference

Complete reference for all Anansi API endpoints.

Authentication

All requests require a Bearer token in the Authorization header. Create keys from your developer portal.

shell
Authorization: Bearer ans_your_api_key_here

Keys are HMAC-hashed at rest. Every key has a label and creation timestamp visible in the portal. Revoke any key instantly from your dashboard.

POST /v1/ingest

POST/v1/ingest

Ingest content into a user's memory. Content is sanitized, chunked, embedded, and queued for synthesis. Returns immediately — synthesis is asynchronous.

Request body (JSON)

Field	Type		Description
userId	string	required	Your app's identifier for this user. Max 256 chars.
content	string	required	Text to ingest. Max 100 KB. Secrets and API keys are automatically redacted before storage.
sourceType	string	optional	`conversation` · `voice` · `action` · `agent_summary` · `onboarding` · `meeting`. Defaults to `api_text`. Preserved in `relevant[].metadata.sourceType`.
sourceId	string	optional	Idempotency key. Alphanum + `:_./–`, max 256 chars.
sessionId	string	optional	Groups conversation turns by session. Surfaces in `relevant[].metadata.sessionId`.
agentId	string	optional	Identifies the agent that produced this content. Surfaces in `relevant[].metadata.agentId`.
metadata	object	optional	Arbitrary key-value pairs. Recognised fields: `title`, `author`, `timestamp`, `actionType`, `resourceId`, `resourceType`.

Response 202

202Response

{ "id": "api:ws_id:user_abc:uuid", "queued": true }

Errors

Status	Meaning
401	Missing or invalid API key
400	Missing required fields or invalid sourceType
402	Monthly ingest quota exceeded
413	Content exceeds 100 KB
429	Rate limit exceeded (100 req/min)

POST /v1/ingest/batch

POST/v1/ingest/batch

Ingest up to 50 items in a single request. Accepts the same fields as /v1/ingest per item. Ideal for onboarding flows and bulk imports. Synthesis is triggered once for all unique userIds touched.

Request body (JSON)

Field	Type		Description
items	array	required	Array of ingest objects (1–50). Each item supports the same fields as `POST /v1/ingest`.

Response 202

202Response

{ "queued": 4, "ids": ["api:ws:user:uuid1", "api:ws:user:uuid2", ...] }

Errors

Status	Meaning
400	items is not an array, is empty, or exceeds 50
402	Monthly ingest quota exceeded
429	Rate limit exceeded

GET /v1/context

GET/v1/context

Retrieve synthesized memory context for a user. Returns static facts, dynamic context, and (if q provided) relevant vector search results.

Query parameters

Param	Type		Description
userId	string	required	Same userId used during ingest. Max 256 chars.
q	string	optional	Query for vector search. Returns top relevant chunks. Omit for synthesized profile only.
asOf	ISO 8601	optional	Point-in-time query. Returns the synthesized profile as it was at this UTC timestamp. Only chunks ingested on or before this date are included.
asOfKnowledge	ISO 8601	optional	Bi-temporal query. Returns what your system knew at this timestamp — useful for replaying past system state regardless of when events actually occurred.
limit	number	optional	Max number of relevant chunks to return (default 5, max 20). Only applies when `q` is provided.

Response 200

200Response

{ "static": ["Prefers TypeScript", "Works on payments team"], "dynamic": ["Building webhook retry system"], "relevant": [{ "content": "User prefers TypeScript...", "similarity": 0.87, "metadata": { "timestamp": "2026-06-08T..." } }] }

Errors

Status	Meaning
401	Missing or invalid API key
400	Missing userId or userId exceeds 256 chars
402	Monthly context quota exceeded

Tip

Performance: Synthesized profiles are cached in Redis with a 60-second TTL. Warm cache returns in under 30ms. Cold cache miss is under 200ms p95.

GET /v1/entities

GET/v1/entities

Return the entity graph for a user — people, organizations, and tools extracted from ingested content. Updated after each synthesis pass.

Query parameters

Param	Type		Description
userId	string	required	The userId to retrieve the entity graph for.
type	string	optional	Filter by entity type: `person` · `organization` · `tool`. Omit to return all types.

Response 200

200Response

{ "entities": [ { "name": "Sarah", "type": "person", "relationship": "manager", "confidence": 0.91 }, { "name": "Stripe", "type": "organization", "relationship": "employer", "confidence": 0.87 }, { "name": "BullMQ", "type": "tool", "relationship": "uses", "confidence": 0.94 } ] }

Errors

Status	Meaning
401	Missing or invalid API key
400	Missing userId
404	No entity graph found for this user (not yet synthesized)

GET /v1/search

GET/v1/search

Hybrid vector + keyword search across all memory chunks for a user. Use this for full-text retrieval beyond the top-K results returned by GET /v1/context.

Query parameters

Param	Type		Description
userId	string	required	The userId to search memory for.
q	string	required	Search query. Combined vector similarity + BM25 keyword match.
limit	number	optional	Max results to return (default 10, max 50).
sourceType	string	optional	Filter by source type (e.g. `meeting`, `conversation`).
asOf	ISO 8601	optional	Only return chunks ingested on or before this timestamp.

Response 200

200Response

{ "results": [ { "content": "User prefers TypeScript...", "similarity": 0.89, "sourceType": "conversation", "ingestedAt": "2026-06-10T..." }, { "content": "Debugging BullMQ retry logic", "similarity": 0.82, "sourceType": "meeting", "ingestedAt": "2026-06-09T..." } ] }

DELETE /v1/memory

DELETE/v1/memory

Delete all memory for a user — chunks, embeddings, and synthesized profiles. Idempotent.

Query parameters

Param	Type		Description
userId	string	required	The userId whose memory to delete entirely.

Response 200

200Response

{ "deleted": 7 }

Rate limits

Endpoint	Per-minute	Monthly (API plan)
POST /v1/ingest	100 req/min	10,000/month
GET /v1/context	60 req/min	5,000/month
GET /v1/entities	60 req/min	Unlimited
GET /v1/search	60 req/min	Unlimited
DELETE /v1/memory	60 req/min	Unlimited

Monthly limit exceeded → 402. Per-minute limit exceeded → 429.