> 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-8f3d896df32794f28ab6f557a94cbd117983f7c2%2Finstance-api.yaml?alt=media) {% endopenapi %} {% tabs %} {% tab title="curl" %} ```bash curl -X POST https://api.kai-studio.ai/api/document/list-docs \ -H "instance-id: " \ -H "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": "", "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": "", "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-8f3d896df32794f28ab6f557a94cbd117983f7c2%2Finstance-api.yaml?alt=media) {% endopenapi %} {% tabs %} {% tab title="curl" %} ```bash curl -X POST https://api.kai-studio.ai/api/document/doc \ -H "instance-id: " \ -H "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": "", "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": "", "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-8f3d896df32794f28ab6f557a94cbd117983f7c2%2Finstance-api.yaml?alt=media) {% endopenapi %} ```bash curl -X POST https://api.kai-studio.ai/api/document/download \ -H "instance-id: " \ -H "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-8f3d896df32794f28ab6f557a94cbd117983f7c2%2Finstance-api.yaml?alt=media) {% 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-8f3d896df32794f28ab6f557a94cbd117983f7c2%2Finstance-api.yaml?alt=media) {% 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-8f3d896df32794f28ab6f557a94cbd117983f7c2%2Finstance-api.yaml?alt=media) {% 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-8f3d896df32794f28ab6f557a94cbd117983f7c2%2Finstance-api.yaml?alt=media) {% endopenapi %} {% tabs %} {% tab title="curl" %} ```bash curl -X POST https://api.kai-studio.ai/api/document/kb-meta-fields \ -H "instance-id: " \ -H "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": "", "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": "", "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": }` 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-8f3d896df32794f28ab6f557a94cbd117983f7c2%2Finstance-api.yaml?alt=media) {% endopenapi %} --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://k-ai.gitbook.io/knowledge-ai/sources-and-ingestion/instance-api/documents.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.