> ## Documentation Index > Fetch the complete documentation index at: https://docs.ascii.dev/llms.txt > Use this file to discover all available pages before exploring further. # Create box > Provision a new cloud computer. Store the returned `box.id` with your product job/session record. ## OpenAPI ````yaml openapi/box-v1.yaml POST /boxes openapi: 3.1.0 info: title: Box Public API v1 version: 1.0.0 description: > Public JSON API for creating, operating, prompting, observing, and exposing Box sandboxes from backend services, CI jobs, hosted workers, and Box automation products. The v1 reference intentionally documents the developer integration surface only. Dashboard billing actions are not part of v1. servers: - url: https://ascii.dev/api/box/v1 security: - BoxBearerAuth: [] tags: - name: Box description: >- Unified Box account, setup, lifecycle, prompting, event history, desktop access, and SSH operations. paths: /boxes: post: tags: - Box summary: Create box description: >- Provision a new cloud computer. Store the returned `box.id` with your product job/session record. operationId: create requestBody: required: false content: application/json: schema: $ref: '#/components/schemas/CreateBoxRequest' responses: '202': description: Box accepted for provisioning. content: application/json: schema: $ref: '#/components/schemas/CreateBoxResponse' examples: provisioning: value: ok: true type: box.created status: provisioning ttlSeconds: 3600 box: id: bx_23456789 name: Box 2026-05-31 12:00 state: provisioning url: null ip: null createdAt: '2026-05-31T12:00:00Z' updatedAt: '2026-05-31T12:00:00Z' archiveAfter: '2026-05-31T13:00:00Z' desktopAvailable: false desktopUrl: null snapshotAvailable: false snapshotCompletedAt: null '401': $ref: '#/components/responses/Unauthorized' '402': $ref: '#/components/responses/PaymentRequired' '409': $ref: '#/components/responses/Conflict' '429': $ref: '#/components/responses/RateLimited' components: schemas: CreateBoxRequest: type: object description: Options for provisioning a new cloud computer. properties: ttlSeconds: oneOf: - type: integer minimum: 1 maximum: 2592000 - type: 'null' default: 3600 description: >- Number of seconds before automatic archival. `null` disables auto-stop. The backend also accepts the string `infinite` for legacy compatibility; new clients should send null. env: type: object additionalProperties: type: string description: >- Per-box environment variables injected into the box's tool environment, on top of the account environment's variables (per-box values win on conflicts). Keys must match `[A-Za-z_][A-Za-z0-9_]{0,127}`; at most 100 variables and 64KB total. Reserved names (`ASCII_TOKEN`, `ASCII_API_URL`, `AGENT_ID`, `PRODUCT_MODE`, `ENVIRONMENT_ID`, `BOX_ID`, `SERVICE_PREVIEW_TOKEN`, `BOX_CLI_TOKEN`) are rejected with `invalid_env`. Forked boxes inherit the source box's env unless the fork request supplies its own `env`. noEnv: type: boolean default: false description: >- Create a box with none of the secrets attached to your account (no environment variables, secret files, or credentials), confined to itself so it cannot act on your account or other boxes. For boxes you give to your own users. SSH, SCP, desktop, snapshots, and public URLs still work; pass `env` to give the box a secret of its own. A fork of a no-env box is always no-env. examples: - ttlSeconds: 3600 - ttlSeconds: null - ttlSeconds: 3600 env: DATABASE_URL: postgres://user:pass@host:5432/app FEATURE_FLAG: '1' - ttlSeconds: null noEnv: true CreateBoxResponse: allOf: - $ref: '#/components/schemas/SuccessBase' - type: object required: - status - ttlSeconds - box properties: type: type: string const: box.created status: type: string enum: - provisioning ttlSeconds: type: - integer - 'null' box: $ref: '#/components/schemas/Box' SuccessBase: type: object required: - ok - type properties: ok: type: boolean examples: - true type: type: string description: Stable success envelope discriminator added by v1. Box: type: object required: - id - name - state - desktopAvailable - snapshotAvailable properties: id: type: string pattern: ^bx_[23456789abcdefghjkmnpqrstuvwxyz]{8}$ examples: - bx_23456789 name: type: string examples: - Box 2026-05-31 12:00 state: type: string enum: - init - provisioning - provisioned - cloning - ready - idle - running - archiving - archived - error url: type: - string - 'null' format: uri description: Machine URL when assigned. ip: type: - string - 'null' description: Machine IPv4 address when assigned. createdAt: type: - string - 'null' format: date-time updatedAt: type: - string - 'null' format: date-time archiveAfter: type: - string - 'null' format: date-time description: Automatic archival time, or null when auto-stop is disabled. desktopAvailable: type: boolean desktopUrl: type: - string - 'null' format: uri description: Secret-bearing desktop stream URL when available. Redact from logs. snapshotAvailable: type: boolean snapshotCompletedAt: type: - string - 'null' format: date-time description: >- Timestamp of the most recent successfully completed snapshot, or null. subdomain: type: - string - 'null' description: >- The box's stable three-word subdomain slug (e.g. "frazil-pneuma-rallye"), or null before one is assigned. lastSnapshotAttemptAt: type: - string - 'null' format: date-time description: >- Timestamp of the most recent snapshot attempt of any status (queued, in_progress, completed, failed, cancelled), or null. Use with snapshotCompletedAt to detect snapshots that keep failing. lastSnapshotStatus: type: - string - 'null' enum: - queued - in_progress - completed - failed - cancelled - null description: >- Status of the most recent snapshot attempt, or null if none. A value other than completed while snapshotCompletedAt stays stale indicates failing snapshots. ErrorEnvelope: type: object required: - ok - type - status - code - message - error - requestId properties: ok: type: boolean examples: - false type: type: string examples: - box.error status: type: integer examples: - 409 code: type: string examples: - provider_not_configured message: type: string examples: - Prompting is locked until Codex is configured on the Agents page. requestId: type: string examples: - req_01HX... error: type: object required: - code - message - status properties: code: type: string message: type: string status: type: integer details: type: object additionalProperties: true responses: Unauthorized: description: Missing or invalid bearer token. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' examples: unauthorized: value: ok: false type: box.error status: 401 code: unauthorized message: Unauthorized error: code: unauthorized message: Unauthorized status: 401 requestId: req_01HX... PaymentRequired: description: >- 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. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' Conflict: description: Request conflicts with current account or box state. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' RateLimited: description: Creation or active-box limit reached. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' securitySchemes: BoxBearerAuth: type: http scheme: bearer bearerFormat: box_api_key description: >- Box bearer token in the form `box_...`. Service API keys authenticate Box operations. ````