Skip to main content
POST
/
boxes
/
{boxId}
/
prompt
curl --request POST \ --url https://ascii.dev/api/box/v1/boxes/{boxId}/prompt \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data ' { "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." } '
{
  "ok": true,
  "type": "prompt.queued",
  "id": "bx_23456789",
  "promptId": "prompt_123",
  "promptRun": {
    "id": "prompt_123",
    "promptId": "prompt_123",
    "boxId": "bx_23456789",
    "status": "queued",
    "done": false
  },
  "status": "queued",
  "provider": "codex",
  "model": "gpt-5.4",
  "reasoningEffort": "medium"
}

Authorizations

​
Authorization
string
header
required

Box API key in the form box_.... Create and rotate keys in the Box dashboard or through the v1 API key endpoints.

Path Parameters

​
boxId
string
required

Public Box id returned by create/list/get box calls.

Pattern: ^bx_[23456789abcdefghjkmnpqrstuvwxyz]{8}$

Body

application/json

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 opus, sonnet, haiku. If omitted, the user's saved provider default is used.

​
provider
enum<string>
required
Available options:
codex,
claude-code,
claude
​
prompt
string
required

Natural-language task for the Box, including repo, preview, or browser-use instructions.

Minimum string length: 1
​
model
string | null

Optional provider model id. Prefer the documented ids; unknown explicit ids are currently forwarded rather than rejected by request validation.

Examples:

"gpt-5.4"

"sonnet"

​
reasoningEffort
string | null

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 opus supports low, medium, high, max; sonnet supports low, medium, high; haiku has no reasoning control.

Example:

"medium"

Response

Prompt queued.

​
ok
boolean
required
Example:

true

​
type
string
required

Stable success envelope discriminator added by v1.

Allowed value: "prompt.queued"
​
id
string
required

Box id.

​
promptId
string
required
​
promptRun
object
required
​
status
enum<string>
required
Available options:
queued
​
provider
string
required
​
model
string | null
​
reasoningEffort
string | null