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

# Mandatory questions

Mandatory questions are the Steward-defined probes that drive question-based conflict detection on an audit instance. Each question is embedded, broadcast across the Document Repository, and surfaces a conflict whenever two documents disagree on the answer. This page covers the question lifecycle: list, create, set the expert answer, mark managed or ignored, and force re-analysis of a refused question.

This page covers 6 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\_mandatory\_question\_list

`POST /audit/mandatory-question/list`

Auxiliary worklist over mandatory questions. The primary expert worklist is `audit_question_conflict_list` (see [Conflicts](/knowledge-ai/k-ai-audit/api-reference/conflicts.md)) — use this list to inspect or manage questions directly, or to find a `REFUSED` question to pass to `audit_mandatory_question_force_analyze`. Optional `state` filter (for example `REFUSED`, `MANAGED`, `IGNORED`).

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

{% openapi src="/files/LsPumOBZAN25uU285Xuz" path="/audit/mandatory-question/list" 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/mandatory-question/list \
  -H "Authorization: Bearer <YOUR_ACCESS_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"instance_id": "ki_abc123", "offset": 0, "limit": 50, "state": "REFUSED"}'
```

{% endtab %}

{% tab title="Python" %}

```python
import httpx

response = httpx.post(
    "https://api-audit.kai-studio.ai/audit/mandatory-question/list",
    headers={"Authorization": f"Bearer {access_token}"},
    json={
        "instance_id": "ki_abc123",
        "offset": 0,
        "limit": 50,
        "state": "REFUSED",
    },
)
response.raise_for_status()
print(response.json())
```

{% endtab %}

{% tab title="TypeScript" %}

```ts
const response = await fetch(
  "https://api-audit.kai-studio.ai/audit/mandatory-question/list",
  {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${accessToken}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      instance_id: "ki_abc123",
      offset: 0,
      limit: 50,
      state: "REFUSED",
    }),
  },
);
if (!response.ok) throw new Error(`HTTP ${response.status}`);
console.log(await response.json());
```

{% endtab %}
{% endtabs %}

***

## audit\_mandatory\_question\_create

`POST /audit/mandatory-question/create`

Create a new mandatory question on an audit instance. The question is queued for embedding and analysis; once analysis completes it either produces conflicts (`audit_question_conflict_list`) or moves to a terminal state.

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

{% openapi src="/files/LsPumOBZAN25uU285Xuz" path="/audit/mandatory-question/create" 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/mandatory-question/create \
  -H "Authorization: Bearer <YOUR_ACCESS_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "instance_id": "ki_abc123",
    "question": "Does the document set cover fire safety procedures?"
  }'
```

{% endtab %}

{% tab title="Python" %}

```python
import httpx

response = httpx.post(
    "https://api-audit.kai-studio.ai/audit/mandatory-question/create",
    headers={"Authorization": f"Bearer {access_token}"},
    json={
        "instance_id": "ki_abc123",
        "question": "Does the document set cover fire safety procedures?",
    },
)
response.raise_for_status()
print(response.json())
```

{% endtab %}

{% tab title="TypeScript" %}

```ts
const response = await fetch(
  "https://api-audit.kai-studio.ai/audit/mandatory-question/create",
  {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${accessToken}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      instance_id: "ki_abc123",
      question: "Does the document set cover fire safety procedures?",
    }),
  },
);
if (!response.ok) throw new Error(`HTTP ${response.status}`);
console.log(await response.json());
```

{% endtab %}
{% endtabs %}

***

## audit\_mandatory\_question\_set\_answer

`POST /audit/mandatory-question/set-answer`

Record the expert answer for a mandatory question. Admin flow — in normal operation experts resolve conflicts via `audit_question_conflict_set_answer` (which targets the conflict, not the question).

{% openapi src="/files/LsPumOBZAN25uU285Xuz" path="/audit/mandatory-question/set-answer" 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\_mandatory\_question\_set\_managed

`POST /audit/mandatory-question/set-managed`

Mark a mandatory question as managed. Triggers re-indexation of every document cited by the question's conflicts. Call only once the expert has confirmed the question is fully resolved.

{% openapi src="/files/LsPumOBZAN25uU285Xuz" path="/audit/mandatory-question/set-managed" 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\_mandatory\_question\_set\_ignored

`POST /audit/mandatory-question/set-ignored`

Mark a mandatory question as ignored — the Steward chose not to pursue this probe.

{% openapi src="/files/LsPumOBZAN25uU285Xuz" path="/audit/mandatory-question/set-ignored" 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\_mandatory\_question\_force\_analyze

`POST /audit/mandatory-question/force-analyze`

Force re-analysis of a refused mandatory question. Only valid when the question is in `REFUSED` state. Recomputes its embedding and re-enqueues a `CheckQuestionTask` for the audit worker. Returns `true` once the question has been re-queued.

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

{% openapi src="/files/LsPumOBZAN25uU285Xuz" path="/audit/mandatory-question/force-analyze" 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

* [Conflicts](/knowledge-ai/k-ai-audit/api-reference/conflicts.md) — the question-driven conflicts produced by these questions.
* [Questions & answers](/knowledge-ai/k-ai-audit/api-reference/questions-answers.md) — the broader, instance-level full-audit review.
* [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:

```
GET https://k-ai.gitbook.io/knowledge-ai/k-ai-audit/api-reference/mandatory-questions.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.