> For the complete documentation index, see [llms.txt](https://k-ai.gitbook.io/knowledge-ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://k-ai.gitbook.io/knowledge-ai/sources-and-ingestion/instance-api/documents.md).

# Documents

The Documents endpoints expose metadata and indexation status for files in the instance.

Authenticated with `instance-id` + `api-key` headers — see [Instance API keys](/knowledge-ai/authentication/api-keys.md).

***

## POST /api/document/list-docs

List documents from the index with pagination and optional state filtering. Results may differ from the Document Repository if a differential indexation has not been launched since the last changes.

Valid states: `INITIAL_SAVED`, `UPDATED`, `ON_CONTENT_EXTRACT`, `CONTENT_EXTRACTED`, `PARSING_ERROR`, `ON_INDEXATION`, `INDEXED`.

{% openapi src="/files/ggZwaT7KDX2BbCKblljY" path="/api/document/list-docs" method="post" %}
[instance-api.yaml](https://3937809777-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F85gF5n5kGsNQKMPwm2VR%2Fuploads%2Fgit-blob-f10c7aa7b61beb8fa154e76dc42db38f2d85f9f0%2Finstance-api.yaml?alt=media\&token=79231d80-f551-4804-9087-efd6ceda9ab9)
{% endopenapi %}

{% tabs %}
{% tab title="curl" %}

```bash
curl -X POST https://api.kai-studio.ai/api/document/list-docs \
  -H "instance-id: <YOUR_INSTANCE_ID>" \
  -H "api-key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{"offset": 0, "limit": 20, "state": "INDEXED"}'
```

{% endtab %}

{% tab title="Python" %}

```python
import httpx

response = httpx.post(
    "https://api.kai-studio.ai/api/document/list-docs",
    headers={
        "instance-id": "<YOUR_INSTANCE_ID>",
        "api-key": "<YOUR_API_KEY>",
    },
    json={"offset": 0, "limit": 20, "state": "INDEXED"},
)
response.raise_for_status()
for doc in response.json()["response"]:
    print(doc["id"], doc["name"])
```

{% endtab %}

{% tab title="TypeScript" %}

```ts
const response = await fetch(
  "https://api.kai-studio.ai/api/document/list-docs",
  {
    method: "POST",
    headers: {
      "instance-id": "<YOUR_INSTANCE_ID>",
      "api-key": "<YOUR_API_KEY>",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ offset: 0, limit: 20, state: "INDEXED" }),
  },
);
if (!response.ok) throw new Error(`HTTP ${response.status}`);
const { response: docs } = await response.json();
console.log(docs);
```

{% endtab %}
{% endtabs %}

Each item has `id`, `name`, and `extraproperties` (a dictionary of metadata set during ingestion — audit counters, indexation state, chunk count, KB signature, and KB-specific fields).

***

## POST /api/document/doc

Retrieve detailed information about a single document by its ID. Returns `id`, `name`, the storage `url`, an auto-generated `resume`, and the `extraproperties` dictionary.

{% openapi src="/files/ggZwaT7KDX2BbCKblljY" path="/api/document/doc" method="post" %}
[instance-api.yaml](https://3937809777-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F85gF5n5kGsNQKMPwm2VR%2Fuploads%2Fgit-blob-f10c7aa7b61beb8fa154e76dc42db38f2d85f9f0%2Finstance-api.yaml?alt=media\&token=79231d80-f551-4804-9087-efd6ceda9ab9)
{% endopenapi %}

{% tabs %}
{% tab title="curl" %}

```bash
curl -X POST https://api.kai-studio.ai/api/document/doc \
  -H "instance-id: <YOUR_INSTANCE_ID>" \
  -H "api-key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{"id": "doc_abc123"}'
```

{% endtab %}

{% tab title="Python" %}

```python
import httpx

response = httpx.post(
    "https://api.kai-studio.ai/api/document/doc",
    headers={
        "instance-id": "<YOUR_INSTANCE_ID>",
        "api-key": "<YOUR_API_KEY>",
    },
    json={"id": "doc_abc123"},
)
response.raise_for_status()
print(response.json()["response"])
```

{% endtab %}

{% tab title="TypeScript" %}

```ts
const response = await fetch("https://api.kai-studio.ai/api/document/doc", {
  method: "POST",
  headers: {
    "instance-id": "<YOUR_INSTANCE_ID>",
    "api-key": "<YOUR_API_KEY>",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ id: "doc_abc123" }),
});
if (!response.ok) throw new Error(`HTTP ${response.status}`);
console.log(await response.json());
```

{% endtab %}
{% endtabs %}

***

## POST /api/document/download

Download the original file from storage. Returns a binary stream (`application/octet-stream`).

{% openapi src="/files/ggZwaT7KDX2BbCKblljY" path="/api/document/download" method="post" %}
[instance-api.yaml](https://3937809777-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F85gF5n5kGsNQKMPwm2VR%2Fuploads%2Fgit-blob-f10c7aa7b61beb8fa154e76dc42db38f2d85f9f0%2Finstance-api.yaml?alt=media\&token=79231d80-f551-4804-9087-efd6ceda9ab9)
{% endopenapi %}

```bash
curl -X POST https://api.kai-studio.ai/api/document/download \
  -H "instance-id: <YOUR_INSTANCE_ID>" \
  -H "api-key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{"id": "doc_abc123"}' \
  -o downloaded-file.pdf
```

***

## POST /api/document/docs-by-ids

Retrieve document information for a list of IDs. Supports pagination. Each returned item carries the same fields as `/api/document/doc` plus a computed `url`.

{% openapi src="/files/ggZwaT7KDX2BbCKblljY" path="/api/document/docs-by-ids" method="post" %}
[instance-api.yaml](https://3937809777-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F85gF5n5kGsNQKMPwm2VR%2Fuploads%2Fgit-blob-f10c7aa7b61beb8fa154e76dc42db38f2d85f9f0%2Finstance-api.yaml?alt=media\&token=79231d80-f551-4804-9087-efd6ceda9ab9)
{% endopenapi %}

***

## POST /api/document/count-documents

Count documents in the index, optionally filtered by state and/or a list of document IDs. Valid states match those of `list-docs`.

{% openapi src="/files/ggZwaT7KDX2BbCKblljY" path="/api/document/count-documents" method="post" %}
[instance-api.yaml](https://3937809777-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F85gF5n5kGsNQKMPwm2VR%2Fuploads%2Fgit-blob-f10c7aa7b61beb8fa154e76dc42db38f2d85f9f0%2Finstance-api.yaml?alt=media\&token=79231d80-f551-4804-9087-efd6ceda9ab9)
{% endopenapi %}

***

## POST /api/document/count-documents-per-date

Get document counts grouped by date. Returns a dictionary mapping `YYYY-MM-DD` strings to integer counts.

{% openapi src="/files/ggZwaT7KDX2BbCKblljY" path="/api/document/count-documents-per-date" method="post" %}
[instance-api.yaml](https://3937809777-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F85gF5n5kGsNQKMPwm2VR%2Fuploads%2Fgit-blob-f10c7aa7b61beb8fa154e76dc42db38f2d85f9f0%2Finstance-api.yaml?alt=media\&token=79231d80-f551-4804-9087-efd6ceda9ab9)
{% endopenapi %}

***

## POST /api/document/kb-meta-fields

Retrieve all metadata fields available from the Document Repository for a given document. The returned dictionary contains field names and their values as configured on the source connector; the exact shape depends on the connector and is not statically typed.

{% openapi src="/files/ggZwaT7KDX2BbCKblljY" path="/api/document/kb-meta-fields" method="post" %}
[instance-api.yaml](https://3937809777-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F85gF5n5kGsNQKMPwm2VR%2Fuploads%2Fgit-blob-f10c7aa7b61beb8fa154e76dc42db38f2d85f9f0%2Finstance-api.yaml?alt=media\&token=79231d80-f551-4804-9087-efd6ceda9ab9)
{% endopenapi %}

{% tabs %}
{% tab title="curl" %}

```bash
curl -X POST https://api.kai-studio.ai/api/document/kb-meta-fields \
  -H "instance-id: <YOUR_INSTANCE_ID>" \
  -H "api-key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{"id": "doc_abc123"}'
```

{% endtab %}

{% tab title="Python" %}

```python
import httpx

response = httpx.post(
    "https://api.kai-studio.ai/api/document/kb-meta-fields",
    headers={
        "instance-id": "<YOUR_INSTANCE_ID>",
        "api-key": "<YOUR_API_KEY>",
    },
    json={"id": "doc_abc123"},
)
response.raise_for_status()
print(response.json()["response"])
```

{% endtab %}

{% tab title="TypeScript" %}

```ts
const response = await fetch(
  "https://api.kai-studio.ai/api/document/kb-meta-fields",
  {
    method: "POST",
    headers: {
      "instance-id": "<YOUR_INSTANCE_ID>",
      "api-key": "<YOUR_API_KEY>",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ id: "doc_abc123" }),
  },
);
if (!response.ok) throw new Error(`HTTP ${response.status}`);
console.log(await response.json());
```

{% endtab %}
{% endtabs %}

Response shape (per the OpenAPI spec): `{"response": <object>}` where the value is an open-ended dictionary of metadata field names to their values. Refer to the source connector for the expected fields.

***

## POST /api/document/parsing-blocks

Retrieve the parsed content blocks produced by the file parser for a document. Each block has an `id` (formatted as `{document_id}_{index}`) and `content` (text). Supports pagination.

{% openapi src="/files/ggZwaT7KDX2BbCKblljY" path="/api/document/parsing-blocks" method="post" %}
[instance-api.yaml](https://3937809777-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F85gF5n5kGsNQKMPwm2VR%2Fuploads%2Fgit-blob-f10c7aa7b61beb8fa154e76dc42db38f2d85f9f0%2Finstance-api.yaml?alt=media\&token=79231d80-f551-4804-9087-efd6ceda9ab9)
{% endopenapi %}