Skip to documentation
eli.aidocs

Intake

Ingest documents

Documents are the raw material of the knowledge base. Post markdown to /api/v1/documents and eli.ai commits the vault save, chunks, and full-text index before returning 201. Embedding and graph enrichment continue as detached work. This guide covers the full lifecycle: create, list, read, update, delete, and what the storage response does and does not guarantee.

Prerequisites

  • A key with kb:write (to create/update/delete) and kb:read (to list/read). See Getting started.
  • For a cross-workspace user key, an X-Workspace-Id header on every request.

Create a document

Supply markdown content and, normally, a vault path. The path may be omitted and derived; content may be omitted when creating a titled placeholder. The response is stored-document metadata only: docId, normalized path, content hash, and title.

POST/api/v1/documentsBearer · kb:write

Save markdown through the vault. The file, metadata, chunks, and full-text index commit before 201; embedding warm-up is detached and extraction is handed to the worker queue.

Request body

pathstringVault path, e.g. northwind/interviews/cfo-2026-03.md. Folders are implicit; omitting it derives a unique path.
contentstringMarkdown body. Defaults to a one-heading note when omitted.
titlestringUsed for the default heading when content is omitted. Stored title otherwise comes from frontmatter, the first H1, or the filename.
Example requestbash
curl -s -X POST https://your-host/api/v1/documents \
  -H "Authorization: Bearer $ELI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "path": "northwind/interviews/cfo-2026-03.md",
    "title": "CFO interview — March 2026",
    "content": "# CFO interview\n\nWe reviewed the [[FY26 Budget]] with [[Dana Whitfield]], CFO of [[Northwind Trading Co]]. The Order Platform migration is the top cost driver this quarter."
  }'
Responsejson
{
  "docId": "01KY10AAAAAAAAAAAAAAAAAAAA",
  "path": "northwind/interviews/cfo-2026-03.md",
  "contentHash": "5d41402abc4b2a76b9719d911017c5925d41402abc4b2a76b9719d911017c592",
  "title": "CFO interview"
}

201 is storage readiness, not enrichment readiness

The response intentionally has no chunk count, entity count, status, or freshness field. Chunks and FTS are already committed; embeddings and entity/relation extraction are detached. Read the document immediately, and treat graph/search enrichment as eventually available work rather than inferring it from this payload.

From document to graph

The 201 means the vault file, document metadata, chunks, and full-text index have committed. Embedding warm-up is started without delaying the response, and entity/relation extraction is handed to the worker queue. The create payload does not report either enrichment stage.

Storage, chunks, and FTS commit first; enrichment continues independently.

Extraction is what turns prose into structure: it reads the chunks, proposes entities and typed relations, and links each to the chunk it came from as a mention. Crucially, extraction reuses existing entities by normalized name — so a document that mentions "Northwind Trading Co" attaches to the same entity a prior document or a manual edit already created, rather than duplicating it. Read the model in Entity graph.

List & read

GET/api/v1/documentsBearer · kb:read

List live, ACL-visible documents alphabetically by path. Paginate with limit/offset.

Query parameters

limitintegerPage size, 1–200. Default 50.
offsetintegerRows to skip. Default 0.
Example requestbash
curl -s "https://your-host/api/v1/documents?limit=2&offset=0" \
  -H "Authorization: Bearer $ELI_KEY"
Responsejson
{
  "items": [
    {
      "id": "01KY10AAAAAAAAAAAAAAAAAAAA",
      "path": "northwind/interviews/cfo-2026-03.md",
      "title": "CFO interview",
      "contentHash": "5d41402abc4b2a76b9719d911017c5925d41402abc4b2a76b9719d911017c592",
      "version": 1,
      "updatedAt": "2026-07-21T09:14:03.412Z"
    }
  ],
  "total": 1,
  "limit": 2,
  "offset": 0
}
GET/api/v1/documents/{id}Bearer · kb:read

Fetch stored metadata plus full markdown content. missing is true when metadata exists but the vault file cannot be read. An id in another workspace is invisible under RLS → 404.

Example requestbash
curl -s https://your-host/api/v1/documents/01KY10AAAAAAAAAAAAAAAAAAAA \
  -H "Authorization: Bearer $ELI_KEY"
Responsejson
{
  "id": "01KY10AAAAAAAAAAAAAAAAAAAA",
  "path": "northwind/interviews/cfo-2026-03.md",
  "title": "CFO interview",
  "contentHash": "5d41402abc4b2a76b9719d911017c5925d41402abc4b2a76b9719d911017c592",
  "version": 1,
  "updatedAt": "2026-07-21T09:14:03.412Z",
  "content": "# CFO interview\n\nWe reviewed the [[FY26 Budget]]…",
  "missing": false
}

Update

PATCHrequires the complete replacement content. It commits the updated file, chunks, full-text index, revision, and audit row before responding, then starts the same detached embedding and extraction work. Extraction replaces the document's prior machine projection atomically when it runs.

PATCH/api/v1/documents/{id}Bearer · kb:write

Replace a document's markdown content. The durable save/chunk/FTS work commits before the response; enrichment is detached.

Request body

contentrequiredstringComplete replacement markdown body.
Example requestbash
curl -s -X PATCH https://your-host/api/v1/documents/01KY10AAAAAAAAAAAAAAAAAAAA \
  -H "Authorization: Bearer $ELI_KEY" \
  -H "Content-Type: application/json" \
  -d '{"content":"# CFO interview\n\nUpdated: the Order Platform migration slipped to Q3."}'
Responsejson
{
  "docId": "01KY10AAAAAAAAAAAAAAAAAAAA",
  "path": "northwind/interviews/cfo-2026-03.md",
  "contentHash": "8ad8757baa8564dc136c1e07507f4a985afee1f5d9ad91c8c1e4a5d1bd443d8e",
  "title": "CFO interview"
}

Delete

Deletion moves the file toward recoverable vault trash and commits the document tombstone, graph-provenance cleanup, chunk/vector removal, terminal revision, and audit event as one database transaction. That atomic cleanup prevents retrieval from seeing a half-deleted graph or index. See the full cascade in Export & offboarding.

DELETE/api/v1/documents/{id}Bearer · kb:write

Soft-delete a document; atomically tombstone metadata and remove graph/chunk-derived data.

Example requestbash
curl -s -X DELETE https://your-host/api/v1/documents/01KY10AAAAAAAAAAAAAAAAAAAA \
  -H "Authorization: Bearer $ELI_KEY"
Responsejson
{ "deleted": true, "id": "01KY10AAAAAAAAAAAAAAAAAAAA" }

Errors

400 for invalid JSON, pagination, path, or a PATCH without required content; 401 for a bad key, 403 when the key lacks kb:write, and 404 for an unknown or other-workspace id. Details in Errors & rate limits.

The leverage

One POST is a document; a stream of them is a self-organizing knowledge graph. Point your CRM, ticket system, or meeting-notes pipeline at this endpoint and every artifact becomes searchable through committed FTS when it lands and available to semantic/graph retrieval as detached enrichment completes — with no schema required up front because extraction discovers the structure. Then ask questions of everything you've fed in, or curate the graph by hand where extraction needs a human's judgment.