Questions and approvals API

Kheish exposes approvals and structured user questions as first-class suspended-run states. These endpoints do not create unrelated work. They resume runs that are waiting.

Endpoint inventory

List pending user questions:

GET /v1/questions
GET /v1/sessions/{session_id}/questions

Resume from a session context:

POST /v1/sessions/{session_id}/approvals
POST /v1/sessions/{session_id}/questions
POST /v1/sessions/{session_id}/approval-runs

Resume from a run handle:

POST /v1/runs/{run_id}/approvals
POST /v1/runs/{run_id}/questions
POST /v1/runs/{run_id}/questions/{request_id}/cancel

Which endpoint should you use?

Use the session-scoped endpoints when you already operate in a session workflow and want the result projected back onto the session surface. Use the run-scoped endpoints when you already have a concrete suspended run_id and want a detached resume handle. Behavior difference:

POST /v1/sessions/{session_id}/approvals
- returns an updated SessionView
POST /v1/sessions/{session_id}/questions
- returns an updated SessionView
POST /v1/sessions/{session_id}/approval-runs
- returns 202 Accepted plus a detached RunView
POST /v1/runs/{run_id}/approvals
- returns 202 Accepted plus a detached RunView
POST /v1/runs/{run_id}/questions
- returns 202 Accepted plus a detached RunView
POST /v1/runs/{run_id}/questions/{request_id}/cancel
- validates that request_id is pending on run_id, then returns the cancelled or declined RunView

List pending user questions

GET /v1/questions supports:

session_id

GET /v1/sessions/{session_id}/questions is the session-scoped equivalent. The response is a list of PendingQuestionView objects:

session_id
agent_id
run_id
run_kind
requester_agent_id
requester_session_id
requester_run_id
requester_tool_call_id
requester_project_ids
requester_channel_ids
parent_project_ids
parent_channel_ids
request

The requester and project/channel fields are populated for parent_clarification runs. They let operators see which child run is blocked, where the question came from, and which project or channel contexts were active when the child escalated the clarification. request is a UserQuestionRequest:

id
tool_call_id
questions
created_at_ms
expires_at_ms

Each structured question contains:

id
header
question
options
multi_select

Resolve approvals

Approval endpoints accept:

{
  "idempotency_key": "optional-client-retry-key",
  "resolutions": [
    {
      "request_id": "approval-bash-1",
      "behavior": "allow",
      "justification": "approved by operator"
    }
  ]
}

Each ApprovalResolution supports:

request_id
behavior
- allow
- deny
updated_input
justification
reason

Use updated_input when the approver wants to modify the pending tool input before allowing it. Clients can also send the idempotency key through the Idempotency-Key header. Reusing the same key with an identical payload returns the same resumed run; reusing it with a different payload is rejected.

Resolve structured user questions

Question endpoints accept:

{
  "idempotency_key": "optional-client-retry-key",
  "resolution": {
    "request_id": "question-1",
    "answers": [
      {
        "question_id": "routing",
        "selected_option_ids": ["openai"]
      },
      {
        "question_id": "notes",
        "freeform_answer": "Use the fast path unless cost exceeds budget."
      }
    ],
    "declined": false,
    "justification": "Answered by operator"
  }
}

UserQuestionResolution fields:

request_id
answers
declined
justification

Each answer supports:

question_id
selected_option_ids
freeform_answer

For declined questions, set declined to true and leave answers empty. Clients can also send the idempotency key through the Idempotency-Key header. This is recommended for CLI and UI retries because question answers resume the original suspended run.

Cancel structured user questions

Cancel a specific pending question through the run-scoped cancel endpoint:

{
  "idempotency_key": "optional retry key",
  "justification": "optional operator note"
}

