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

# Instances & users

Audit instances scope every other Audit API call. An audit instance is a K-AI instance (the `ki_*` Document Repository owning the documents being audited) carrying the audit module, with a workflow step, a configuration, and a team of attached users.

This page covers 8 operations: the dashboard entrypoint, instance read and configuration, and five team-management operations.

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

## Access tiers

| Tier           | Who                                                                                            | Grants                                                                                       |
| -------------- | ---------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
| View + resolve | Organization Owner / Admin / Steward (organization-wide), or any user attached to the instance | Read the instance and its worklists; answer and close conflicts, questions, missing subjects |
| Configure      | Organization Owner / Admin / Steward                                                           | Change the configuration, manage the team                                                    |

Every instance-scoped operation returns `400` when `instance_id` is not a `ki_*` id, and `403` when the caller lacks the required tier.

***

## audit\_dashboard\_get

`POST /audit/dashboard/get-my-dashboard`

Lists every K-AI instance carrying the audit module that the caller can access, with per-instance counters for unresolved question conflicts, unresolved full-audit conflicts, pending mandatory questions, and pending missing subjects. Pass `organization_id` to restrict the list to one organization. This is the recommended entrypoint — every other audit operation needs a `ki_*` instance id taken from this dashboard.

`counts.total_documents` and `counts.documents_with_unresolved_conflicts` give the share of the corpus involved in at least one unresolved conflict; derive the percentage from them. Both are `null` together when the value could not be computed — unknown, never zero.

`pipeline_state` and `analysis_activity` (`running`, `queued`, `idle`) tell whether the first audit pass has completed and whether an analysis is moving the numbers right now. `null` means unknown. Treat `pipeline_state` as unknown when `last_observed_at` is missing or stale, and report an instance as ready only from `ready_for_use: true`.

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

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

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

```bash
curl -X POST https://api-audit.kai-studio.ai/audit/dashboard/get-my-dashboard \
  -H "Authorization: Bearer <YOUR_ACCESS_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"organization_id": "<ORGANIZATION_ID>"}'
```

{% endtab %}

{% tab title="Python" %}

```python
import httpx

response = httpx.post(
    "https://api-audit.kai-studio.ai/audit/dashboard/get-my-dashboard",
    headers={"Authorization": f"Bearer {access_token}"},
    json={},
)
response.raise_for_status()
print(response.json())
```

{% endtab %}

{% tab title="TypeScript" %}

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

{% endtab %}
{% endtabs %}

***

## audit\_instance\_get

`POST /audit/instance/get-instance`

Retrieve one audit instance: name, workflow step (`ON_CHECKING_INDEXATION` while the index is being checked, then `RUNNING_PHASE`), configuration, and the same `pipeline_state` / `analysis_activity` readiness signals as the dashboard. Requires the view tier. Returns `404` if the instance does not exist.

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

***

## audit\_instance\_update\_configuration

`POST /audit/instance/update-configuration`

Replace the configuration of an audit instance. The only setting is `need_detect_owner_document_feature`: when `true`, the K-AI Companion browser extension only offers a user the documents they own, plus documents with no detected owner. The K-AI Audit web app document list is not filtered by it. Requires the configure tier. Returns `404` for an unknown instance and `500` when the configuration could not be written (nothing changed).

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

***

## Team management

The following five operations manage the users attached to an instance. Attachment gives a user view and resolve access to that instance; organization Owners, Admins and Stewards reach every instance of the organization without being attached. All five require the configure tier. User ids are raw, never prefixed.

***

## audit\_user\_get\_users

`POST /audit/user/get-users-for-instance`

Paginated list (`offset`, `limit` up to 1000) of the users attached to the instance. Users reaching the instance only through an organization-wide role are not listed. When the roster cannot be read, the call fails instead of returning an empty list.

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

***

## audit\_user\_list\_org\_users

`POST /audit/user/list-org-users`

List the active members of the organization owning the instance, each flagged with `is_knowledge_expert`, `is_service_account` (`true` for an Organization API key), and `attached` (already on this instance's team). Use it to pick a user for `audit_user_attach_existing`. Returns `404` if the instance has no owning organization.

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

***

## audit\_user\_attach\_existing

`POST /audit/user/attach-existing-user`

Attach an existing member of the owning organization to the instance. A human user is also granted the Knowledge Expert organization role if they do not hold it yet (`granted_knowledge_expert: true`). An Organization API key is attached without any role grant. Idempotent: `linked: false` means the user was already attached.

Returns `404` when the user does not exist or is not a member of the owning organization.

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

***

## audit\_user\_remove

`POST /audit/user/remove-user-from-instance`

Detach a user from the instance. The Knowledge Expert organization role is not revoked, and a user holding an organization-wide role keeps access through it. Returns `500` when the attachment could not be removed — the user still has access in that case.

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

***

## audit\_user\_instances\_for\_user

`POST /audit/user/instances-for-user`

List the audit instances of one organization that a given user — human or Organization API key — is attached to, whatever their status (`status` is echoed as stored). `org_wide: true` means the user holds an organization role that reaches every audit instance of the organization, so `instances` understates its reach. Both fields are read together: a failed read returns an error, never `org_wide: false`.

Takes `organization_id` and `user_id` (both raw) instead of an instance id. Requires an Owner, Admin, or Steward role in that organization.

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

***

## Next

* [Documents](/knowledge-ai/k-ai-audit/api-reference/documents.md) — list documents, owners, recommendations, scoring.
* [Unified conflicts](/knowledge-ai/k-ai-audit/api-reference/unified-conflicts.md) — one worklist for question and full-audit conflicts.