Prompt Box - ascii

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"
}

{
  "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..."
}

{
  "ok": false,
  "type": "box.error",
  "status": 401,
  "code": "unauthorized",
  "message": "Unauthorized",
  "error": {
    "code": "unauthorized",
    "message": "Unauthorized",
    "status": 401
  },
  "requestId": "req_01HX..."
}

{
  "ok": true,
  "type": "<string>",
  "status": 123,
  "code": "<string>",
  "message": "<string>",
  "requestId": "<string>",
  "error": {
    "code": "<string>",
    "message": "<string>",
    "status": 123,
    "details": {}
  }
}

{
  "ok": true,
  "type": "<string>",
  "status": 123,
  "code": "<string>",
  "message": "<string>",
  "requestId": "<string>",
  "error": {
    "code": "<string>",
    "message": "<string>",
    "status": 123,
    "details": {}
  }
}

{
  "ok": true,
  "type": "<string>",
  "status": 123,
  "code": "<string>",
  "message": "<string>",
  "requestId": "<string>",
  "error": {
    "code": "<string>",
    "message": "<string>",
    "status": 123,
    "details": {}
  }
}

Authorizations

Authorization

string

header

required

Box bearer token in the form box_.... Service API keys authenticate Box operations.

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 claude-fable-5, 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"

"claude-fable-5"

"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 claude-fable-5 and opus support low, medium, high, max; sonnet supports low, medium, high; haiku has no reasoning control.

Example:

"medium"

Response

Prompt queued.

boolean

required

Example:

true

type

string

required

Stable success envelope discriminator added by v1.

Allowed value: "prompt.queued"

string

required

Box id.

promptId

string

required

promptRun

object

required

Show child attributes

status

enum<string>

required

Available options:

queued

provider

string

required

model

string | null

reasoningEffort

string | null

List box eventsReturn Box work, lifecycle, and progress events so product UIs can show what the box is doing. Event payloads are extensible. Clients can long-poll this endpoint with `sort=asc` and a cursor to stream responses. Response events expose agent text, streaming partials via `data.is_streaming`, and tool calls/results via `data.tools`.

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"
}

{
  "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..."
}

{
  "ok": false,
  "type": "box.error",
  "status": 401,
  "code": "unauthorized",
  "message": "Unauthorized",
  "error": {
    "code": "unauthorized",
    "message": "Unauthorized",
    "status": 401
  },
  "requestId": "req_01HX..."
}

{
  "ok": true,
  "type": "<string>",
  "status": 123,
  "code": "<string>",
  "message": "<string>",
  "requestId": "<string>",
  "error": {
    "code": "<string>",
    "message": "<string>",
    "status": 123,
    "details": {}
  }
}

{
  "ok": true,
  "type": "<string>",
  "status": 123,
  "code": "<string>",
  "message": "<string>",
  "requestId": "<string>",
  "error": {
    "code": "<string>",
    "message": "<string>",
    "status": 123,
    "details": {}
  }
}

{
  "ok": true,
  "type": "<string>",
  "status": 123,
  "code": "<string>",
  "message": "<string>",
  "requestId": "<string>",
  "error": {
    "code": "<string>",
    "message": "<string>",
    "status": 123,
    "details": {}
  }
}