API Reference

This reference covers Momo’s HTTP REST API for document ingestion, memory extraction, and hybrid search.

This page covers the HTTP REST API only. The embedded C ABI added under momo/ffi is documented separately in Embedded C FFI Reference.

Response Envelope

All API responses follow a consistent envelope format with three optional top-level fields:

{
  "data": { ... },
  "meta": {
    "nextCursor": "string",
    "total": 42
  },
  "error": {
    "code": "snake_case_error_code",
    "message": "Human readable message"
  }
}

data: Present on success, containing the requested resource or result. Absent on error.
error: Present on failure, containing an error code and message. Absent on success.
meta: Optional, used for pagination in list endpoints.

HTTP status codes: 200 for success, 201 for created, 202 for accepted, and appropriate 4xx/5xx for errors.

Authentication

Authentication is handled via Bearer tokens in the Authorization header.

Authorization: Bearer <your_api_key>

API keys are configured via the MOMO_API_KEYS environment variable.
If MOMO_API_KEYS is empty or unset, protected routes return 401 Unauthorized with the standard error envelope.
Failed authentication returns 401 Unauthorized with {"error": {"code": "unauthorized", "message": "..."}}.

Public Routes

The following routes are accessible without authentication:

Route	Description
`GET /api/v1/health`	Health check endpoint
`GET /api/v1/openapi.json`	OpenAPI specification
`GET /api/v1/docs`	ReDoc API documentation UI

