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/write \
  -H "Authorization: Bearer $XMEM_AUTH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "instance_id": "your-instance-id",
    "text": "Alice Johnson works at Acme Corp. Her email is alice@acme.com.",
    "extraction_logic": "deep"
  }'

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

The rest of this page covers every endpoint in detail.

---

Instance management

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

POST /instance/generate_schema

Generate an xmemory schema from a plain-language description:

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

Returns { "status": "ok", "generated_schema": { ... } }.

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

POST /instance/create

Create an instance from a generated schema. Pass either yml_schema or json_schema:

{ "yml_schema": "..." }

Returns { "status": "ok", "instance_id": "inst_abc123" }.

Save the instance_id — you’ll pass it with every subsequent call.

POST /instance/update

Update the schema of an existing instance:

{
  "instance_id": "inst_abc123",
  "yml_schema": "..."
}

Returns { "status": "ok" }.

---

Write

POST /write

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

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

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

Returns:

{
  "status": "ok",
  "extract_write_id": "ew_...",
  "cleaned_objects": { ... },
  "diff_plan": { ... }
}

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

POST /write_async

Same extraction pipeline, but returns immediately instead of blocking:

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

Returns { "status": "ok", "write_id": "wq_..." }.

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

POST /write_status

Check whether an async write has finished:

{ "write_id": "wq_..." }

Returns:

{
  "status": "ok",
  "write_id": "wq_...",
  "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 /read

Query the instance in natural language:

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

Field	Required	Description
instance_id	yes	Instance to query
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 /extract

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

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

Returns { "status": "ok", "objects_extracted": { ... } }.

Same parameters as /write.

---

Health check

GET /healthz

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

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

---

Errors

All endpoints return { "status": "error", "error_message": "..." } on failure with the appropriate HTTP status code (400, 401, 404, 500).

---

Endpoint summary

Endpoint	Method	Auth	Description
/healthz	GET	—	Health check
/instance/generate_schema	POST	Yes	Generate a schema from a description
/instance/create	POST	Yes	Create a new instance
/instance/update	POST	Yes	Update an instance’s schema
/write	POST	Yes	Write (synchronous)
/write_async	POST	Yes	Write (async, returns write_id)
/write_status	POST	Yes	Poll async write status
/read	POST	Yes	Query the instance
/extract	POST	Yes	Extract without writing