Ingestion

What this family does

Ingestion accepts raw text, batches of items, and uploaded files: chat exports, documents and transcripts. Nothing is processed inline. Every route validates and durably queues the work, then returns a job id, and a background worker chunks, embeds and links the content into the knowledge graph. Poll GET /v1/ingest/{job_id}/status for one job’s progress, GET /v1/jobs for the cross-family view, or subscribe to the job.completed event and stop polling.

Routes

Method	Path	Scope	What it does
`GET`	`/v1/import`	`read`	List imports
`POST`	`/v1/import`	`write`	Import a file
`POST`	`/v1/import/transcript`	`write`	Import a transcript
`POST`	`/v1/ingest`	`write`	Ingest content
`POST`	`/v1/ingest/batch`	`write`	Ingest a batch of content items
`GET`	`/v1/ingest/{job_id}/status`	`read`	Get ingest job status

Headers that apply here

Neither header is declared as an OpenAPI parameter, so neither appears in the generated schema tables.

X-Exo-Subject selects which subject the call acts for on the subject-aware routes above. Omit it to act as the key owner. See Subjects.
Idempotency-Key makes a retry safe on POST /v1/ingest, POST /v1/ingest/batch. See Idempotency.

The shape of a call

Ingest a piece of content.

curl -X POST https://api.get-exo.com/v1/ingest \
  -H "X-Exo-API-Key: $EXO_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 8f14e45fceea167a" \
  -d '{"content": "We dropped the freemium tier. Too much support load."}'

import httpx

response = httpx.post(
    "https://api.get-exo.com/v1/ingest",
    headers={"X-Exo-API-Key": EXO_KEY, "Idempotency-Key": "8f14e45fceea167a"},
    json={"content": "We dropped the freemium tier. Too much support load."},
)
job_id = response.json()["jobId"]

const response = await fetch("https://api.get-exo.com/v1/ingest", {
  method: "POST",
  headers: {
    "X-Exo-API-Key": process.env.EXO_KEY!,
    "Content-Type": "application/json",
    "Idempotency-Key": "8f14e45fceea167a",
  },
  body: JSON.stringify({ content: "We dropped the freemium tier. Too much support load." }),
});
const { jobId } = await response.json();

The response:

{
  "jobId": "b1f0c6d2-8a44-4b21-9a1e-6d1f0c6d28a441a8",
  "status": "pending"
}

Traps

202 means queued, not stored. Content is not retrievable until the job reaches a terminal status: neither pending nor running on GET /v1/ingest/{job_id}/status (that route’s own vocabulary calls the finished state done), or succeeded on GET /v1/jobs/{job_id}. A retrieve run straight after an accept returns the graph as it was before. Send Idempotency-Key on the JSON routes. POST /v1/ingest and POST /v1/ingest/batch replay. The two import routes take multipart form data and do not, because the replay engine fingerprints a JSON body. GET /v1/import is history, not job status. It lists the 20 most recent imports for the effective subject. nodesCreated and domainsDetected stay null until the worker finishes.

API reference

Base URL, authentication, and the conventions every route shares.

Errors

The problem envelope and the full code catalogue.

​What this family does

​Routes

​Headers that apply here

​The shape of a call

​Traps

​Related