> ## Documentation Index
> Fetch the complete documentation index at: https://internal.september.wtf/llms.txt
> Use this file to discover all available pages before exploring further.

# HITL endpoints

> Endpoints for answering questions the agent asks during execution.

When the agent pauses to ask a question or request permission, it emits an
`hitl_request` SSE event and waits. You answer through these endpoints.

## POST /hitl/respond

Answer a pending HITL request. The agent loop resumes immediately.

### Request

```http theme={null}
POST /hitl/respond
X-Engine-Key: <key>
Content-Type: application/json

{
  "task_id": "task-001",
  "answer": "yes",
  "feedback": "Looks correct, go ahead.",
  "content_blocks": []
}
```

| Field            | Type   | Required | Purpose                                                                                |
| ---------------- | ------ | -------- | -------------------------------------------------------------------------------------- |
| `task_id`        | string | yes      | The task whose agent is paused.                                                        |
| `answer`         | string | yes      | The user's answer. For permission prompts: `"yes"` / `"no"`. For questions: free text. |
| `feedback`       | string | no       | Additional commentary the agent should consider.                                       |
| `content_blocks` | array  | no       | Structured content (e.g. images, files) to include in the response.                    |

### Response

```json theme={null}
{
  "status": "resumed",
  "request_id": "hitl-..."
}
```

Or `404` if no HITL request is pending for the given task.

## GET /hitl/pending

List HITL requests waiting for a response, across all tasks.

### Request

```http theme={null}
GET /hitl/pending
X-Engine-Key: <key>
```

### Response

```json theme={null}
{
  "pending": [
    {
      "request_id": "hitl-...",
      "task_id": "task-001",
      "kind": "permission",
      "question": "Should I delete /tmp/foo?",
      "created_at": "2026-04-27T12:34:56.000Z"
    }
  ]
}
```

## See also

* [Streaming events: hitl\_request](../streaming-events#hitl_request) for
  what the agent sends.
* [Permissions](../../agents-and-tools/permissions) for how the
  permission system decides what to ask about.