> 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/tree/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-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/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-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/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-f10c7aa7b61beb8fa154e76dc42db38f2d85f9f0%2Finstance-api.yaml?alt=media\&token=79231d80-f551-4804-9087-efd6ceda9ab9)
{% 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-f10c7aa7b61beb8fa154e76dc42db38f2d85f9f0%2Finstance-api.yaml?alt=media\&token=79231d80-f551-4804-9087-efd6ceda9ab9)
{% 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-f10c7aa7b61beb8fa154e76dc42db38f2d85f9f0%2Finstance-api.yaml?alt=media\&token=79231d80-f551-4804-9087-efd6ceda9ab9)
{% 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-f10c7aa7b61beb8fa154e76dc42db38f2d85f9f0%2Finstance-api.yaml?alt=media\&token=79231d80-f551-4804-9087-efd6ceda9ab9)
{% 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-f10c7aa7b61beb8fa154e76dc42db38f2d85f9f0%2Finstance-api.yaml?alt=media\&token=79231d80-f551-4804-9087-efd6ceda9ab9)
{% 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-f10c7aa7b61beb8fa154e76dc42db38f2d85f9f0%2Finstance-api.yaml?alt=media\&token=79231d80-f551-4804-9087-efd6ceda9ab9)
{% 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-f10c7aa7b61beb8fa154e76dc42db38f2d85f9f0%2Finstance-api.yaml?alt=media\&token=79231d80-f551-4804-9087-efd6ceda9ab9)
{% 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-f10c7aa7b61beb8fa154e76dc42db38f2d85f9f0%2Finstance-api.yaml?alt=media\&token=79231d80-f551-4804-9087-efd6ceda9ab9)
{% 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/tree/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-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/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-f10c7aa7b61beb8fa154e76dc42db38f2d85f9f0%2Finstance-api.yaml?alt=media\&token=79231d80-f551-4804-9087-efd6ceda9ab9)
{% 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-f10c7aa7b61beb8fa154e76dc42db38f2d85f9f0%2Finstance-api.yaml?alt=media\&token=79231d80-f551-4804-9087-efd6ceda9ab9)
{% 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/tree/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-f10c7aa7b61beb8fa154e76dc42db38f2d85f9f0%2Finstance-api.yaml?alt=media\&token=79231d80-f551-4804-9087-efd6ceda9ab9)
{% 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-f10c7aa7b61beb8fa154e76dc42db38f2d85f9f0%2Finstance-api.yaml?alt=media\&token=79231d80-f551-4804-9087-efd6ceda9ab9)
{% endopenapi %}

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