> ## Documentation Index > Fetch the complete documentation index at: https://docs.boat.dev/llms.txt > Use this file to discover all available pages before exploring further. # Prompt Boat > Queue a natural-language work item for an agent harness (Codex, Claude Code, pi, OpenCode, or Prime Agent) inside the box. Observe progress with `GET /boxes/{boxId}/events`. A Box runs many conversations in parallel. Set `new: true` to start a fresh one, `conversationId` to continue a specific one, or omit both to continue the most-recently-active conversation; the response returns the `conversationId`. See [Integrated agents](/box/integrated-agents). ## OpenAPI ````yaml openapi/box-v1.yaml POST /boxes/{boxId}/prompt openapi: 3.1.0 info: title: Boat Public API v1 version: 1.0.0 description: > Public JSON API for creating, operating, prompting, observing, and exposing Boat sandboxes from backend services, CI jobs, hosted workers, and Boat automation products. The v1 reference intentionally documents the developer integration surface only. Dashboard billing actions are not part of v1. servers: - url: https://ascii.dev/api/box/v1 security: - BoxBearerAuth: [] tags: - name: Box description: >- Unified Boat account, setup, lifecycle, prompting, event history, desktop access, and SSH operations. paths: /boxes/{boxId}/prompt: post: tags: - Box summary: Prompt Boat description: >- Queue a natural-language work item for an agent harness (Codex, Claude Code, pi, OpenCode, or Prime Agent) inside the box. Observe progress with `GET /boxes/{boxId}/events`. A Box runs many conversations in parallel. Set `new: true` to start a fresh one, `conversationId` to continue a specific one, or omit both to continue the most-recently-active conversation; the response returns the `conversationId`. See [Integrated agents](/box/integrated-agents). operationId: prompt parameters: - $ref: '#/components/parameters/BoxId' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/PromptRequest' examples: repoWork: value: provider: codex model: gpt-5.4 reasoningEffort: medium prompt: >- Work on the selected repo, run tests, fix failures, commit the result, and report any hosted preview URL. computerUse: value: provider: claude-code model: sonnet reasoningEffort: high prompt: >- Use the browser to research flight options to France and return the best itinerary summary with source links. responses: '202': description: Prompt queued. content: application/json: schema: $ref: '#/components/schemas/PromptResponse' examples: queued: value: ok: true type: prompt.queued id: bx_23456789 promptId: prompt_123 conversationId: 8f1c2b7a-3d4e-4f5a-9b0c-1d2e3f4a5b6c promptRun: id: prompt_123 promptId: prompt_123 boxId: bx_23456789 status: queued done: false conversationId: 8f1c2b7a-3d4e-4f5a-9b0c-1d2e3f4a5b6c status: queued provider: codex model: gpt-5.4 reasoningEffort: medium '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '402': $ref: '#/components/responses/PaymentRequired' '404': $ref: '#/components/responses/NotFound' '409': $ref: '#/components/responses/Conflict' components: parameters: BoxId: name: boxId in: path required: true schema: type: string pattern: ^bx_[23456789abcdefghjkmnpqrstuvwxyz]{8}$ description: Public Box id returned by create/list/get box calls. schemas: PromptRequest: type: object description: > Work item to queue inside an existing Boat. Provider credentials must already be configured in the Boat dashboard. **Providers (harnesses):** `codex`, `claude-code` (alias `claude`), `pi`, `opencode`, `prime-agent` (alias `prime`), `kimi` (Kimi Code CLI, alias `kimi-code`). Omit `provider` to use the harness the user selected on the Agents dashboard. **Models & reasoning effort** are harness- and model-specific and change over time. Fetch the live catalog (every provider's models and which reasoning-effort levels each accepts) from `GET /provider-models`. Some models accept no reasoning control. `pi`, `opencode` and `prime-agent` also expose models routed through OpenRouter and llmgateway (ids like `openrouter:anthropic/claude-sonnet-4.5`). **Conversations:** a Box runs many conversations in parallel, each with its own history. Set `new: true` to start a fresh conversation, or `conversationId` to continue a specific one; omit both to continue the Box's most-recently-active conversation. The response returns the `conversationId` this prompt ran in. Conversations run concurrently up to a per-box limit that scales with the Box's memory; beyond it, prompts queue. required: - provider - prompt properties: provider: type: string enum: - codex - claude-code - claude - pi - opencode - prime-agent - prime - kimi - kimi-code model: type: - string - 'null' description: >- Optional provider model id from `GET /provider-models`. Omit to use the model selected for that harness on the Agents dashboard. Unknown explicit ids are currently forwarded rather than rejected by request validation. examples: - gpt-5.6-terra - claude-sonnet-5 - openrouter:anthropic/claude-sonnet-4.5 reasoningEffort: type: - string - 'null' description: >- Optional reasoning/thinking level (e.g. `none`, `low`, `medium`, `high`, `xhigh`, `max`). Which levels a given model accepts is listed per model in `GET /provider-models`; some models accept none. examples: - high new: type: boolean description: >- Start a NEW conversation on the Box (runs in parallel with any existing ones) instead of continuing the most-recently-active one. Mutually exclusive with `conversationId`. examples: - true conversationId: type: - string - 'null' description: >- Continue a specific conversation by id (as returned by a previous prompt). Omit (and omit `new`) to continue the Box's most-recently-active conversation. format: uuid prompt: type: string minLength: 1 description: >- Natural-language task for the Boat, including repo, preview, or browser-use instructions. examples: - provider: codex model: gpt-5.4 reasoningEffort: medium prompt: >- Work on the selected repo, run tests, fix failures, commit the result, and report any hosted preview URL. - provider: claude new: true prompt: >- Start a second, independent task on the auth module while the first keeps running. PromptResponse: allOf: - $ref: '#/components/schemas/SuccessBase' - type: object required: - id - promptId - promptRun - status - provider properties: type: type: string const: prompt.queued id: type: string description: Box id. promptId: type: string conversationId: type: - string - 'null' description: >- The conversation this prompt was queued in. A new one when `new` was set, the one named by `conversationId`, or the Box's most-recently-active conversation. See [Integrated agents](/box/integrated-agents). promptRun: $ref: '#/components/schemas/PromptRun' status: type: string enum: - queued provider: type: string model: type: - string - 'null' reasoningEffort: type: - string - 'null' SuccessBase: type: object required: - ok - type properties: ok: type: boolean examples: - true type: type: string description: Stable success envelope discriminator added by v1. PromptRun: type: object required: - id - promptId - boxId - status - done properties: id: type: string promptId: type: string boxId: type: string status: type: string enum: - sending - queued - running - finished - failed - interrupted done: type: boolean createdAt: type: - string - 'null' format: date-time model: type: - string - 'null' reasoningEffort: type: - string - 'null' conversationId: type: - string - 'null' description: >- The conversation this prompt ran in. A Box runs many conversations in parallel; see [Integrated agents](/box/integrated-agents). ErrorEnvelope: type: object required: - ok - type - status - code - message - error - requestId properties: ok: type: boolean examples: - false type: type: string examples: - box.error status: type: integer examples: - 409 code: type: string examples: - provider_not_configured message: type: string examples: - Prompting is locked until Codex is configured on the Agents page. requestId: type: string examples: - req_01HX... error: type: object required: - code - message - status properties: code: type: string message: type: string status: type: integer details: type: object additionalProperties: true responses: BadRequest: description: Invalid request body or parameters. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' examples: invalid: value: ok: false type: box.error status: 400 code: invalid_json message: Request body must be valid JSON. error: code: invalid_json message: Request body must be valid JSON. status: 400 requestId: req_01HX... Unauthorized: description: Missing or invalid bearer token. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' examples: unauthorized: value: ok: false type: box.error status: 401 code: unauthorized message: Unauthorized error: code: unauthorized message: Unauthorized status: 401 requestId: req_01HX... PaymentRequired: description: >- Account cannot currently create or operate Boxes. The error body may include a dashboard billing URL, but billing actions are not part of the v1 API. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' NotFound: description: Resource not found. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' Conflict: description: Request conflicts with current account or box state. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' securitySchemes: BoxBearerAuth: type: http scheme: bearer bearerFormat: box_api_key description: >- Boat bearer token in the form `box_...`. Service API keys authenticate Boat operations. ````