Skip to main content
Not in the generated OpenAPI spec. Behavioral guide: Approvals. Resolve body fields depend on kind (tool_approval, input_required, auth_required) — see Resolve a request below.

Authentication

Every route takes the session JWT from POST /api/auth/login as Authorization: Bearer <token>, or the dashboard session cookie. None of these routes is rate limited. A request belongs to the user whose agent run paused — its owner. Only the owner or a superuser can view, resolve, or cancel it. Role tiers don’t change this: an admin who isn’t a superuser can’t act on another user’s request. A missing or invalid credential returns 401 before the handler runs:
Handler errors on these routes return a plain-text body (for example hitl request not found), except a 500, which returns JSON with a correlation ID you can quote to your operator:

The request object

Every route on this page returns the same object (the list wraps it in data). allowed_actions per kind: execution fields: question is the JSON the agent sent. Common fields: A pending request expires after HITL_REQUEST_TTL_DAYS (default 7) days.

List pending requests

GET /api/hitl/pending Returns every request still waiting on a human, oldest first. Use it to build an inbox or to find a pause your client didn’t see live. The dashboard’s Waiting list in Chat reads this route. Auth: session JWT or dashboard cookie. Any authenticated user; you see only your own requests. A superuser sees every user’s. The list isn’t paginated and takes no query parameters. When an agent re-raises an MCP tool approval as its own pause, only the MCP tool request is listed — resolving that one resumes both.

Example

Errors

Get a request

GET /api/hitl/{id} Returns one request in any state. Use it to show the question, or to poll after you resolve until resume_status leaves not_started. For push updates, open GET /api/hitl/{id}/stream instead. Auth: session JWT or dashboard cookie. Owner or superuser.

Path parameters

Example

Errors

Resolve a request

POST /api/hitl/{id}/resolve Records the human’s decision and resumes the paused run. This is what the Approve, Reject, and answer controls in Chat call, and what nasiko chat and nasiko maf workflow run --wait call when you answer inline. Auth: session JWT or dashboard cookie. Owner or superuser.

Path parameters

Request body

One body shape covers all three kinds. Send only the fields for the request’s kind; the rest are ignored. answer (each item), custom_answer, and note are limited to 8,192 bytes each.

tool_approval

  • approve sets status to resolved. reject sets it to rejected, and the run receives the rejection.
  • scope: "once" allows this one call. scope: "session" also allows the same tool, on the same connector, for the same agent, for the rest of this conversation — for up to 24 hours — without asking again.
  • The recorded human_response is { "decision", "scope", "note" }. scope is null on a rejection.

input_required

The accepted answer depends on the question:
The request moves to resolved. When the pause came from a chat conversation, your answer is also added to that conversation as your message.

auth_required

Authorization is two calls:
  1. { "auth_action": "start" } when the human opens the sign-in link (question.auth_url). The request stays pending, and human_response.auth_outcome becomes started so other clients can show that sign-in is under way.
  2. { "auth_action": "confirm" } once sign-in is done. The request moves to resolved with human_response { "auth_outcome": "confirmed" }, and the run resumes.
To decline, cancel the request.

Example

The response adds already_resolved (except for auth_action: "start", which returns the plain request object).

Behavior

  • First decision wins. If the request was already resolved or rejected — by you in another tab, or by another client — the call doesn’t change it. It returns 200 with the existing decision and already_resolved: true. Retrying a resolve is safe.
  • Resuming is asynchronous. The response returns once the decision is recorded, usually with resume_status: "not_started". Nasiko then delivers the answer to the paused agent. Watch resume_status with GET /api/hitl/{id} or the /stream route: completed means the run picked up the answer; failed, delivery_outcome_unknown, or agent_lost_task mean it didn’t.
  • When an agent re-raised an MCP tool approval as its own pause, resolving the MCP tool request also resolves the agent’s pause, so the run resumes once.

Errors

Cancel a request

POST /api/hitl/{id}/cancel Withdraws a pending request without answering it. Use it to decline an auth_required sign-in, or to clear a request nobody will answer. The request moves to canceled. No body. Auth: session JWT or dashboard cookie. Owner or superuser.

Path parameters

Example

Behavior

  • Canceling an already-canceled request returns 200 with already_canceled: true. Retrying is safe.
  • Ctrl+C at a CLI prompt does not call this route. The request stays pending until you resolve or cancel it.

Errors