> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sparkles.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Create a sandbox

> Creates an asynchronously booting sandbox. An identical Idempotency-Key retry returns the same sandbox; changed request fields return 409.



## OpenAPI

````yaml /openapi.json post /api/public/v1/sandboxes
openapi: 3.1.0
info:
  title: Sparkles Sandbox API
  version: 1.0.0
  description: Create coding sandboxes, stream their work, and control their lifecycle.
servers:
  - url: https://sparkles.dev
security: []
paths:
  /api/public/v1/sandboxes:
    post:
      tags:
        - sandboxes
      summary: Create a sandbox
      description: >-
        Creates an asynchronously booting sandbox. An identical Idempotency-Key
        retry returns the same sandbox; changed request fields return 409.
      operationId: createSandbox
      parameters:
        - in: header
          name: Idempotency-Key
          schema:
            type: string
            minLength: 1
            maxLength: 255
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                repos:
                  minItems: 1
                  type: array
                  items:
                    type: object
                    properties:
                      fullName:
                        type: string
                        maxLength: 201
                        pattern: ^[A-Za-z0-9._-]+\/[A-Za-z0-9._-]+$
                      ref:
                        type: string
                        minLength: 1
                        maxLength: 255
                    required:
                      - fullName
                    additionalProperties: false
                prompt:
                  type: string
                  minLength: 1
                  maxLength: 60000
                model:
                  type: string
                  minLength: 1
                  maxLength: 200
                reasoningEffort:
                  type: string
                  enum:
                    - none
                    - low
                    - medium
                    - high
                    - xhigh
                    - max
                    - ultra
                    - ultracode
                title:
                  type: string
                  minLength: 1
                  maxLength: 120
                toolApprovalMode:
                  default: auto
                  type: string
                  enum:
                    - auto
                    - prompt
                metadata:
                  default: {}
                  type: object
                  propertyNames:
                    type: string
                    minLength: 1
                    maxLength: 64
                  additionalProperties:
                    type: string
                    maxLength: 1000
              required:
                - repos
                - prompt
              additionalProperties: false
      responses:
        '200':
          description: An identical sandbox creation was already accepted
          headers:
            Location:
              required: true
              schema:
                type: string
                format: uri
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    pattern: ^c_[a-z2-9]{12}$
                  worktreeId:
                    readOnly: true
                    type: string
                    minLength: 1
                  object:
                    type: string
                    const: sandbox
                  status:
                    type: string
                    enum:
                      - queued
                      - creating
                      - running
                      - succeeded
                      - failed
                      - terminating
                      - terminated
                  title:
                    type: string
                  repos:
                    type: array
                    items:
                      type: object
                      properties:
                        fullName:
                          type: string
                          maxLength: 201
                          pattern: ^[A-Za-z0-9._-]+\/[A-Za-z0-9._-]+$
                        ref:
                          type: string
                          minLength: 1
                          maxLength: 255
                      required:
                        - fullName
                      additionalProperties: false
                  model:
                    type:
                      - string
                      - 'null'
                  agentRuntime:
                    type: string
                    enum:
                      - opencode
                      - codex
                      - claude
                      - grok
                  turn:
                    type: object
                    properties:
                      active:
                        type: boolean
                    required:
                      - active
                    additionalProperties: false
                  usage:
                    type: object
                    properties:
                      llmRequestCount:
                        type: integer
                        minimum: 0
                        maximum: 9007199254740991
                      costMicroUsd:
                        type: integer
                        minimum: 0
                        maximum: 9007199254740991
                      creditsChargedMicros:
                        type: integer
                        minimum: 0
                        maximum: 9007199254740991
                    required:
                      - llmRequestCount
                      - costMicroUsd
                      - creditsChargedMicros
                    additionalProperties: false
                  metadata:
                    type: object
                    propertyNames:
                      type: string
                    additionalProperties:
                      type: string
                  error:
                    type:
                      - string
                      - 'null'
                  createdAt:
                    type: string
                  startedAt:
                    type:
                      - string
                      - 'null'
                  completedAt:
                    type:
                      - string
                      - 'null'
                  links:
                    type: object
                    properties:
                      self:
                        type: string
                        format: uri
                      events:
                        type: string
                        format: uri
                      messages:
                        type: string
                        format: uri
                    required:
                      - self
                      - events
                      - messages
                    additionalProperties: false
                required:
                  - id
                  - worktreeId
                  - object
                  - status
                  - title
                  - repos
                  - model
                  - agentRuntime
                  - turn
                  - usage
                  - metadata
                  - error
                  - createdAt
                  - startedAt
                  - completedAt
                  - links
                additionalProperties: false
        '201':
          description: Sandbox creation accepted
          headers:
            Location:
              required: true
              schema:
                type: string
                format: uri
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    pattern: ^c_[a-z2-9]{12}$
                  worktreeId:
                    readOnly: true
                    type: string
                    minLength: 1
                  object:
                    type: string
                    const: sandbox
                  status:
                    type: string
                    enum:
                      - queued
                      - creating
                      - running
                      - succeeded
                      - failed
                      - terminating
                      - terminated
                  title:
                    type: string
                  repos:
                    type: array
                    items:
                      type: object
                      properties:
                        fullName:
                          type: string
                          maxLength: 201
                          pattern: ^[A-Za-z0-9._-]+\/[A-Za-z0-9._-]+$
                        ref:
                          type: string
                          minLength: 1
                          maxLength: 255
                      required:
                        - fullName
                      additionalProperties: false
                  model:
                    type:
                      - string
                      - 'null'
                  agentRuntime:
                    type: string
                    enum:
                      - opencode
                      - codex
                      - claude
                      - grok
                  turn:
                    type: object
                    properties:
                      active:
                        type: boolean
                    required:
                      - active
                    additionalProperties: false
                  usage:
                    type: object
                    properties:
                      llmRequestCount:
                        type: integer
                        minimum: 0
                        maximum: 9007199254740991
                      costMicroUsd:
                        type: integer
                        minimum: 0
                        maximum: 9007199254740991
                      creditsChargedMicros:
                        type: integer
                        minimum: 0
                        maximum: 9007199254740991
                    required:
                      - llmRequestCount
                      - costMicroUsd
                      - creditsChargedMicros
                    additionalProperties: false
                  metadata:
                    type: object
                    propertyNames:
                      type: string
                    additionalProperties:
                      type: string
                  error:
                    type:
                      - string
                      - 'null'
                  createdAt:
                    type: string
                  startedAt:
                    type:
                      - string
                      - 'null'
                  completedAt:
                    type:
                      - string
                      - 'null'
                  links:
                    type: object
                    properties:
                      self:
                        type: string
                        format: uri
                      events:
                        type: string
                        format: uri
                      messages:
                        type: string
                        format: uri
                    required:
                      - self
                      - events
                      - messages
                    additionalProperties: false
                required:
                  - id
                  - worktreeId
                  - object
                  - status
                  - title
                  - repos
                  - model
                  - agentRuntime
                  - turn
                  - usage
                  - metadata
                  - error
                  - createdAt
                  - startedAt
                  - completedAt
                  - links
                additionalProperties: false
        '400':
          description: The request body or Idempotency-Key failed validation
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                      message:
                        type: string
                    required:
                      - code
                      - message
                    additionalProperties: false
                required:
                  - error
                additionalProperties: false
        '401':
          description: Missing, malformed, revoked, or otherwise invalid API key
          headers:
            WWW-Authenticate:
              required: true
              description: Bearer authentication challenge for the Sparkles Sandbox API
              schema:
                type: string
                description: Bearer authentication challenge for the Sparkles Sandbox API
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                      message:
                        type: string
                    required:
                      - code
                      - message
                    additionalProperties: false
                required:
                  - error
                additionalProperties: false
        '402':
          description: The organization has no credits remaining
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                      message:
                        type: string
                    required:
                      - code
                      - message
                    additionalProperties: false
                required:
                  - error
                additionalProperties: false
        '403':
          description: >-
            The API key lacks the sandboxes scope or its user is no longer an
            active organization member
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                      message:
                        type: string
                    required:
                      - code
                      - message
                    additionalProperties: false
                required:
                  - error
                additionalProperties: false
        '409':
          description: Idempotency or sandbox concurrency conflict
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                      message:
                        type: string
                    required:
                      - code
                      - message
                    additionalProperties: false
                required:
                  - error
                additionalProperties: false
        '413':
          description: Request body exceeded 64 KiB
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                      message:
                        type: string
                    required:
                      - code
                      - message
                    additionalProperties: false
                required:
                  - error
                additionalProperties: false
        '415':
          description: Content-Type was not application/json
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                      message:
                        type: string
                    required:
                      - code
                      - message
                    additionalProperties: false
                required:
                  - error
                additionalProperties: false
        '429':
          description: The API key exceeded its distributed per-minute request limit
          headers:
            Retry-After:
              required: true
              description: Seconds until another request may be made
              schema:
                type: string
                pattern: ^\d+$
                description: Seconds until another request may be made
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                      message:
                        type: string
                    required:
                      - code
                      - message
                    additionalProperties: false
                required:
                  - error
                additionalProperties: false
        '500':
          description: The request could not be completed because of an internal error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                      message:
                        type: string
                    required:
                      - code
                      - message
                    additionalProperties: false
                required:
                  - error
                additionalProperties: false
        '502':
          description: The sandbox command runtime is unavailable
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                      message:
                        type: string
                    required:
                      - code
                      - message
                    additionalProperties: false
                required:
                  - error
                additionalProperties: false
      security:
        - apiKey: []
components:
  securitySchemes:
    apiKey:
      type: http
      scheme: bearer
      bearerFormat: spk_live_…
      description: >-
        Long-lived opaque API key minted by an approved user at /api. The secret
        is shown once, stored only as a SHA-256 digest, and disabled immediately
        when either the key or its API access grant is revoked.

````