> ## Documentation Index
> Fetch the complete documentation index at: https://docs.impellabs.tech/llms.txt
> Use this file to discover all available pages before exploring further.

# Knowledge ingestion

> Publishing a stored document into the index an agent retrieves from — and withdrawing it.

`POST /api/v2/knowledge/ingestions` is the one place on the platform where a
stored [document](/v2/documents) 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.

```bash theme={null}
curl "$IMPEL_API/knowledge/ingestions" \
  -H "Authorization: Bearer $IMPEL_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 5e77…" \
  -d '{
    "document_id": "doc_…",
    "knowledge_group": "grp_policies"
  }'
```

Answers **202** with a `job_id`. See [Jobs](/v2/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` | Declared on the route — publishing and withdrawing                           |
| `documents:read`  | Checked in the service — you must be allowed to read what you are publishing |

<Warning>
  `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.
</Warning>

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

```bash theme={null}
curl "$IMPEL_API/knowledge/ingestions/kin_…" -H "Authorization: Bearer $IMPEL_KEY"
```

```json theme={null}
{
  "object": "knowledge_ingestion",
  "id": "kin_…",
  "status": "completed",
  "document_id": "doc_…",
  "document_filename": "returns-policy-2026.pdf",
  "knowledge": {
    "scope": "group",
    "group_id": "…",
    "requested_group": "grp_policies",
    "chunk_count": 42,
    "character_count": 61220,
    "indexed": true
  },
  "processing": { "…": "…" }
}
```

`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

```bash theme={null}
curl -X DELETE "$IMPEL_API/knowledge/ingestions/kin_…" \
  -H "Authorization: Bearer $IMPEL_KEY"
```

Needs `knowledge:write`.

<Note>
  `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`.
</Note>

## Listing

```bash theme={null}
curl "$IMPEL_API/knowledge/ingestions?limit=50" -H "Authorization: Bearer $IMPEL_KEY"
```

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.

## Related

<CardGroup cols={2}>
  <Card title="Knowledge concepts" icon="book" href="/concepts/knowledge">
    What a knowledge group is, how retrieval works, and what an agent is allowed
    to quote.
  </Card>

  <Card title="Documents" icon="file" href="/v2/documents">
    Getting the file in, and reading the representation this indexes.
  </Card>
</CardGroup>