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.

curl -s -L -X POST https://eli.ai/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."
  }'

{
  "docId": "01KY10AAAAAAAAAAAAAAAAAAAA",
  "path": "northwind/interviews/cfo-2026-03.md",
  "contentHash": "5d41402abc4b2a76b9719d911017c5925d41402abc4b2a76b9719d911017c592",
  "title": "CFO interview"
}

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.

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

curl -s "https://eli.ai/api/v1/documents?limit=2&offset=0" \
  -H "Authorization: Bearer $ELI_KEY"

{
  "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
}

curl -s https://eli.ai/api/v1/documents/01KY10AAAAAAAAAAAAAAAAAAAA \
  -H "Authorization: Bearer $ELI_KEY"

{
  "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.

curl -s -L -X PATCH https://eli.ai/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."}'

{
  "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.

curl -s -L -X DELETE https://eli.ai/api/v1/documents/01KY10AAAAAAAAAAAAAAAAAAAA \
  -H "Authorization: Bearer $ELI_KEY"

{ "deleted": true, "id": "01KY10AAAAAAAAAAAAAAAAAAAA" }

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.