> 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/audit-raw.md).

# Audit (raw)

{% hint style="warning" %}
**Not to be confused with K-AI Audit.** These endpoints are raw audit primitives exposed by the K-AI instance itself — low-level counters, flags, and document pairs, consumed machine-to-machine. The full audit workflow (state machine, duplicates, conflicts, questions, MCP integration) lives on the separate [K-AI Audit](/knowledge-ai/k-ai-audit/audit.md) service.
{% endhint %}

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

The `state` field on conflicts uses the lowercase tokens `detected`, `managed`, and `ignored` at the input layer (some endpoints accept the empty string `""` as "no filter"). The underlying records use upper-case `DETECTED`, `MANAGED`, `IGNORED`, `REDETECTED`, `DISAPPEARED` — see the [`ConflictAnomaly` schema](https://github.com/KAI-Internal/gitbook/blob/main/reference/openapi/instance-api.yaml).

***

## POST /api/audit/conflict-information

List all conflict anomalies with optional free-text search, pagination, document name filtering, state filtering, and document ID filtering. When a `query` is provided, the system embeds it and performs semantic search over conflicts. When `document_name` is provided, document IDs are resolved by name first.

{% openapi src="/files/ggZwaT7KDX2BbCKblljY" path="/api/audit/conflict-information" 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/audit/conflict-information \
  -H "instance-id: <YOUR_INSTANCE_ID>" \
  -H "api-key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{"limit": 200, "offset": 0, "state": "detected"}'
```

{% endtab %}

{% tab title="Python" %}

```python
import httpx

response = httpx.post(
    "https://api.kai-studio.ai/api/audit/conflict-information",
    headers={
        "instance-id": "<YOUR_INSTANCE_ID>",
        "api-key": "<YOUR_API_KEY>",
    },
    json={"limit": 200, "offset": 0, "state": "detected"},
)
response.raise_for_status()
for conflict in response.json()["response"]:
    print(conflict["id"], conflict["subject"])
```

{% endtab %}

{% tab title="TypeScript" %}

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

{% endtab %}
{% endtabs %}

***

## POST /api/audit/conflict-information/set-state

Update a conflict's state. Valid states are `managed`, `ignored`, and `detected`. When the state is set to `managed`, the associated documents are automatically queued for reindexation (via `RemoveDocumentAgent` with `check_document=true`), and per-document conflict counts are recalculated.

{% openapi src="/files/ggZwaT7KDX2BbCKblljY" path="/api/audit/conflict-information/set-state" 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/audit/conflict-information/set-state \
  -H "instance-id: <YOUR_INSTANCE_ID>" \
  -H "api-key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{"id": "conflict_001", "state": "managed"}'
```

{% endtab %}

{% tab title="Python" %}

```python
import httpx

response = httpx.post(
    "https://api.kai-studio.ai/api/audit/conflict-information/set-state",
    headers={
        "instance-id": "<YOUR_INSTANCE_ID>",
        "api-key": "<YOUR_API_KEY>",
    },
    json={"id": "conflict_001", "state": "managed"},
)
response.raise_for_status()
print(response.json())
```

{% endtab %}

{% tab title="TypeScript" %}

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

{% endtab %}
{% endtabs %}

***

## POST /api/audit/get-conflict-information

Retrieve a specific conflict by its ID. Returns a 403 error if the conflict does not exist.

{% openapi src="/files/ggZwaT7KDX2BbCKblljY" path="/api/audit/get-conflict-information" 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/audit/get-conflict-information-by-subject

Retrieve all conflict anomalies matching a given subject, with pagination and optional state filtering. The `subject` field is required; an empty or missing subject returns a 403 error.

{% openapi src="/files/ggZwaT7KDX2BbCKblljY" path="/api/audit/get-conflict-information-by-subject" 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/audit/count-conflict-information

Return the total number of conflict anomalies in the instance. No request body required.

{% openapi src="/files/ggZwaT7KDX2BbCKblljY" path="/api/audit/count-conflict-information" 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/audit/count-conflict-by-subject

Count conflict anomalies grouped by subject. Optionally filter by document IDs (the `state` field in the input is accepted but the underlying query groups by subject across the given documents). The response is a flat map of subject to count, e.g. `{"safety requirements": 5}`.

{% openapi src="/files/ggZwaT7KDX2BbCKblljY" path="/api/audit/count-conflict-by-subject" 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/audit/count-conflict-by-date

Count conflict anomalies grouped by date and state. Returns a nested map of date → state → count, e.g. `{"2025-03-15": {"detected": 3, "managed": 1}}`.

{% openapi src="/files/ggZwaT7KDX2BbCKblljY" path="/api/audit/count-conflict-by-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/audit/count-conflicts-by-state

Count conflict anomalies for a specific state. The `state` field is required; omitting it returns a 403 error.

{% openapi src="/files/ggZwaT7KDX2BbCKblljY" path="/api/audit/count-conflicts-by-state" 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 %}

**Response shape** (per the OpenAPI spec): the response wraps a nested statistics object — `{"response": <object>}` — whose precise shape is produced by the underlying `AuditStatisticController` query. The structure is open-ended in the spec because the handler passes the raw aggregation dict directly. Refer to a live API call against your instance for the exact keys.

***

## POST /api/audit/count-conflict-by-document-ids

Count conflict anomalies for the given document IDs, optionally filtered by state. Returns a flat map of document ID to count.

{% openapi src="/files/ggZwaT7KDX2BbCKblljY" path="/api/audit/count-conflict-by-document-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/audit/document-ids-to-manage

Count duplicates and conflicts per document, returning a nested dictionary. Supports search, pagination, document name filtering, state filtering, and document ID filtering. The response value for each document ID is an object with `conflicts` and `duplicates` integer counts.

{% openapi src="/files/ggZwaT7KDX2BbCKblljY" path="/api/audit/document-ids-to-manage" 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/audit/get-anomalies-for-document

Retrieve all conflicts associated with a specific document. Returns an object containing a `conflicts` array of [`ConflictAnomaly`](https://github.com/KAI-Internal/gitbook/blob/main/reference/openapi/instance-api.yaml) items.

{% openapi src="/files/ggZwaT7KDX2BbCKblljY" path="/api/audit/get-anomalies-for-document" 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/audit/get-anomalies-for-document \
  -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/audit/get-anomalies-for-document",
    headers={
        "instance-id": "<YOUR_INSTANCE_ID>",
        "api-key": "<YOUR_API_KEY>",
    },
    json={"id": "doc_abc123"},
)
response.raise_for_status()
for conflict in response.json()["response"]["conflicts"]:
    print(conflict["id"], conflict["state"], conflict["subject"])
```

{% endtab %}

{% tab title="TypeScript" %}

```ts
const response = await fetch(
  "https://api.kai-studio.ai/api/audit/get-anomalies-for-document",
  {
    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/audit/document-is-analyzed

Check whether a specific document has already been audited. Returns `true` if the document's `audit_done` flag is set.

{% openapi src="/files/ggZwaT7KDX2BbCKblljY" path="/api/audit/document-is-analyzed" 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/audit/get-conflict-document-pair

Retrieve document ID pairs that have potential conflicts between them. Supports pagination, document name filtering, state filtering, and sort order.

{% openapi src="/files/ggZwaT7KDX2BbCKblljY" path="/api/audit/get-conflict-document-pair" 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 %}

**Response shape** (per the OpenAPI spec): `{"response": [<object>, ...]}`. Each list item is an open-ended object (`additionalProperties: true`) produced by the underlying `AnomalyController` query — the exact keys are not statically typed in the source. Refer to a live API call for the precise structure.

***

## POST /api/audit/get-conflicts-by-document-id-pair

Retrieve all conflict anomalies between a specific pair of documents. Supports pagination and state filtering. Returns a list of [`ConflictAnomaly`](https://github.com/KAI-Internal/gitbook/blob/main/reference/openapi/instance-api.yaml) items.

{% openapi src="/files/ggZwaT7KDX2BbCKblljY" path="/api/audit/get-conflicts-by-document-id-pair" 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/audit/list-all-document-ids

Return a paginated list of document IDs that have at least one anomaly (conflict or duplicate). The handler delegates to `AnomalyController.get_document_ids()` with `limit` and `offset` from the input. The other input fields (`query`, `document_name`, `state`, `document_ids`) are accepted but only `limit` and `offset` are used by the underlying query.

{% openapi src="/files/ggZwaT7KDX2BbCKblljY" path="/api/audit/list-all-document-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 %}

**Response shape** (per the OpenAPI spec): `{"response": ["doc_abc123", "doc_def456", ...]}` — a flat array of document ID strings.


---

# 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/audit-raw.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.