API

The xmemory REST API is what the Python and TypeScript SDKs call under the hood. You can also call it directly with curl, fetch, or any HTTP client.

For MCP-based access (no HTTP calls needed), see the MCP guide.

All endpoints live under https://api.xmemory.ai, accept JSON, and return JSON. Every request except /healthz requires a Bearer token in the Authorization header.

Please register your interest at https://xmemory.ai and we will reach out to give access. When you receive your API key, copy and securely store the key. Never share your API key publicly.

Try it

Write something, then read it back — two curl calls:

# Write
curl -X POST https://api.xmemory.ai/instances/your-instance-id/write \
  -H "Authorization: Bearer $XMEM_AUTH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Alice Johnson works at Acme Corp. Her email is alice@acme.com.",
    "extraction_logic": "deep"
  }'

# Read
curl -X POST https://api.xmemory.ai/instances/your-instance-id/read \
  -H "Authorization: Bearer $XMEM_AUTH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "What is Alice'\''s email?"
  }'
# → {"reader_result": {"answer": "alice@acme.com"}, ...}

The rest of this page covers every endpoint in detail.

Clusters

`GET /clusters`

List all clusters accessible to the authenticated user.

curl https://api.xmemory.ai/clusters \
  -H "Authorization: Bearer $XMEM_AUTH_TOKEN"

`GET /clusters/{cluster_id}`

Get a single cluster by ID.

curl https://api.xmemory.ai/clusters/your-cluster-id \
  -H "Authorization: Bearer $XMEM_AUTH_TOKEN"

Instance management

Before you can write or read, you need an instance — a memory store with a typed schema inside a cluster.

`POST /clusters/{cluster_id}/instances/generate_schema`

Generate an xmemory schema from a plain-language description:

{
  "schema_description": "Track contacts with name, email, company, and notes."
}

To refine an existing schema, pass current_yml_schema — existing objects and fields are preserved and only the described changes are applied.

`POST /clusters/{cluster_id}/instances`

Create an instance from a generated schema:

{
  "name": "contacts",
  "description": "Optional description",
  "instance_schema": {
    "yml": { "value": "..." }
  }
}

Use "yml": { "value": "..." } for YAML schemas, or "json_schema": { "value": "..." } for JSON.

Returns instance metadata including the id. Save it — you’ll pass it with every subsequent call.

`GET /instances`

List all instances accessible to the authenticated user.

curl https://api.xmemory.ai/instances \
  -H "Authorization: Bearer $XMEM_AUTH_TOKEN"

`GET /instances/{instance_id}`

Get a single instance by ID.

`GET /instances/{instance_id}/schema`

Get the current schema of an instance.

`PUT /instances/{instance_id}/schema`

Update the schema of an existing instance:

{
  "instance_schema": {
    "yml": { "value": "..." }
  }
}

`PUT /instances/{instance_id}`

Update instance metadata (name and description):

{
  "name": "new-name",
  "description": "Updated description"
}

`DELETE /instances/{instance_id}`

Delete an instance. Returns a list of deleted instance IDs.

Write

`POST /instances/{instance_id}/write`

Extract structured objects from text and persist them. Blocks until committed.

{
  "text": "Bob Lee is a designer at Globex. He joined last Monday.",
  "extraction_logic": "deep"
}

Field	Required	Description
`text`	yes	Free-form text to extract from
`extraction_logic`	no	`"deep"` (default), `"regular"`, or `"fast"`

Returns:

{
  "write_id": "...",
  "cleaned_objects": { ... },
  "diff_plan": { ... },
  "trace_id": "..."
}

cleaned_objects contains the stored objects. diff_plan shows what was inserted, updated, or deleted.

`POST /instances/{instance_id}/write_async`

Same extraction pipeline, but returns immediately instead of blocking:

{
  "text": "Carol is a senior engineer at Initech.",
  "extraction_logic": "deep"
}

Returns { "write_id": "..." }.

