ariana-dot-dev/kimi-box-plugin/box-api

Box HTTP API v1

Base URL: https://ascii.dev/api/box/v1 — auth is Authorization: Bearer $BOX_API_KEY on every request (create keys in the Box dashboard, API Keys tab). For typed clients prefer the SDKs (box-sdk-typescript / box-sdk-python skills); for shell integration the CLI (box-cli skill).

Response envelope & errors

Every v1 JSON body has ok (boolean) and type (stable discriminator, e.g. box.list, prompt.queued). Errors keep HTTP status authoritative and add a structured envelope:

{"ok": false, "type": "box.error", "status": 409, "code": "provider_not_configured", "message": "...", "error": {"code": "...", "message": "...", "status": 409, "details": {}}, "requestId": "req_..."}

Lifecycle states

provisioning/provisioned/cloning → poll GET /boxes/{id}; ready/idle → accepts prompts and access; running → agent work in progress; archiving → poll to archived; archived → resume or fork; error → show error, allow stop/delete/resume/fork.

idle/running only track work queued via POST /prompt — your own SSH/command-endpoint processes do not change state. Wait for ready or idle before sending commands (earlier commands run before per-box env is applied).

Prompt providers

codex (models gpt-5.5, gpt-5.4 default, gpt-5.4-mini, gpt-5.3-codex; efforts none–xhigh) and claude-code (models claude-fable-5, opus, sonnet default, haiku; efforts low–max except haiku). claude is accepted as an alias; store claude-code. Omit model to use the account's saved default. Missing provider credentials → provider_not_configured with a setup URL.

Core loop (curl)

export BOX_API_BASE="https://ascii.dev/api/box/v1"
 
BOX_ID=$(curl -sS -X POST "$BOX_API_BASE/boxes" \
  -H "Authorization: Bearer $BOX_API_KEY" -H "Content-Type: application/json" \
  -d '{"ttlSeconds":3600}' | jq -r '.box.id')
 
curl -sS "$BOX_API_BASE/boxes/$BOX_ID" -H "Authorization: Bearer $BOX_API_KEY"   # poll until ready/idle
 
curl -sS -X POST "$BOX_API_BASE/boxes/$BOX_ID/prompt" \
  -H "Authorization: Bearer $BOX_API_KEY" -H "Content-Type: application/json" \
  -d '{"provider":"codex","model":"gpt-5.4","reasoningEffort":"medium","prompt":"Run tests, fix failures, report back."}'
 
curl -sS "$BOX_API_BASE/boxes/$BOX_ID/events" -H "Authorization: Bearer $BOX_API_KEY"
curl -sS -X POST "$BOX_API_BASE/boxes/$BOX_ID/stop" -H "Authorization: Bearer $BOX_API_KEY"

Create options: ttlSeconds (null = no auto-stop, max 2592000), env (per-box vars), noEnv: true (withhold all account secrets — required for boxes given to your users). Run any in-box tool (including host and lux) through POST /boxes/{boxId}/commands: {"command":"host 3000 --private","cwd":"my-repo","timeoutSeconds":60}.

Endpoints

Treat API keys, desktopUrl, and any _token URL as secrets — never log them unredacted.

Full per-endpoint reference: https://docs.ascii.dev/box/api/v1 (OpenAPI: https://docs.ascii.dev/openapi/box-v1.yaml)