# Prompt a harness

`POST /v1/sandboxes/{sandbox}/prompts`

**In this build:** Works on the simulator or a real VM.

**Scope:** `agent.prompt`

**CLI:** `harebox prompt`

Send an `Idempotency-Key` header. A retry with the same key never repeats the action.

## Request: `PromptRequest`

| Field | Type | Notes |
|---|---|---|
| `prompt` (required) | `string` |  |
| `harness` | `string` | See GET /harnesses. Claude Code, Codex, pi, OpenCode, Prime Agent, Kimi Code, Mistral Vibe, Hermes, OpenClaw, Cursor CLI or an adapter you add. |
| `model` | `string` |  |
| `reasoning_effort` | `string` |  |
| `fast` | `boolean` |  |
| `conversation` | `string` | Continue this conversation. Omit to continue the current one. |
| `new_conversation` | `boolean` |  |
| `attachments` | `array` |  |
| `budget_usd` | `number` | Stop this turn when proxied token spend passes this amount. |
| `webhook_url` | `string` | Also notify this URL when the prompt ends. |

## Response: 202

`Prompt`

| Field | Type | Notes |
|---|---|---|
| `id` (required) | `string` |  |
| `conversation` (required) | `string` |  |
| `status` (required) | `string` | One of: `queued`, `running`, `finished`, `failed`, `interrupted`, `budget_exceeded` |
| `harness` | `string` |  |
| `model` | `string` |  |
| `usage` | `object` |  |
| `error` | `object` |  |

Errors follow [one format](../errors.html).