Resolve body fields depend on kind (
tool_approval, input_required, auth_required) — see Resolve a request below.
Authentication
Every route takes the session JWT fromPOST /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:
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 indata).
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’skind; the rest are ignored.
answer (each item), custom_answer, and note are limited to 8,192 bytes each.
tool_approval
approvesetsstatustoresolved.rejectsets it torejected, 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_responseis{ "decision", "scope", "note" }.scopeisnullon a rejection.
input_required
The accepted answer depends on the question:
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:
{ "auth_action": "start" }when the human opens the sign-in link (question.auth_url). The request stayspending, andhuman_response.auth_outcomebecomesstartedso other clients can show that sign-in is under way.{ "auth_action": "confirm" }once sign-in is done. The request moves toresolvedwithhuman_response{ "auth_outcome": "confirmed" }, and the run resumes.
Example
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
200with the existing decision andalready_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. Watchresume_statuswithGET /api/hitl/{id}or the/streamroute:completedmeans the run picked up the answer;failed,delivery_outcome_unknown, oragent_lost_taskmean 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
200withalready_canceled: true. Retrying is safe. - Ctrl+C at a CLI prompt does not call this route. The request stays
pendinguntil you resolve or cancel it.