REST API

Document bases

A document base is a set of documents that gets read once and then answers questions. Create one, read its readiness counts, delete it and everything in it.

A document base is the unit everything else hangs off: documents go into it, onboarding compiles it, questions are asked of it, and MCP clients connect to it. Most workspaces run a handful, split by audience rather than by size.

Create a document base

curl -X POST https://api.engramdynamics.org/v1/corpora \
  -H "Authorization: Bearer <your key>" \
  -H "Content-Type: application/json" \
  -d '{"name": "Support handbook", "source_type": "upload"}'

Requires the ingest scope. The name is how a person and the CLI address the base, so it is trimmed, has to be between 1 and 200 characters, and has to be unique within the workspace, compared without case. A clash is a 409 that hands you the base you already have:

{
  "error": {
    "code": "duplicate_name",
    "message": "A document base named 'Support handbook' already exists in this workspace. Pick a different name, or open the existing one.",
    "status": 409,
    "details": {"existing_id": "c_7a1f..."},
    "request_id": "8c0b..."
  }
}

source_type is a label for where the documents come from and defaults to upload. Creating a base is also where the workspace entitlements are checked: a confirmed email address, an active plan, and the workspace allowance on Plans and allowances.

Read one, or list them all

curl "https://api.engramdynamics.org/v1/corpora?limit=50" \
  -H "Authorization: Bearer <your key>"

curl https://api.engramdynamics.org/v1/corpora/c_7a1f... \
  -H "Authorization: Bearer <your key>"

The listing is paginated, newest first. Both routes return the same object:

Field	Meaning
`id`, `name`, `created_at`	Identity.
`status`	The base's own lifecycle: `new`, `training`, `ready` or `failed`.
`n_documents`	Files in the base. Counts files, never the internal pieces a long file is served in.
`documents_ready`	Documents with memory built. This is what an answer can draw on.
`documents_onboarding`	Documents parsing, queued, building, or changed and not yet rebuilt.
`documents_failed`	Documents that could not be read or built. They need attention.
`last_synced_at`	When the newest ready document last changed state, so you can answer "how fresh is this".
`n_cartridges`, `train_seconds`, `corpus_tokens`	Measured results of the last onboarding run.

Readiness is per document, not per base

A base answers as soon as one document has memory built. Adding a file never takes the base offline: the new document is unavailable until its build lands, and everything already built keeps answering. So poll documents_ready and documents_onboarding rather than waiting for status to say ready, and show progress from those numbers. The same three counts ride on every answer, so an agent can see mid-conversation that three documents are still coming.

base = requests.get(f"{BASE}/corpora/{base_id}", headers=HEADERS, timeout=30).json()
if base["documents_onboarding"]:
    print(f"{base['documents_ready']} ready, {base['documents_onboarding']} still onboarding")

Reaching a base from an agent

Agents reach a document base through Engram's hosted MCP server rather than through a credential of their own. One connection covers the whole workspace and the base is a tool argument, so an agent that should see this base needs nothing more than a workspace API key with the query scope. Setup is on MCP quick start.

Delete a document base

curl -X DELETE https://api.engramdynamics.org/v1/corpora/c_7a1f... \
  -H "Authorization: Bearer <your key>"

Answers 204. The delete is the real thing, not a flag: raw files, extracted text, the retrieval index, the database rows, the built memory and every warm copy of it on the serving hardware. A cartridge another live document in the workspace still serves is kept, which is the one deliberate exception. What survives is the audit receipt, because that is the proof the deletion happened. See Data lifecycle and deletion for the full timeline.

Put documents in it: Documents and ingest.