All other /api/v1/* routes require a valid Bearer token.

Pagination

List endpoints use page-based pagination with cursors encoded as page numbers.

limit: (Optional) Number of items to return. Default: 20, Max: 100. Clamped to 1..100.
cursor: (Optional) Page number (1-based) encoded as a string. Pass the value from meta.nextCursor to fetch the next page.

Next page cursors are provided in the meta.nextCursor field when more results are available. The cursor is simply the next page number as a string (e.g., "2", "3").

Error Codes

Code	HTTP Status	Description
`invalid_request`	400	The request parameters or body are invalid.
`unauthorized`	401	Authentication is required or the provided token is invalid.
`not_found`	404	The requested resource was not found.
`conflict`	409	A conflict occurred (e.g., duplicate custom ID).
`internal_error`	500	An unexpected server error occurred.
`not_implemented`	501	The requested feature is not yet implemented.

ID Formats

documentId: 21-character NanoID (e.g., V1StGXR8_Z5jdHi6B-myT).
memoryId: 21-character NanoID (e.g., V1StGXR8_Z5jdHi6B-myT).
ingestionId: Same as documentId (maps 1:1 to the document being processed).

Enums

IngestionStatus

"queued", "processing", "completed", "failed"

V1DocumentType

"text", "pdf", "webpage", "image", "video", "audio", "markdown", "code", "csv", "docx", "pptx", "xlsx", "unknown"

V1MemoryType

"fact", "preference", "episode"

SearchScope

"documents", "memories", "hybrid" (default)

GraphNodeType

"memory", "document"

GraphEdgeType

"updates", "relatesTo", "conflictsWith", "derivedFrom", "sources"

Health & System

Health Check

GET /api/v1/health

Example Request:

curl http://localhost:3000/api/v1/health

Example Response:

{
  "data": {
    "status": "ok",
    "version": "0.1.0",
    "database": { "status": "ok" },
    "embeddings": {
      "status": "ok",
      "model": "BAAI/bge-small-en-v1.5",
      "dimensions": 384
    },
    "llm": {
      "status": "available",
      "provider": "openai",
      "model": "gpt-4o-mini"
    },
    "reranker": {
      "enabled": false,
      "model": null,
      "status": "disabled"
    }
  }
}

OpenAPI Spec

GET /api/v1/openapi.json

Example Request:

curl http://localhost:3000/api/v1/openapi.json

API Documentation (UI)

GET /api/v1/docs

Renders the ReDoc UI for API exploration.

MCP (Streamable HTTP)

Momo also exposes a built-in MCP server. This protocol surface is separate from the REST v1 envelope and uses JSON-RPC over streamable HTTP.

Endpoint: POST /mcp (or custom MOMO_MCP_PATH)
OAuth discovery:
- GET /.well-known/oauth-protected-resource
- GET /.well-known/oauth-authorization-server

For protocol handshake, tool/resource catalog, and client examples, see MCP Guide.

The embedded FFI surface is separate from both REST and MCP and does not use the { data, meta, error } response envelope. See Embedded C FFI Reference.

Documents

Create Document

POST /api/v1/documents

Example Request:

curl -X POST http://localhost:3000/api/v1/documents \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Sample document content...",
    "containerTag": "user_123",
    "customId": "unique_ref_001",
    "metadata": { "source": "manual" },
    "contentType": "text/plain",
    "extractMemories": true
  }'

Example Response (202 Accepted):

{
  "data": {
    "documentId": "V1StGXR8_Z5jdHi6B-myT",
    "ingestionId": "V1StGXR8_Z5jdHi6B-myT"
  }
}

Note: ingestionId is the same value as documentId and can be used to poll the ingestion status endpoint.

List Documents

GET /api/v1/documents

Example Request:

curl "http://localhost:3000/api/v1/documents?containerTags=user_123&limit=10" \
  -H "Authorization: Bearer <token>"

Example Response:

{
  "data": {
    "documents": [
      {
        "documentId": "V1StGXR8_Z5jdHi6B-myT",
        "customId": "unique_ref_001",
        "title": "Welcome Note",
        "docType": "text",
        "ingestionStatus": "completed",
        "metadata": {},
        "containerTags": ["user_123"],
        "createdAt": "2024-02-08T12:00:00Z",
        "updatedAt": "2024-02-08T12:00:00Z"
      }
    ]
  },
  "meta": {
    "nextCursor": "2"
  }
}

Get Document

GET /api/v1/documents/{documentId}

Example Request:

curl http://localhost:3000/api/v1/documents/V1StGXR8_Z5jdHi6B-myT \
  -H "Authorization: Bearer <token>"

Example Response:

{
  "data": {
    "documentId": "V1StGXR8_Z5jdHi6B-myT",
    "customId": "unique_ref_001",
    "title": "Welcome Note",
    "content": "Full text content here...",
    "summary": "Short summary of the text",
    "url": "https://example.com/doc",
    "docType": "text",
    "ingestionStatus": "completed",
    "metadata": {},
    "containerTags": ["user_123"],
    "chunkCount": 5,
    "createdAt": "2024-02-08T12:00:00Z",
    "updatedAt": "2024-02-08T12:00:00Z"
  }
}

Update Document

PATCH /api/v1/documents/{documentId}

Example Request:

curl -X PATCH http://localhost:3000/api/v1/documents/V1StGXR8_Z5jdHi6B-myT \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Updated Title",
    "metadata": { "category": "archive" }
  }'

Delete Document

DELETE /api/v1/documents/{documentId}

Example Request:

curl -X DELETE http://localhost:3000/api/v1/documents/V1StGXR8_Z5jdHi6B-myT \
  -H "Authorization: Bearer <token>"

Batch Create Documents

POST /api/v1/documents:batch

Example Request:

curl -X POST http://localhost:3000/api/v1/documents:batch \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "documents": [
      { "content": "Doc 1", "customId": "ref_1" },
      { "content": "Doc 2", "customId": "ref_2" }
    ],
    "containerTag": "user_123"
  }'

Upload File

POST /api/v1/documents:upload

Multipart form fields:

file (required): Binary file payload.
containerTag (optional): Namespace/container tag.
metadata (optional): JSON object string.
extractMemories (optional): true|false (also accepts 1|0|yes|no). Defaults to false.

Supported media and documents include PDF, Office files (docx, pptx, xlsx), images (OCR), and audio/video (transcription) when providers are configured.

Example Request:

curl -X POST http://localhost:3000/api/v1/documents:upload \
  -H "Authorization: Bearer <token>" \
  -F "file=@/path/to/document.pdf" \
  -F "containerTag=user_123" \
  -F "extractMemories=true"

Ingestions

Get Ingestion Status

GET /api/v1/ingestions/{ingestionId}

Example Request:

curl http://localhost:3000/api/v1/ingestions/V1StGXR8_Z5jdHi6B-myT \
  -H "Authorization: Bearer <token>"

Example Response:

{
  "data": {
    "documentId": "V1StGXR8_Z5jdHi6B-myT",
    "status": "completed",
    "title": "Uploaded Document",
    "createdAt": "2024-02-08T12:00:00Z"
  }
}

Search

Unified Search

POST /api/v1/search

Example Request:

curl -X POST http://localhost:3000/api/v1/search \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "q": "What is my favorite color?",
    "containerTags": ["user_123"],
    "limit": 5,
    "rerank": true
  }'

Example Response:

{
  "data": {
    "results": [
      {
        "type": "memory",
        "memoryId": "mem_abc123",
        "content": "User prefers the color blue.",
        "similarity": 0.92,
        "metadata": {},
        "updatedAt": "2024-02-08T12:00:00Z"
      },
      {
        "type": "document",
        "documentId": "doc_xyz789",
        "title": "Bio",
        "docType": "text",
        "score": 0.85,
        "chunks": [
          { "content": "...favorite color is blue...", "score": 0.88 }
        ],
        "metadata": {},
        "createdAt": "2024-02-08T12:00:00Z",
        "updatedAt": "2024-02-08T12:00:00Z"
      }
    ],
    "total": 2,
    "timingMs": 145
  }
}

Memories

Create Memory

POST /api/v1/memories

Example Request:

curl -X POST http://localhost:3000/api/v1/memories \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "User lives in Berlin.",
    "containerTag": "user_123",
    "memoryType": "fact"
  }'

Example Response (201 Created):

{
  "data": {
    "memoryId": "mem_berlin_001",
    "content": "User lives in Berlin.",
    "containerTag": "user_123",
    "memoryType": "fact",
    "version": 1,
    "isLatest": true,
    "isInference": false,
    "isForgotten": false,
    "isStatic": false,
    "metadata": {},
    "createdAt": "2024-02-08T12:00:00Z",
    "updatedAt": "2024-02-08T12:00:00Z"
  }
}

List Memories

GET /api/v1/memories

Example Request:

curl "http://localhost:3000/api/v1/memories?containerTag=user_123&limit=20" \
  -H "Authorization: Bearer <token>"

Get Memory

GET /api/v1/memories/{memoryId}

Example Request:

curl http://localhost:3000/api/v1/memories/mem_abc123 \
  -H "Authorization: Bearer <token>"

Update Memory

PATCH /api/v1/memories/{memoryId}

Example Request:

curl -X PATCH http://localhost:3000/api/v1/memories/mem_abc123 \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "User lives in Berlin, Germany.",
    "isStatic": true
  }'

Example Response:

{
  "data": {
    "memoryId": "mem_abc123",
    "content": "User lives in Berlin, Germany.",
    "version": 2,
    "createdAt": "2024-02-08T12:05:00Z"
  }
}

Delete Memory (Forget by ID)

DELETE /api/v1/memories/{memoryId}

Example Request:

curl -X DELETE http://localhost:3000/api/v1/memories/mem_abc123 \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{ "reason": "obsolete" }'

Example Response:

{
  "data": {
    "memoryId": "mem_abc123",
    "forgotten": true
  }
}

Forget Memory by Content

POST /api/v1/memories:forget

Example Request:

curl -X POST http://localhost:3000/api/v1/memories:forget \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Where the user lives",
    "containerTag": "user_123",
    "reason": "User requested deletion"
  }'

Example Response:

{
  "data": {
    "memoryId": "mem_abc123",
    "forgotten": true
  }
}

Graph

Memory Graph

GET /api/v1/memories/{memoryId}/graph

Query Parameters:

Parameter	Type	Default	Description
`depth`	number	`2`	Number of hops to traverse from the starting memory
`maxNodes`	number	`50`	Maximum number of memory nodes to return
`relationTypes`	string	(all)	Comma-separated edge types: `updates,relatesto,conflictswith,derivedfrom,sources`

Example Request:

curl "http://localhost:3000/api/v1/memories/mem_abc123/graph?depth=3&maxNodes=100&relationTypes=updates,sources" \
  -H "Authorization: Bearer <token>"

Example Response:

{
  "data": {
    "nodes": [
      { "id": "mem_abc123", "type": "memory", "metadata": {} },
      { "id": "doc_xyz789", "type": "document", "metadata": {} }
    ],
    "links": [
      { "source": "mem_abc123", "target": "doc_xyz789", "type": "sources" }
    ]
  }
}

Container Graph

GET /api/v1/containers/{tag}/graph

Query Parameters:

Parameter	Type	Default	Description
`maxNodes`	number	`100`	Maximum number of memory nodes to return

Example Request:

curl "http://localhost:3000/api/v1/containers/user_123/graph?maxNodes=50" \
  -H "Authorization: Bearer <token>"

List Container Tags

GET /api/v1/containers/tags

Returns all distinct active container tags.

Example Request:

curl http://localhost:3000/api/v1/containers/tags \
  -H "Authorization: Bearer <token>"

Example Response:

{
  "data": {
    "tags": ["user_123", "user_456", "project_abc"]
  }
}

Profile

Compute User Profile

POST /api/v1/profile:compute

Example Request:

curl -X POST http://localhost:3000/api/v1/profile:compute \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "containerTag": "user_123",
    "generateNarrative": true
  }'

Example Response:

{
  "data": {
    "containerTag": "user_123",
    "narrative": "The user lives in Berlin and likes pizza.",
    "staticFacts": [
      {
        "content": "Lives in Berlin",
        "confidence": 1.0,
        "createdAt": "2024-02-08T12:00:00Z"
      }
    ],
    "dynamicFacts": [],
    "totalMemories": 2,
    "lastUpdated": "2024-02-08T12:00:00Z"
  }
}

Conversations

Ingest Conversation

POST /api/v1/conversations:ingest

Example Request:

curl -X POST http://localhost:3000/api/v1/conversations:ingest \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      { "role": "user", "content": "I like pizza." }
    ],
    "containerTag": "user_123",
    "memoryType": "preference"
  }'

Example Response (200 OK):

{
  "data": {
    "memoriesExtracted": 1,
    "memoryIds": ["mem_pizza_001"],
    "sessionId": "chat_001"
  }
}

Admin

Run Forgetting Cycle

POST /api/v1/admin/forgetting:run

Example Request:

curl -X POST http://localhost:3000/api/v1/admin/forgetting:run \
  -H "Authorization: Bearer <token>"

Example Response:

{
  "data": {
    "memoriesForgotten": 2,
    "memoriesEvaluated": 150
  }
}