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

# Update many sandboxes

> Changes up to 500 sandboxes in one request. Give each item the `id` of a sandbox and the fields of an update, such as `state: stopped` to stop it. The API changes the items one after the other. It returns a result for each item, in the sequence of the items: the ID, and an error message if the change failed. Needs the `sandboxes:write` scope.



## OpenAPI

````yaml /api-reference/openapi.json post /v1/sandboxes/update-many
openapi: 3.1.0
info:
  title: VMS API
  version: 1.0.0
  description: >-
    The public API of a VMS workspace. Each request needs an API key of the
    workspace in the Authorization header.
servers:
  - url: https://vms.dev/api
    description: The VMS API
security:
  - apiKey: []
paths:
  /v1/sandboxes/update-many:
    post:
      tags:
        - Sandboxes
      summary: Update many sandboxes
      description: >-
        Changes up to 500 sandboxes in one request. Give each item the `id` of a
        sandbox and the fields of an update, such as `state: stopped` to stop
        it. The API changes the items one after the other. It returns a result
        for each item, in the sequence of the items: the ID, and an error
        message if the change failed. Needs the `sandboxes:write` scope.
      operationId: updateManySandboxes
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateManySandboxesBody'
      responses:
        '200':
          description: A result for each item.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SandboxBulkResult'
        '400':
          description: The request is not valid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: The API key is missing, not correct, revoked, or expired.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: The API key does not have the scope of the endpoint.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: The API key sent more than 1,200 requests in one minute.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    UpdateManySandboxesBody:
      type: object
      properties:
        items:
          minItems: 1
          maxItems: 500
          type: array
          items:
            $ref: '#/components/schemas/UpdateSandboxItem'
      required:
        - items
    SandboxBulkResult:
      type: object
      properties:
        succeeded:
          type: integer
          minimum: -9007199254740991
          maximum: 9007199254740991
        failed:
          type: integer
          minimum: -9007199254740991
          maximum: 9007199254740991
        message:
          type:
            - string
            - 'null'
        data:
          type: array
          items:
            type: object
            properties:
              index:
                type: integer
                minimum: -9007199254740991
                maximum: 9007199254740991
              id:
                type:
                  - string
                  - 'null'
              error:
                type:
                  - string
                  - 'null'
            required:
              - index
              - id
              - error
            additionalProperties: false
      required:
        - succeeded
        - failed
        - message
        - data
      additionalProperties: false
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              example: no_capacity
            message:
              type: string
            requestId:
              type:
                - string
                - 'null'
            retryAfterSeconds:
              type: integer
              minimum: 0
              maximum: 9007199254740991
            sandboxId:
              description: The sandbox that the error is about.
              type: string
          required:
            - code
            - message
            - requestId
          additionalProperties: false
      required:
        - error
      additionalProperties: false
    UpdateSandboxItem:
      type: object
      properties:
        name:
          description: The new name. Send null to remove the name.
          anyOf:
            - type: string
              pattern: ^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$
              description: >-
                A name that is unique in the workspace: 1 to 63 lowercase
                letters, digits, and hyphens. It cannot start or end with a
                hyphen.
              example: agent-42
            - type: 'null'
        labels:
          description: The new labels. They replace all labels of the sandbox.
          type: object
          propertyNames:
            type: string
            pattern: ^[A-Za-z0-9](?:[A-Za-z0-9._/-]{0,61}[A-Za-z0-9])?$
          additionalProperties:
            type: string
            maxLength: 255
          example:
            project: web
            agent: reviewer
        stopAfterSeconds:
          description: >-
            The new seconds that the sandbox runs after each start, counted from
            the current start. If this time is already past, the sandbox stops
            now. Send null to turn off auto-stop. Do not send it with stopAt.
          anyOf:
            - type: integer
              minimum: 60
              maximum: 2592000
            - type: 'null'
          example: 3600
        stopAt:
          description: >-
            The new time when the sandbox stops on its own. It must be in the
            future, and the sandbox must be creating, starting, or running. Send
            null to turn off auto-stop. Do not send it with stopAfterSeconds.
          anyOf:
            - type: string
              format: date-time
              pattern: >-
                ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$
            - type: 'null'
          example: '2026-11-16T12:00:00Z'
        state:
          $ref: '#/components/schemas/SandboxTargetState'
          description: >-
            Send stopped to stop the sandbox, or running to resume it. The
            response is 202 with the operation of the stop or the resume.
        size:
          $ref: '#/components/schemas/SandboxSize'
          description: >-
            The size after the resume. Send it only with state running, to a
            stopped sandbox.
        pinImage:
          description: >-
            Send true to keep the current base image at each resume. Send false
            to move the sandbox to the latest base image at the next resume
            after the 10-minute hold.
          type: boolean
        id:
          type: string
          minLength: 1
          example: sbx_06d8k3m7q2v9x4b1n5c0e8f2ja
      required:
        - id
    SandboxTargetState:
      type: string
      enum:
        - stopped
        - running
      description: stopped stops a running sandbox. running resumes a stopped sandbox.
    SandboxSize:
      type: string
      enum:
        - small
        - medium
        - large
        - xlarge
      description: The vCPU, RAM, and disk of a sandbox.
  securitySchemes:
    apiKey:
      type: http
      scheme: bearer
      description: An API key that starts with vms_. Make one in Settings > API keys.

````

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