For normal user questions, POST /v1/runs/{run_id}/questions/{request_id}/cancel cancels the waiting run only when the request id still matches a pending question on that run. A stale or mistyped request_id is rejected and the run remains waiting. For parent-clarification questions, the same endpoint records a declined clarification and delivers that declined answer back to the requesting child. The optional justification is included in the declined clarification payload. questions cancel uses this request-scoped endpoint. The older run-level POST /v1/runs/{run_id}/cancel still cancels a run directly, but clients that are acting on a question should prefer the request-scoped question cancel endpoint. Clients can also send the cancel idempotency key through the Idempotency-Key header. This is recommended when retrying a request-scoped cancel after network loss or double-submit. CLI retries with questions cancel --idempotency-key require --run-id, because a completed cancel removes the pending question from session-scoped discovery.

Question errors

Question endpoints return application/problem+json with stable domain and code fields. Common codes:

Status	Domain	Code	Meaning
`400`	`questions`	`question_request_mismatch`	The resolution or cancel request does not match the pending question request.
`400`	`questions`	`question_option_not_found`	An answer selected an option id that is not part of the question.
`400`	`questions`	`question_answer_missing`	A required structured question was not answered.
`400`	`questions`	`question_duplicate_answer`	The payload answered the same question more than once.
`400`	`questions`	`question_duplicate_option`	The payload selected the same option more than once.
`400`	`questions`	`question_declined_with_answers`	A declined resolution also supplied answers.
`400`	`questions`	`question_single_select_violation`	A single-select question received multiple selected options.
`400`	`questions`	`question_answer_empty`	An answer supplied neither selected options nor freeform text.
`400`	`questions`	`question_unknown_answer`	The payload included answers for questions not present in the request.
`409`	`questions`	`question_state_conflict`	The run is not waiting for a user question.
`409`	`questions`	`question_expired`	The question expired before the answer or cancel request arrived.
`409`	`questions`	`question_resolution_conflict`	A parent-clarification retry supplied a different answer after the first resolution was already durably claimed.
`409`	`idempotency`	`idempotency_conflict`	The idempotency key was reused with a different payload.

Run states

These endpoints are relevant when a run enters one of these states:

waiting_for_approval
waiting_for_user_question

You can inspect those states through Sessions and runs API using:

GET /v1/sessions/{session_id}
GET /v1/runs/{run_id}

Relevant fields on RunView:

pending_approval_ids
pending_approvals
pending_question_ids
pending_questions

Question-producing tools may set:

expires_at_ms for an absolute Unix timestamp in milliseconds
expires_after_ms for a relative timeout from question creation

Expired normal user questions cancel the waiting run. Expired parent-clarification questions are delivered back to the requesting child as a declined clarification. Parent-clarification resolution is durable and idempotent. If the daemon restarts after an answer is captured but before every side effect finishes, startup replays the missing mailbox/output/audit work once. Parent interrupts and parent question cancellation are delivered to the child as declined clarifications. If the child has already been closed, the parent run still completes and the answer is moved to the child’s mailbox dead-letter queue. GET /v1/runs/{run_id}/events and GET /v1/sessions/{session_id}/events include a structured parent_clarification_resolved event for parent-clarification answers.

Operational notes

Approval resolution is batch-based: send every decision you want to resolve in the current request.
Approval batches are atomic per run: invalid, duplicate, or stale request IDs reject the batch without resolving any approval in that run.
approvals allow-all and approvals deny-all group work by run and submit one atomic batch per run; they are not one global transaction across multiple sessions or runs.
Session-scoped resume endpoints operate on the active waiting state for that session.
Run-scoped resume endpoints are safer when multiple suspended runs could exist over time and the client wants to target one exact waiting run.
CLI operators can answer with questions answer --interactive, decline with questions answer --declined, and cancel with questions cancel.

API reference

Operational reference

Questions and approvals API

Questions and approvals API

Endpoint inventory

Which endpoint should you use?

List pending user questions

Resolve approvals

Resolve structured user questions

Cancel structured user questions

Question errors

Run states

Operational notes

​Questions and approvals API

​Endpoint inventory

​Which endpoint should you use?

​List pending user questions

​Resolve approvals

​Resolve structured user questions

​Cancel structured user questions

​Question errors

​Run states

​Operational notes

Questions and approvals API

Endpoint inventory

Which endpoint should you use?

List pending user questions

Resolve approvals

Resolve structured user questions

Cancel structured user questions

Question errors

Run states

Operational notes