> 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 Audit instances scope every other Audit API call. Each audit instance is bound to a K-AI instance (the `ki_*` Document Repository owning the documents being audited) and tracks a workflow step, configuration, and a membership list of users with admin/regular roles. This page covers 13 operations: the dashboard entrypoint, instance read/update, K-AI credential lookup, step + configuration updates, and the seven user-membership 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\_dashboard\_get `POST /audit/dashboard/get-my-dashboard` Returns a summary of every audit instance the authenticated user can access, with per-instance counters for unresolved conflicts, unresolved full-audit conflicts, pending mandatory questions, and pending missing subjects. This is the recommended entrypoint before drilling into a specific instance — every other audit operation needs a `ki_*` instance id taken from this dashboard. {% 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-00a25a57ce88a8c396c05c4686ed7c88c8fa834a%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 " \ -H "Content-Type: application/json" \ -d '{}' ``` {% 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\_list\_for\_user `POST /audit/instance/list-instances-for-user` List every audit instance accessible by the authenticated user. Lower-level alternative to `audit_dashboard_get` — no aggregated counters, just the raw instance records. {% openapi src="/files/LsPumOBZAN25uU285Xuz" path="/audit/instance/list-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-00a25a57ce88a8c396c05c4686ed7c88c8fa834a%2Faudit-api.yaml?alt=media) {% endopenapi %} *** ## audit\_instance\_get `POST /audit/instance/get-instance` Retrieve a single audit instance by id, including its current workflow step and configuration. {% 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-00a25a57ce88a8c396c05c4686ed7c88c8fa834a%2Faudit-api.yaml?alt=media) {% endopenapi %} *** ## audit\_instance\_get\_kai\_instances `POST /audit/instance/get-kai-instances` Return the K-AI `instance_id` and `api_key` linked to the audit instance. Shape preserved for K-AI Audit web app compatibility — the response is always an array (zero or one entry). After the unification migration, `kai_instance_id` equals the input `instance_id`. {% openapi src="/files/LsPumOBZAN25uU285Xuz" path="/audit/instance/get-kai-instances" 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\_instance\_update\_step `POST /audit/instance/update-instance-step` Update the workflow step of an audit instance. The audit lifecycle is fully automated end-to-end; this endpoint is reserved for K-AI Audit web app reopen flows and admin recovery. Allowed steps: `ON_CHECKING_INDEXATION`, `RUNNING_PHASE`, `INIT`, `CHECK_INDEXATION_DONE`, `LAUNCH_DUPLICATE_IDENTIFICATION`, `ON_DUPLICATE_IDENTIFICATION`, `DUPLICATE_IDENTIFICATION_DONE`. {% openapi src="/files/LsPumOBZAN25uU285Xuz" path="/audit/instance/update-instance-step" 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\_instance\_update\_configuration `POST /audit/instance/update-configuration` Update the configuration of an audit instance. The only documented flag is `need_detect_owner_document_feature`: when enabled, non-admin users only see documents they own and conflicts touching documents they own. {% 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-00a25a57ce88a8c396c05c4686ed7c88c8fa834a%2Faudit-api.yaml?alt=media) {% endopenapi %} *** ## User membership The following seven operations manage user membership and instance-level roles. Add/remove/promote/demote require instance admin or global admin privileges. *** ## audit\_user\_get\_users `POST /audit/user/get-users-for-instance` List users associated with an audit instance with pagination. Accessible by instance members and global admins. {% 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-00a25a57ce88a8c396c05c4686ed7c88c8fa834a%2Faudit-api.yaml?alt=media) {% endopenapi %} *** ## audit\_user\_list\_instances `POST /audit/user/list-user-instances` List the audit instances a given user can access within an organization. Global admins can query any user; non-admin callers may only query themselves. {% openapi src="/files/LsPumOBZAN25uU285Xuz" path="/audit/user/list-user-instances" 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\_user\_add `POST /audit/user/add-user-to-instance` Add a user to an audit instance (admin only). {% openapi src="/files/LsPumOBZAN25uU285Xuz" path="/audit/user/add-user-to-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-00a25a57ce88a8c396c05c4686ed7c88c8fa834a%2Faudit-api.yaml?alt=media) {% endopenapi %} *** ## audit\_user\_remove `POST /audit/user/remove-user-from-instance` Remove a user from an audit instance (admin only). {% 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-00a25a57ce88a8c396c05c4686ed7c88c8fa834a%2Faudit-api.yaml?alt=media) {% endopenapi %} *** ## audit\_user\_set\_admin `POST /audit/user/set-user-admin-for-instance` Promote a user to admin scope on this audit instance. {% openapi src="/files/LsPumOBZAN25uU285Xuz" path="/audit/user/set-user-admin-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-00a25a57ce88a8c396c05c4686ed7c88c8fa834a%2Faudit-api.yaml?alt=media) {% endopenapi %} *** ## audit\_user\_set\_normal `POST /audit/user/set-user-normal-for-instance` Demote an instance admin back to regular user. {% openapi src="/files/LsPumOBZAN25uU285Xuz" path="/audit/user/set-user-normal-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-00a25a57ce88a8c396c05c4686ed7c88c8fa834a%2Faudit-api.yaml?alt=media) {% endopenapi %} *** ## audit\_user\_is\_admin `POST /audit/user/user-is-admin-for-instance` Check whether the authenticated user is admin on this audit instance. Global admins inherit admin on every instance and always return `true`. {% openapi src="/files/LsPumOBZAN25uU285Xuz" path="/audit/user/user-is-admin-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-00a25a57ce88a8c396c05c4686ed7c88c8fa834a%2Faudit-api.yaml?alt=media) {% endopenapi %} *** ## Next * [Documents & indexation](/knowledge-ai/k-ai-audit/api-reference/documents.md) — list, get by id, set owner, count, recommendations. * [Conflicts](/knowledge-ai/k-ai-audit/api-reference/conflicts.md) — the primary expert worklist. * [K-AI MCP](/knowledge-ai/k-ai-mcp/mcp.md) — connect Claude Desktop / Cursor / Le Chat to the Audit MCP server. --- # 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/instances.md?ask=&goal= ``` `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.