> 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/assertion-cases.md).

# Assertion cases

An assertion case checks an outside text against the Document Repository. A reviewer submits the text to verify — a draft procedure, a contract clause, a regulatory notice, a set of attachments — and K-AI extracts every factual assertion it contains, compares each one with the documents of the instance, and produces a report: documents to fix, documents to complete, points to arbitrate between diverging documents, and documents to create.

This page covers 12 operations. All of them are REST-only — none is exposed on the Audit MCP server.

Auth: OAuth 2.1 Bearer token, [Organization API key](https://k-ai.gitbook.io/knowledge-ai/authentication/organization-api-keys.md) Bearer, or the `kai_auth` HttpOnly cookie — see [Authentication](https://k-ai.gitbook.io/knowledge-ai/authentication/authentication.md).

## Lifecycle

```
COLLECTING ──start-analysis──▶ PARSING ──▶ EXTRACTING ──▶ ANALYZING ──▶ REPORT_READY ──close-case──▶ CLOSED
                                  │             │              │
                                  └─────────────┴──────────────┴──▶ FAILED
```

| State          | Meaning                                                                                       |
| -------------- | --------------------------------------------------------------------------------------------- |
| `COLLECTING`   | The case accepts inputs: one pasted text and attachments. Inputs can be added and removed.    |
| `PARSING`      | Attachments are being converted to text.                                                      |
| `EXTRACTING`   | K-AI extracts the assertions from every usable input.                                         |
| `ANALYZING`    | Each assertion is compared with the documents of the instance.                                |
| `REPORT_READY` | The report is available in [`audit_assertion_get_case`](#audit_assertion_get_case).           |
| `CLOSED`       | The case is archived. Texts and attachments are purged; the report and the timeline are kept. |
| `FAILED`       | The analysis stopped. `case.error` and `summary.failures` explain why.                        |

Only `COLLECTING` is driven by the client. The transitions from `PARSING` to `REPORT_READY` run in the background; poll [`audit_assertion_get_case`](#audit_assertion_get_case) and read `progress` to follow them.

Each assertion receives a verdict:

| Verdict        | Meaning                                                                   |
| -------------- | ------------------------------------------------------------------------- |
| `CONTRADICTED` | The documents contradict the assertion.                                   |
| `AMBIGUOUS`    | The documents disagree: some contradict the assertion, others confirm it. |
| `CONFIRMED`    | The documents confirm the assertion.                                      |
| `PARTIAL`      | The documents cover the subject only incompletely.                        |
| `ABSENT`       | No document covers the assertion.                                         |

Assertions outside the scope of the instance are flagged `off_domain: true`.

## Access

| Action                                                              | Who                                                                                                                                   |
| ------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| List and read cases, download attachments                           | Any user who can view the instance.                                                                                                   |
| Create, rename, duplicate, add or remove inputs, start the analysis | Users who can resolve on the instance (organization owners, admins and stewards, and the Knowledge Experts attached to the instance). |
| Close or delete a case                                              | The case author, an organization-wide role, or an admin of the instance.                                                              |

A case that does not exist and a case on an instance you cannot view both return `404 case_not_found`.

## Identifiers

| Prefix | Object                                               |
| ------ | ---------------------------------------------------- |
| `ac_`  | Assertion case                                       |
| `an_`  | Case input (text or attachment)                      |
| `aa_`  | Extracted assertion                                  |
| `af_`  | Finding — what one document says about one assertion |
| `ap_`  | Proposal — a document to create                      |

Errors carry a machine code in `detail.error`, for example `{"detail": {"error": "case_not_collecting"}}`. A malformed or wrongly prefixed id returns `400` with `wrong_id_namespace` or `invalid_id_format`.

***

## audit\_assertion\_create\_case

`POST /audit/assertion/create-case`

Create an empty case in `COLLECTING`. `title` (max 200 characters) and `effective_date` (a reference date, `YYYY-MM-DD`, stored as a label — it does not influence the analysis) are optional and can be changed later with [`audit_assertion_update_case`](#audit_assertion_update_case).

Returns the case summary.

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

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

```bash
curl -X POST https://api-audit.kai-studio.ai/audit/assertion/create-case \
  -H "Authorization: Bearer <YOUR_ACCESS_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"instance_id": "ki_abc123", "title": "Supplier onboarding procedure v3", "effective_date": "2026-11-01"}'
```

{% endtab %}

{% tab title="Python" %}

```python
import httpx

response = httpx.post(
    "https://api-audit.kai-studio.ai/audit/assertion/create-case",
    headers={"Authorization": f"Bearer {access_token}"},
    json={
        "instance_id": "ki_abc123",
        "title": "Supplier onboarding procedure v3",
        "effective_date": "2026-11-01",
    },
)
response.raise_for_status()
case_id = response.json()["response"]["id"]  # "ac_..."
```

{% endtab %}

{% tab title="TypeScript" %}

```ts
const response = await fetch(
  "https://api-audit.kai-studio.ai/audit/assertion/create-case",
  {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${accessToken}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      instance_id: "ki_abc123",
      title: "Supplier onboarding procedure v3",
      effective_date: "2026-11-01",
    }),
  },
);
if (!response.ok) throw new Error(`HTTP ${response.status}`);
const caseId = (await response.json()).response.id; // "ac_..."
```

{% endtab %}
{% endtabs %}

***

## audit\_assertion\_update\_case

`POST /audit/assertion/update-case`

Rename a case or change its effective date. Allowed in every state, `CLOSED` included. An omitted field is left unchanged; an explicit `null` clears it.

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

***

## audit\_assertion\_set\_text

`POST /audit/assertion/set-text`

Set the pasted text of the case (1 to 200,000 characters). A case holds one text input: calling this again replaces it. Only in `COLLECTING` — otherwise `409 case_not_collecting`.

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

***

## audit\_assertion\_add\_attachment

`POST /audit/assertion/add-attachment`

Upload one file to the case. The body is `multipart/form-data` with the fields `instance_id`, `case_id` and `file`. Only in `COLLECTING`.

* Accepted extensions: `.pdf`, `.docx`, `.xlsx`, `.pptx`, `.txt`, `.html`. Anything else returns `415 unsupported_file_type`.
* Default limits: 25 MiB per file (`413 file_too_large`), 20 attachments per case (`409 too_many_attachments`).

The file is processed as soon as it is stored. Follow `inputs[].parse_state` until it reaches `DONE` or `FAILED` in [`audit_assertion_get_case`](#audit_assertion_get_case).

```bash
curl -X POST https://api-audit.kai-studio.ai/audit/assertion/add-attachment \
  -H "Authorization: Bearer <YOUR_ACCESS_TOKEN>" \
  -F instance_id=ki_abc123 \
  -F case_id=ac_7f3e9c1a-0b2d-4e5f-9a8b-1c2d3e4f5a6b \
  -F file=@procedure-v3.docx
```

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

***

## audit\_assertion\_remove\_input

`POST /audit/assertion/remove-input`

Remove one input (`an_*`) — the text or an attachment — and delete its stored file. Only in `COLLECTING`. Returns `{"response": {"removed": true}}`.

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

***

## audit\_assertion\_start\_analysis

`POST /audit/assertion/start-analysis`

Move the case from `COLLECTING` to `PARSING` and start the analysis. At least one input must be usable — a non-empty text, or an attachment that was read successfully — otherwise `409 no_usable_input`. Returns `{"response": {"case_id": "ac_…", "state": "PARSING"}}`.

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

***

## audit\_assertion\_list\_cases

`POST /audit/assertion/list-cases`

List the cases of an instance, paginated with `offset` and `limit` (1–1000). Each entry carries the state, the author, the number of inputs and, once the report is ready, the action counts (`documents_to_fix`, `documents_to_complete`, `points_to_arbitrate`, `documents_to_create`).

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

***

## audit\_assertion\_get\_case

`POST /audit/assertion/get-case`

Return the full case. This is both the progress endpoint and the report.

| Field            | Content                                                                                                                       |
| ---------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `case`           | Title, effective date, state, author, error.                                                                                  |
| `timeline[]`     | Every state transition: `from`, `to`, `at`, `by`.                                                                             |
| `progress`       | `step` (1 = collecting … 5 = report) and `assertions_done` / `assertions_total`. A `FAILED` case keeps the step it failed at. |
| `summary`        | Set once the report is ready: verdict `counts`, `actions` counts, `failures[]`.                                               |
| `inputs[]`       | Each input with its processing state, `usable`, and `downloadable`.                                                           |
| `assertions[]`   | Each extracted assertion with its source input, `verdict` and `off_domain`.                                                   |
| `to_fix[]`       | Documents that contradict assertions, grouped by document, with the passages to correct.                                      |
| `to_complete[]`  | Documents that cover assertions only partially, grouped by document.                                                          |
| `to_arbitrate[]` | `AMBIGUOUS` assertions, with the documents that disagree.                                                                     |
| `to_create[]`    | Proposed new documents and the assertions they would cover.                                                                   |

The report lists are empty until the case reaches `REPORT_READY`.

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

***

## audit\_assertion\_download\_attachment

`POST /audit/assertion/download-attachment`

Download the original file of an attachment input. The response is the binary file with its MIME type and a `Content-Disposition` header carrying the original file name. Text inputs and attachments of a closed case are not downloadable (`410 attachment_unavailable`); check `inputs[].downloadable` first.

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

***

## audit\_assertion\_close\_case

`POST /audit/assertion/close-case`

Archive a case: `REPORT_READY` → `CLOSED`. The texts and attachments are purged; the report, the assertions and the timeline are kept. Restricted to the case author, an organization-wide role, or an admin of the instance.

Returns `409 case_not_report_ready` if the case is in another state and `409 case_already_closed` if it is already closed and purged. Calling it again on a closed case whose purge did not complete retries the purge.

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

***

## audit\_assertion\_delete\_case

`POST /audit/assertion/delete-case`

Delete a case and everything attached to it — inputs, files, assertions, findings, report. Allowed from any state, including during the analysis, which is cancelled. Irreversible. Same access rule as close.

If a stored file cannot be deleted, the case is left intact and the call returns `503 storage_unavailable`; retry it. Returns `{"response": {"deleted": true}}`.

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

***

## audit\_assertion\_duplicate\_case

`POST /audit/assertion/duplicate-case`

Create a new case in `COLLECTING` with a copy of the source case's title, effective date, text and attachments. Attachments are copied as they are — nothing needs to be uploaded again. The typical use is retrying a `FAILED` case after replacing one file.

Refused while an attachment of the source is still being processed (`409 case_parsing_in_progress`) and on a closed case, whose inputs are purged (`409 case_closed`). Open to any user who can resolve on the instance.

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