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

{
  "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": false,
  "type": "box.error",
  "status": 409,
  "code": "provider_not_configured",
  "message": "Prompting is locked until Codex is configured on the Agents page.",
  "requestId": "req_01HX...",
  "error": {
    "code": "<string>",
    "message": "<string>",
    "status": 123,
    "details": {}
  }
}

{
  "ok": false,
  "type": "box.error",
  "status": 409,
  "code": "provider_not_configured",
  "message": "Prompting is locked until Codex is configured on the Agents page.",
  "requestId": "req_01HX...",
  "error": {
    "code": "<string>",
    "message": "<string>",
    "status": 123,
    "details": {}
  }
}

{
  "ok": false,
  "type": "box.error",
  "status": 409,
  "code": "provider_not_configured",
  "message": "Prompting is locked until Codex is configured on the Agents page.",
  "requestId": "req_01HX...",
  "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.

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.

provider

enum<string>

required

Available options:

codex,

claude-code,

claude,

pi,

opencode,

prime-agent,

prime,

kimi,

kimi-code

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

string | null

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.

Example:

"high"

new

boolean

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.

Example:

true

conversationId

string<uuid> | null

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.

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

conversationId

string | null

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.

model

string | null

reasoningEffort

string | null

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

{
  "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": false,
  "type": "box.error",
  "status": 409,
  "code": "provider_not_configured",
  "message": "Prompting is locked until Codex is configured on the Agents page.",
  "requestId": "req_01HX...",
  "error": {
    "code": "<string>",
    "message": "<string>",
    "status": 123,
    "details": {}
  }
}

{
  "ok": false,
  "type": "box.error",
  "status": 409,
  "code": "provider_not_configured",
  "message": "Prompting is locked until Codex is configured on the Agents page.",
  "requestId": "req_01HX...",
  "error": {
    "code": "<string>",
    "message": "<string>",
    "status": 123,
    "details": {}
  }
}

{
  "ok": false,
  "type": "box.error",
  "status": 409,
  "code": "provider_not_configured",
  "message": "Prompting is locked until Codex is configured on the Agents page.",
  "requestId": "req_01HX...",
  "error": {
    "code": "<string>",
    "message": "<string>",
    "status": 123,
    "details": {}
  }
}