> 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/k-ai-audit/api-reference/documents.md).

# Documents & indexation

List and manage documents within an audit instance, look up metadata by id, assign owners, monitor indexation state, and aggregate per-document AI recommendations. When the instance has `need_detect_owner_document_feature` enabled, non-admin users only see documents they own.

This page covers 6 operations.

Auth: OAuth 2.1 Bearer token (MCP) or the `kai_auth` HttpOnly cookie (browsers) — see [OAuth 2.1](/knowledge-ai/authentication/oauth.md).

***

## audit\_documents\_list

`POST /audit/document/list`

Paginated list of audit-side document records (each carries `document_id`, `instance_id`, `document_owner`, and free-form `extraproperties`). When `need_detect_owner_document_feature` is enabled, non-admin callers only see documents assigned to them.

{% openapi src="/files/LsPumOBZAN25uU285Xuz" path="/audit/document/list" method="post" %}
[audit-api.yaml](https://3937809777-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F85gF5n5kGsNQKMPwm2VR%2Fuploads%2Fgit-blob-00a25a57ce88a8c396c05c4686ed7c88c8fa834a%2Faudit-api.yaml?alt=media)
{% endopenapi %}

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

```bash
curl -X POST https://api-audit.kai-studio.ai/audit/document/list \
  -H "Authorization: Bearer <YOUR_ACCESS_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"instance_id": "ki_abc123", "offset": 0, "limit": 50}'
```

{% endtab %}

{% tab title="Python" %}

```python
import httpx

response = httpx.post(
    "https://api-audit.kai-studio.ai/audit/document/list",
    headers={"Authorization": f"Bearer {access_token}"},
    json={"instance_id": "ki_abc123", "offset": 0, "limit": 50},
)
response.raise_for_status()
print(response.json())
```

{% endtab %}

{% tab title="TypeScript" %}

```ts
const response = await fetch(
  "https://api-audit.kai-studio.ai/audit/document/list",
  {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${accessToken}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      instance_id: "ki_abc123",
      offset: 0,
      limit: 50,
    }),
  },
);
if (!response.ok) throw new Error(`HTTP ${response.status}`);
console.log(await response.json());
```

{% endtab %}
{% endtabs %}

***

## audit\_documents\_set\_owner

`POST /audit/document/set-owner`

Assign or unassign a document Owner (admin only). Pass `null` (or omit) `owner_user_id` to unassign. Admin users cannot be assigned as document owners — only Producers and Stewards in a regular instance role.

{% openapi src="/files/LsPumOBZAN25uU285Xuz" path="/audit/document/set-owner" method="post" %}
[audit-api.yaml](https://3937809777-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F85gF5n5kGsNQKMPwm2VR%2Fuploads%2Fgit-blob-00a25a57ce88a8c396c05c4686ed7c88c8fa834a%2Faudit-api.yaml?alt=media)
{% endopenapi %}

***

## audit\_documents\_get\_by\_ids

`POST /audit/document/get-by-ids`

Resolve document name, URL, and extra properties for up to 100 `kd_*` ids in one call. Side effect: caches the resolved `web_url` on `audit.documents` so subsequent conflict reads surface the URL directly from the database.

{% hint style="info" %}
**Also exposed on MCP** as `audit_documents_get_by_ids` (see [Audit MCP tools](/knowledge-ai/k-ai-mcp/audit-tools.md)).
{% endhint %}

{% openapi src="/files/LsPumOBZAN25uU285Xuz" path="/audit/document/get-by-ids" method="post" %}
[audit-api.yaml](https://3937809777-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F85gF5n5kGsNQKMPwm2VR%2Fuploads%2Fgit-blob-00a25a57ce88a8c396c05c4686ed7c88c8fa834a%2Faudit-api.yaml?alt=media)
{% endopenapi %}

***

## audit\_documents\_get\_recommendations

`POST /audit/document/get-recommendations`

Return every AI-generated modification recommendation accumulated on a document across all resolved conflicts of the current instance. Use when the expert returns to a document later or asks what to change without naming a specific conflict — not as a retry for a freshly-failed `audit_question_conflict_set_answer` (this endpoint only reads persisted recommendations).

{% hint style="info" %}
**Also exposed on MCP** as `audit_documents_get_recommendations` (see [Audit MCP tools](/knowledge-ai/k-ai-mcp/audit-tools.md)).
{% endhint %}

{% openapi src="/files/LsPumOBZAN25uU285Xuz" path="/audit/document/get-recommendations" method="post" %}
[audit-api.yaml](https://3937809777-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F85gF5n5kGsNQKMPwm2VR%2Fuploads%2Fgit-blob-00a25a57ce88a8c396c05c4686ed7c88c8fa834a%2Faudit-api.yaml?alt=media)
{% endopenapi %}

***

## audit\_documents\_count

`POST /audit/document/count`

Count documents in the linked K-AI instance, optionally filtered by indexation state. Used by the K-AI Audit web app to monitor indexation progress.

{% openapi src="/files/LsPumOBZAN25uU285Xuz" path="/audit/document/count" method="post" %}
[audit-api.yaml](https://3937809777-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F85gF5n5kGsNQKMPwm2VR%2Fuploads%2Fgit-blob-00a25a57ce88a8c396c05c4686ed7c88c8fa834a%2Faudit-api.yaml?alt=media)
{% endopenapi %}

***

## audit\_documents\_list\_with\_state

`POST /audit/document/list-with-state`

Paginated list of documents in a given indexation state (for example `PARSING_ERROR`) — used by the K-AI Audit web app to surface documents that need attention.

{% openapi src="/files/LsPumOBZAN25uU285Xuz" path="/audit/document/list-with-state" method="post" %}
[audit-api.yaml](https://3937809777-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F85gF5n5kGsNQKMPwm2VR%2Fuploads%2Fgit-blob-00a25a57ce88a8c396c05c4686ed7c88c8fa834a%2Faudit-api.yaml?alt=media)
{% endopenapi %}

***

## Next

* [Duplicates](/knowledge-ai/k-ai-audit/api-reference/duplicates.md) — duplicate document clusters.
* [Conflicts](/knowledge-ai/k-ai-audit/api-reference/conflicts.md) — the primary expert worklist.
* [K-AI MCP](/knowledge-ai/k-ai-mcp/mcp.md) — programmatic and agent access.


---

# 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/k-ai-audit/api-reference/documents.md?ask=<question>&goal=<endgoal>
```

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