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

# List your sandboxes

> Your live sandboxes on this box, oldest first. Other callers' sandboxes are never listed.

Needs the `view` scope.



## OpenAPI

````yaml /openapi.json get /v1/sandboxes
openapi: 3.1.0
info:
  title: Coreload sandbox API
  version: '1'
  description: >-
    Create short-lived sandboxes, run commands in them and move files in and
    out. The API is in beta and not offered to outside callers yet: there are no
    API keys for outside callers. A call gets a ticket for a box from the edge
    with an API key, then calls the box at the ticket's URL with the ticket's
    `authorization` header. Answers are JSON, except a file download (its bytes)
    and a tunnel (a 101 upgrade); a JSON error is `{ok: false, error: {code,
    message}}`.
servers:
  - url: '{box}'
    description: The box URL from your ticket (`url`).
    variables:
      box:
        default: https://box.coreload.example
        description: The ticket's url.
security:
  - ticket: []
  - apiKey: []
tags:
  - name: Access
    description: 'Tickets: how a key reaches a box.'
  - name: Sandboxes
    description: Create, list, get and destroy sandboxes.
  - name: Runs
    description: Run commands in a sandbox and read their results and output.
  - name: Files
    description: Move files in and out of a sandbox.
  - name: Tunnels
    description: >-
      Byte tunnels over an HTTP upgrade: to a sandbox's SSH server or desktop,
      and the relay that answers a sandbox's outbound connections from your
      side.
paths:
  /v1/sandboxes:
    get:
      tags:
        - Sandboxes
      summary: List your sandboxes
      description: >-
        Your live sandboxes on this box, oldest first. Other callers' sandboxes
        are never listed.


        Needs the `view` scope.
      operationId: listSandboxes
      responses:
        '200':
          description: Your sandboxes.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SandboxList'
        '401':
          description: Notably `unauthorized`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Notably `scope_missing`, `ip_not_allowed`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '502':
          description: Notably `backend_error`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        default:
          description: >-
            An error: `{ok: false, error: {code, message}}`. This route may
            answer any code in this table (code, then status): `invalid_value`
            400, `unauthorized` 401, `scope_missing` 403, `ip_not_allowed` 403,
            `not_found` 404, `idempotency_conflict` 409, `sandbox_not_ready`
            409, `too_large` 413, `quota_exceeded` 429, `busy` 429,
            `wait_timeout` 504, `backend_error` 502.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    SandboxList:
      type: array
      items:
        $ref: '#/components/schemas/Sandbox'
    Error:
      type: object
      required:
        - ok
        - error
      properties:
        ok:
          const: false
        error:
          type: object
          required:
            - code
            - message
          properties:
            code:
              type: string
              description: The error code.
              enum:
                - invalid_value
                - unauthorized
                - scope_missing
                - ip_not_allowed
                - not_found
                - backend_error
                - idempotency_conflict
                - sandbox_not_ready
                - too_large
                - quota_exceeded
                - busy
                - wait_timeout
            message:
              type: string
              description: What went wrong, and what to do.
    Sandbox:
      type: object
      required:
        - id
        - image
        - status
        - createdAt
        - expiresAt
        - labels
      properties:
        id:
          type: string
          description: The sandbox id.
          pattern: ^sbx_[0-9a-f]{12}$
        image:
          type: string
          description: The image it was made from.
        backend:
          type: string
          description: The backend that runs it.
        status:
          type: string
          description: '`creating` until it can run tasks, then `ready`.'
          enum:
            - creating
            - ready
        createdAt:
          type: string
          description: When it was made.
          format: date-time
        expiresAt:
          type: string
          description: When it is deleted.
          format: date-time
        labels:
          type: object
          description: >-
            Up to 16 string pairs: keys `[a-z0-9._-]` of at most 63 characters,
            values of at most 256.
          propertyNames:
            pattern: ^[a-z0-9][a-z0-9._-]{0,62}$
          additionalProperties:
            type: string
            maxLength: 256
          maxProperties: 16
        owner:
          type: string
          description: The caller that made it.
        keyId:
          type: string
          description: >-
            The SHA-256 of the API key that made it (64 lowercase hex), when a
            key made it.
          pattern: ^[0-9a-f]{64}$
  securitySchemes:
    ticket:
      type: apiKey
      in: header
      name: Authorization
      description: >-
        The ticket's `authorization` value, sent as it is (its own scheme, not
        Bearer), until the ticket's `expiresAt`.
    apiKey:
      type: http
      scheme: bearer
      description: >-
        An API key: `Authorization: Bearer <key>`. The edge takes it for a
        ticket; a box takes a key issued for that box. Keys are not issued to
        outside callers yet.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.