Ingest knowledge documents
Load documents into a vector store for retrieval.
A vector store holds documents, their extracted text, and the embeddings used for semantic search. Ingestion is asynchronous: the upload returns immediately and a background job does extraction, chunking and embedding.
Steps
1. Open /knowledge-base for stores and their ingestion jobs, or
/vector-stores for the per-store document inventory.
2. Open a store to see its documents, each with a status.
3. Upload. Binary formats (PDF, DOCX, PPTX, ZIP) are routed through the OCR dispatcher; text formats are ingested directly. Archives are expanded and their members ingested individually.
4. Watch the status. A document moves pending → processing → completed
or failed. The list polls while any row is non-terminal.
Reading document status
| Status | Meaning |
|---|---|
pending | Row created, not yet linked to a job |
processing | A job owns it; extraction/embedding in progress |
completed | Chunks written and searchable |
failed | Terminal; the error field says why |
Every document that enters processing must reach a terminal state. If one
sits in processing indefinitely with an empty error, that is a defect, not a
slow job — see the diagnosis section below.
Choosing the embedding model
The gateway’s DEFAULT_EMBEDDING_MODEL must match the model a corpus was
embedded with. Mismatch does not error — it silently returns irrelevant results,
because query and document vectors land in different spaces. This is the single
most expensive misconfiguration on this path, precisely because it looks like a
relevance problem rather than a config one.
Diagnosing a document that never finishes
Work through these in order:
1. Is a job actually running? Check /knowledge-base for the job’s status.
A job stuck at queued with no started_at is not being claimed — the
processor is not picking it up.
2. Did extraction produce text? A document whose extraction yields nothing is
failed with extraction produced no text. Common for scanned PDFs when no OCR
provider is configured.
3. Is the source fetchable? Jobs ingesting from a URL fail with
unsupported protocol scheme "" when the stored source is a bare filename
rather than a URL. This affects documents queued by older reprocess runs.
4. Was it reprocessed? Reprocess re-runs extraction. It does not
re-derive stored metadata such as content_type, so a document displaying the
wrong type keeps displaying it after a reprocess.
If a document is stuck with an empty error and none of the above applies,
capture its job_id and the store id before re-uploading — re-uploading loses
the evidence needed to diagnose it.
Correcting a wrong content type
Documents ingested before content-type sniffing was tightened can display a
generic type (text/plain) for a file that is plainly not text. The stored value
is corrected with PATCH /v1/vector_stores/{id}/documents/{docID}:
curl -X PATCH https://<gateway>/v1/vector_stores/vs_abc123/documents/<docID> \
-H "X-Aoedge-Identity-Context: <attested context>" \
-H "Content-Type: application/json" \
-d '{"content_type": "application/pdf"}'
For a bulk correction across every store and tenant schema, use the
backfill-content-type tool. Run it with -dry-run first; it only rewrites
values that are generic and disagree with the filename, and never overwrites a
specific stored type.
Search behaviour
Search combines vector similarity with the GraphRAG layer where entities and
relationships have been extracted. /search-logs records queries and what they
matched — the fastest way to tell “the corpus lacks this content” from “the query
is not retrieving it”.