Skip to main content
POST /api/v2/knowledge/ingestions is the one place on the platform where a stored document becomes knowledge — something an agent can retrieve and quote. Uploading a file does not do this. Extracting fields from it does not do this. Publication is a deliberate, separate act, and this endpoint is the whole of it.
Answers 202 with a job_id. See Jobs.

​
Exactly two fields are read

document_id and knowledge_group. Both are requests rather than authority:
  • document_id names a document resolved inside your own isolation boundary.
  • knowledge_group names the body of knowledge it lands in.
Everything else in the body is ignored. A key this API does not know about must not be assignable.

​
It needs two scopes, not one

knowledge:write has never implied documents:read, and documents:create has never implied either. A key that can put files into the platform cannot thereby make them retrievable by an agent, and a key that can publish cannot thereby read the document it names.
The second scope is enforced in the service rather than on the route because it is a fact about the operation rather than about the URL.

​
The resource

scope is the word — group or company_wide — and it is stored alongside group_id so both survive. group_id is null for the company-wide case and for a group that has since been deleted; scope still says which was asked for, which is why both are kept. indexed is the field to check. Until it is true, the document is stored but no agent will retrieve from it. Reading needs knowledge:read.

​
Withdrawing

Needs knowledge:write.
DELETE withdraws the knowledge. It does not delete the document.Publication is a deliberate act, and a deliberate act with no undo is a one-way door — but the undo has to stop at the same line the publication crossed. Deleting the file is DELETE /documents/{id}, which needs documents:delete.

​
Listing

Needs knowledge:read. Returns next_cursor, read back as cursor.

​
Errors are never an oracle

A cross-workspace document, another environment’s ingestion, a knowledge group belonging to somebody else, and an id that was never issued all produce the same 404. A refusal from the execution context is a 403 about your scopes, which reveals nothing about whether any object exists.

Knowledge concepts

What a knowledge group is, how retrieval works, and what an agent is allowed to quote.

Documents

Getting the file in, and reading the representation this indexes.