Important: do not read immediately after an async write — the data may not be committed yet. Poll with write_status first.

`POST /instances/{instance_id}/write_status`

Check whether an async write has finished:

{ "write_id": "..." }

Returns:

{
  "write_id": "...",
  "write_status": "completed",
  "error_detail": null,
  "completed_at": "2025-03-16T12:34:56Z"
}

write_status is one of: queued, processing, completed, failed, not_found.

Read

`POST /instances/{instance_id}/read`

Query the instance in natural language:

{
  "query": "Who joined the team recently?",
  "mode": "single-answer"
}

Field	Required	Description
`query`	yes	Natural-language question
`mode`	no	`"single-answer"` (default), `"xresponse"`, or `"raw-tables"`

The response shape depends on the mode:

Mode	`reader_result`	Best for
`single-answer`	`{"answer": "Bob Lee joined last Monday."}`	Natural-language answers
`xresponse`	`{"objects": [...], "relations": [...]}`	Structured data
`raw-tables`	`{"tables": [...]}`	Raw SQL results

Extract

`POST /instances/{instance_id}/extract`

Extract structured objects from text without storing them — useful for previewing what a write would produce:

{
  "text": "Dave manages the London office.",
  "extraction_logic": "deep"
}

Returns { "objects_extracted": { ... }, "trace_id": "..." }.

Same parameters as write.

Describe

`GET /instances/{instance_id}/describe`

Returns agent-facing tool descriptions enriched with the instance’s actual schema. Use this to tell an LLM what tools are available and how to call them.

curl https://api.xmemory.ai/instances/your-instance-id/describe \
  -H "Authorization: Bearer $XMEM_AUTH_TOKEN"

Returns:

{
  "instance_id": "...",
  "instance_name": "contacts",
  "schema_summary": "This instance tracks contacts with name, email, ...",
  "tools": [
    {
      "name": "write",
      "description": "Extract structured data from text and persist it.",
      "when_to_use": "When you need to store new facts ...",
      "parameters": [
        { "name": "text", "type": "string", "description": "...", "required": true },
        { "name": "extraction_logic", "type": "string", "description": "...", "required": false, "enum": ["fast", "regular", "deep"], "default": "deep" }
      ],
      "http_method": "POST",
      "http_path": "/instances/.../write"
    }
  ]
}

The response only includes tools the caller has permission to use. The schema_summary is a human-readable description of the instance’s schema, suitable for including in an LLM system prompt.

Health check

`GET /healthz`

Returns 200 if the API is reachable. No authentication required.

curl https://api.xmemory.ai/healthz

Errors

All endpoints return an error response on failure with the appropriate HTTP status code (400, 401, 404, 500).

Endpoint summary

Endpoint	Method	Auth	Description
`/healthz`	GET	—	Health check
`/clusters`	GET	Yes	List clusters
`/clusters/{cluster_id}`	GET	Yes	Get a cluster
`/clusters/{cluster_id}/instances/generate_schema`	POST	Yes	Generate a schema from a description
`/clusters/{cluster_id}/instances`	POST	Yes	Create a new instance
`/instances`	GET	Yes	List instances
`/instances/{instance_id}`	GET	Yes	Get an instance
`/instances/{instance_id}`	PUT	Yes	Update instance metadata
`/instances/{instance_id}`	DELETE	Yes	Delete an instance
`/instances/{instance_id}/schema`	GET	Yes	Get instance schema
`/instances/{instance_id}/schema`	PUT	Yes	Update instance schema
`/instances/{instance_id}/write`	POST	Yes	Write (synchronous)
`/instances/{instance_id}/write_async`	POST	Yes	Write (async, returns `write_id`)
`/instances/{instance_id}/write_status`	POST	Yes	Poll async write status
`/instances/{instance_id}/read`	POST	Yes	Query the instance
`/instances/{instance_id}/extract`	POST	Yes	Extract without writing
`/instances/{instance_id}/describe`	GET	Yes	Get agent-facing tool descriptions