Get started

Examples

Five first steps you can copy, paste, and run against a live eli.ai instance — each one a real request, not pseudocode. Swap https://your-host for your instance, export your key as $ELI_KEY, and every one returns exactly the shape shown. When you want the full story behind a call — every field, every error, every knob — follow its full guide link.

Before you start

Every example authenticates with Authorization: Bearer $ELI_KEY and needs the scope shown on its badge — scope always comes from the key, never a URL or body. A workspace key (eli_sk_…) carries its workspace implicitly; a user key (eli_uk_…) additionally needs an X-Workspace-Id header. No key yet? Getting started with the API mints one in a minute.

1 · Ask your first grounded question

Bearer · agents:run

One POST in, a structured, dual-cited answer out: answer with inline [Sn] markers, the answer decomposed into atomic claims, the sources registry each marker resolves to, and a dataCalls registry (empty here — add includeData: true to ground in live rows as [Dn]).

POST /api/v1/querybash

curl -s -X POST https://your-host/api/v1/query \
  -H "Authorization: Bearer $ELI_KEY" \
  -H "Content-Type: application/json" \
  -d '{"question":"How do we handle stuck orders on the Order Platform?"}'

200 · StructuredAnswerjson

{
  "answer": "Stuck orders older than 24 hours should be requeued from the fulfillment console per the incident runbook [S1].",
  "claims": [
    { "text": "Stuck orders older than 24 hours should be requeued from the fulfillment console", "citations": ["S1"] }
  ],
  "sources": [
    {
      "id": "S1",
      "docId": "01KY10AAAAAAAAAAAAAAAAAAAA",
      "docTitle": "Order Platform incident runbook",
      "docPath": "ops/order-platform-runbook.md",
      "chunkId": "01KY10BBBBBBBBBBBBBBBBBBBB",
      "snippet": "When orders remain in STUCK status for more than 24 hours, requeue them from the fulfillment console…"
    }
  ],
  "dataCalls": [],
  "entities": [
    { "id": "01KY0ZW3B8AVDR67NXSE96P81N", "name": "Order Platform", "type": "system", "pagerank": 0.0421 }
  ],
  "groundedness": { "verified": 1, "total": 1 },
  "model": { "chat": "claude-sonnet-4-5", "judge": "claude-haiku-4-5" },
  "usage": { "inputTokens": 3980, "outputTokens": 96, "costUsd": 0.0121 },
  "generatedAt": "2026-07-21T09:14:05.001Z"
}

Full guide: Search & ask →

2 · Start an agent run

Bearer · agents:run

Agents are addressed by slug. With stream: false the request blocks and returns the final RunResult as JSON — the simplest integration. Flip to stream: true (the default) for a Server-Sent Events stream of every step ending in a terminal event.

POST /api/v1/agents/{slug}/runsbash

curl -s -X POST https://your-host/api/v1/agents/budget-analyst/runs \
  -H "Authorization: Bearer $ELI_KEY" \
  -H "Content-Type: application/json" \
  -d '{"input":"What changed in the FY26 budget?","stream":false}'

200 · RunResultjson

{
  "runId": "01J8Z0R2K7WV9F2M3D5N6Q8T1B",
  "status": "succeeded",
  "text": "The FY26 budget cut the Order Platform migration line by 12% and pushed the remainder to Q3 [S1].",
  "citations": [
    { "docId": "01KY10AAAAAAAAAAAAAAAAAAAA", "chunkId": "01KY10BBBBBBBBBBBBBBBBBBBB" }
  ]
}

// a run that hit a requires-approval tool suspends instead:
// { "runId": "01J8Z0…", "status": "suspended", "approvalId": "01J8Z1…" }

Full guide: Run agents →

3 · Generate a report snapshot

Bearer · reports:write

One POST freezes the live state of the knowledge base into an immutable, client-ready snapshot. The call returns immediately with the snapshot id and a generating status; the PDF renders in the background. Fetch it back with GET /api/v1/reports/{id} (structured data is ready at once) or download …/{id}/pdf once pdf.status is ready.

POST /api/v1/reportsbash

curl -s -X POST https://your-host/api/v1/reports \
  -H "Authorization: Bearer $ELI_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title":"Northwind — Q3 engagement report"}'

200 · snapshot queuedjson

{
  "id": "01KY13DDDDDDDDDDDDDDDDDDDD",
  "title": "Northwind — Q3 engagement report",
  "status": "generating",
  "layoutVersion": "report-v4",
  "sections": ["coverage", "kpis", "topEntities", "gaps", "interviewNext"],
  "generatedAt": "2026-07-21T12:00:00.000Z",
  "pdf": { "status": "queued", "url": null }
}

Full guide: Build reports →

4 · Connect a content source

Bearer · kb:write

Register an external source as a connector — Confluence, SharePoint, or Slack. The credential is encrypted at write and never returned (reads show only hasCredential); the source starts active and does nothing until you enqueue its first sync.

POST /api/v1/connectorsbash

curl -s -X POST https://your-host/api/v1/connectors \
  -H "Authorization: Bearer $ELI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "confluence",
    "config": { "baseUrl": "https://acme.atlassian.net/wiki", "spaceKeys": ["ENG"] },
    "credential": { "email": "svc-eli@acme.com", "apiToken": "<atlassian-api-token>" }
  }'

200 · credential maskedjson

{
  "id": "01KZCONNSRC00000000000000",
  "type": "confluence",
  "status": "active",
  "config": { "baseUrl": "https://acme.atlassian.net/wiki", "spaceKeys": ["ENG"], "email": "svc-eli@acme.com" },
  "hasCredential": true,
  "lastSyncedAt": null,
  "createdAt": "2026-07-21T09:14:03.412Z"
}

POST /api/v1/connectors/{id}/syncbash

curl -s -X POST https://your-host/api/v1/connectors/01KZCONNSRC00000000000000/sync \
  -H "Authorization: Bearer $ELI_KEY" \
  -H "Content-Type: application/json" \
  -d '{"kind":"full"}'
# → { "enqueued": true, "sourceId": "01KZCONNSRC00000000000000", "kind": "full" }
# incremental syncs thereafter keep it fresh: {"kind":"incremental"}

Full guide: Connect Confluence, SharePoint & Slack →

5 · Call eli.ai from an MCP client

Bearer · eli_sk_

eli.ai is itself an MCP server at POST /api/mcp. Point Claude or any MCP client at your workspace with the same eli_sk_ key and it gets the KB, graph, and governed data layer as native, read-only tools — kb_search, kb_entity_lookup, and eli_query (the same pipeline as POST /api/v1/query), among others.

claude mcp addbash

claude mcp add --transport http eli https://your-host/api/mcp \
  --header "Authorization: Bearer eli_sk_..."

MCP client configjson

{
  "mcpServers": {
    "eli": {
      "type": "http",
      "url": "https://your-host/api/mcp",
      "headers": {
        "Authorization": "Bearer eli_sk_..."
      }
    }
  }
}

Then ask naturally — "Using the eli tools, what do we know about the Order Platform, and is anything stuck right now?" — and the client chains the tools for you. The endpoint-by-endpoint reference is in MCP server.

Full guide: MCP quickstart →

Where to next

These are the opening moves. Browse every operation in the OpenAPI reference, fire real requests from the API playground, or start from the API overview for the full map of task guides.