---
title: "Prompt Box"
method: POST
path: "/boxes/{boxId}/prompt"
tags: ["Box"]
---

# Prompt Box

`POST /boxes/{boxId}/prompt`

Queue a natural-language work item for Codex or Claude Code inside the box. Observe progress with `GET /boxes/{boxId}/events`.

## Path parameters

- `boxId` string, required

## Request body

- PromptRequest — Work item to queue inside an existing Box. Provider credentials must already be configured in the Box dashboard. Provider values: `codex`, `claude-code`; the backend currently also accepts `claude` as an alias for `claude-code`. Recommended model ids come from `backend/models.json`: Codex `gpt-5.5`, `gpt-5.4`, `gpt-5.4-mini`, `gpt-5.3-codex`; Claude Code `claude-fable-5`, `opus`, `sonnet`, `haiku`. If omitted, the user's saved provider default is used.
  - `provider` 'codex' | 'claude-code' | 'claude', required
  - `model` string, nullable — Optional provider model id. Prefer the documented ids; unknown explicit ids are currently forwarded rather than rejected by request validation.
  - `reasoningEffort` string, nullable — Optional reasoning effort. Codex supports `none`, `low`, `medium`, `high`, `xhigh` for GPT-5.4/5.5/5.4-mini and `low`, `medium`, `high`, `xhigh` for GPT-5.3 Codex. Claude `claude-fable-5` and `opus` support `low`, `medium`, `high`, `max`; `sonnet` supports `low`, `medium`, `high`; `haiku` has no reasoning control.
  - `prompt` string, required — Natural-language task for the Box, including repo, preview, or browser-use instructions.

## Response `202`

Prompt queued.

- PromptResponse
  - `ok` boolean, required
  - `type` 'prompt.queued', required — Stable success envelope discriminator added by v1.
  - `id` string, required — Box id.
  - `promptId` string, required
  - `promptRun` PromptRun, required
    - `id` string, required
    - `promptId` string, required
    - `boxId` string, required
    - `status` 'sending' | 'queued' | 'running' | 'finished' | 'failed', required
    - `done` boolean, required
    - `createdAt` string, date-time, nullable
    - `model` string, nullable
    - `reasoningEffort` string, nullable
  - `status` 'queued', required
  - `provider` string, required
  - `model` string, nullable
  - `reasoningEffort` string, nullable

## Other responses

- `400` — Invalid request body or parameters.
- `401` — Missing or invalid bearer token.
- `402` — 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.
- `404` — Resource not found.
- `409` — Request conflicts with current account or box state.

---

[API](https://skmtc.dev/ascii/apis/box-public-api-v1.md) · [All operations](https://skmtc.dev/ascii/apis/box-public-api-v1/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/ascii/box-public-api-v1/revisions/82d576f82046/schema)