> ## Documentation Index
> Fetch the complete documentation index at: https://docs.toolshed.philo.ventures/llms.txt
> Use this file to discover all available pages before exploring further.

# Elicitation Routes

> Store, poll, and resolve pending approval requests.

<Snippet file="stub-warning.mdx" />

## Create pending elicitation

```
POST /api/elicitation
```

Stores a pending approval request from the runtime.

### Request body

```json theme={null}
{
  "executionId": "abc-123",
  "toolPath": "github.issues.create",
  "message": "Create issue \"Fix login bug\" in my-org/my-repo?",
  "args": { "owner": "my-org", "repo": "my-repo", "title": "Fix login bug" },
  "type": "approval"
}
```

Validated against `ElicitationRequestSchema`:

| Field         | Type     | Required | Default      | Description                              |
| ------------- | -------- | -------- | ------------ | ---------------------------------------- |
| `executionId` | `string` | Yes      | --           | Unique execution ID                      |
| `toolPath`    | `string` | Yes      | --           | Tool requesting approval                 |
| `message`     | `string` | Yes      | --           | Human-readable description of the action |
| `args`        | `object` | No       | --           | Arguments to the tool                    |
| `type`        | `string` | No       | `"approval"` | `"approval"` or `"form"`                 |

### Response (201)

```json theme={null}
{
  "stored": true,
  "executionId": "abc-123"
}
```

***

## Poll elicitation status

```
GET /api/elicitation/:id
```

Check whether a pending elicitation has been resolved.

| Parameter | In   | Required | Description  |
| --------- | ---- | -------- | ------------ |
| `id`      | path | Yes      | Execution ID |

**Response (200):**

```json theme={null}
{
  "executionId": "abc-123",
  "status": "pending"
}
```

<Note>
  The poll endpoint returns a `status` string. Once resolved via the resolve endpoint below, the response shape changes to use the `ElicitationResponseSchema` which has an `approved` boolean field instead of a status string.
</Note>

***

## Resolve elicitation

```
POST /api/elicitation/:id/resolve
```

Approve or deny a pending elicitation.

| Parameter | In   | Required | Description  |
| --------- | ---- | -------- | ------------ |
| `id`      | path | Yes      | Execution ID |

### Request body

```json theme={null}
{
  "approved": true,
  "data": {}
}
```

Validated against `ElicitationResponseSchema`:

| Field      | Type      | Required | Description                                            |
| ---------- | --------- | -------- | ------------------------------------------------------ |
| `approved` | `boolean` | Yes      | Whether to approve the action                          |
| `data`     | `object`  | No       | Additional form data (for `type: "form"` elicitations) |

### Response (200)

```json theme={null}
{
  "executionId": "abc-123",
  "approved": true,
  "resolved": true
}
```