Modal Sandboxes API

openapi: 3.1.0
info:
  title: Modal Dicts and Queues Apps Sandboxes API
  description: 'Modal Dicts and Queues — distributed in-memory primitives for

    cross-container state. Dicts are key-value stores; Queues are FIFO

    message queues used to coordinate work across Modal functions and

    sandboxes.

    '
  version: 0.1.0
  contact:
    name: Modal Labs
    url: https://modal.com
servers:
- url: https://api.modal.com/v1
security:
- ModalToken: []
tags:
- name: Sandboxes
  description: Sandbox lifecycle and management.
paths:
  /sandboxes:
    get:
      tags:
      - Sandboxes
      summary: List Sandboxes
      description: List all sandboxes in the current environment.
      operationId: listSandboxes
      parameters:
      - name: app_id
        in: query
        schema:
          type: string
      - name: tag
        in: query
        schema:
          type: string
      responses:
        '200':
          description: A page of sandboxes.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Sandbox'
    post:
      tags:
      - Sandboxes
      summary: Create Sandbox
      description: 'Create a new Sandbox with the given image, resources, and

        optional entrypoint command. Sandboxes start in `Created` state

        and transition through `Scheduled`, `Started`, `Ready`, and

        terminal states.

        '
      operationId: createSandbox
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SandboxCreate'
      responses:
        '201':
          description: Sandbox created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Sandbox'
  /sandboxes/{sandbox_id}:
    get:
      tags:
      - Sandboxes
      summary: Get Sandbox
      description: Retrieve a single Sandbox by ID.
      operationId: getSandbox
      parameters:
      - name: sandbox_id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: The Sandbox.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Sandbox'
    delete:
      tags:
      - Sandboxes
      summary: Terminate Sandbox
      description: Terminate a Sandbox and free its resources.
      operationId: terminateSandbox
      parameters:
      - name: sandbox_id
        in: path
        required: true
        schema:
          type: string
      responses:
        '204':
          description: Sandbox terminated.
  /sandboxes/{sandbox_id}/snapshot:
    post:
      tags:
      - Sandboxes
      summary: Snapshot Sandbox Filesystem
      description: Capture the Sandbox filesystem state as a reusable image.
      operationId: snapshotSandbox
      parameters:
      - name: sandbox_id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Snapshot image created.
          content:
            application/json:
              schema:
                type: object
                properties:
                  image_id:
                    type: string
  /sandboxes/{sandbox_id}/tunnels:
    get:
      tags:
      - Sandboxes
      summary: List Sandbox Tunnels
      description: Retrieve tunnel metadata for the Sandbox keyed by container port.
      operationId: listTunnels
      parameters:
      - name: sandbox_id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Tunnels for the Sandbox.
          content:
            application/json:
              schema:
                type: object
                additionalProperties:
                  $ref: '#/components/schemas/Tunnel'
components:
  schemas:
    Sandbox:
      type: object
      properties:
        sandbox_id:
          type: string
        app_id:
          type: string
        state:
          type: string
          enum:
          - created
          - scheduled
          - started
          - ready
          - finished
          - terminated
        image:
          type: string
        gpu:
          type: string
        cpu:
          type: number
        memory:
          type: integer
        timeout:
          type: integer
        idle_timeout:
          type: integer
        tags:
          type: object
          additionalProperties:
            type: string
        created_at:
          type: string
          format: date-time
    SandboxCreate:
      type: object
      properties:
        app_id:
          type: string
        image:
          type: string
        entrypoint:
          type: array
          items:
            type: string
        cpu:
          type: number
        memory:
          type: integer
        gpu:
          type: string
        timeout:
          type: integer
        idle_timeout:
          type: integer
        encrypted_ports:
          type: array
          items:
            type: integer
        unencrypted_ports:
          type: array
          items:
            type: integer
        tags:
          type: object
          additionalProperties:
            type: string
    Tunnel:
      type: object
      properties:
        host:
          type: string
        port:
          type: integer
        url:
          type: string
          format: uri
  securitySchemes:
    ModalToken:
      type: http
      scheme: bearer