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

# Setup Sandbox

> Triggers the setup-sandbox background task to create a personal sandbox, provision a GitHub repo, take a snapshot, and shut down. By default, sets up the sandbox for the key owner's account. Pass account_id to target a specific account the API key has access to. Authentication is handled via the x-api-key header or Authorization Bearer token.



## OpenAPI

````yaml api-reference/openapi/content.json POST /api/sandboxes/setup
openapi: 3.1.0
info:
  title: Recoup API - Content
  description: >-
    API documentation for the Recoup platform - an AI agent platform for the
    music industry
  license:
    name: MIT
  version: 1.0.0
servers:
  - url: https://api.recoupable.dev
security: []
paths:
  /api/sandboxes/setup:
    post:
      description: >-
        Triggers the setup-sandbox background task to create a personal sandbox,
        provision a GitHub repo, take a snapshot, and shut down. By default,
        sets up the sandbox for the key owner's account. Pass account_id to
        target a specific account the API key has access to. Authentication is
        handled via the x-api-key header or Authorization Bearer token.
      requestBody:
        description: Optional account targeting parameters
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SetupSandboxRequest'
      responses:
        '200':
          description: Setup task triggered successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SetupSandboxResponse'
        '400':
          description: Bad request - invalid account_id format
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SandboxErrorResponse'
        '401':
          description: Unauthorized - invalid or missing API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SandboxErrorResponse'
components:
  schemas:
    SetupSandboxRequest:
      type: object
      properties:
        account_id:
          type: string
          format: uuid
          description: >-
            UUID of the account to set up the sandbox for. Only applicable when
            the authenticated account has access to multiple accounts via
            organization membership. If not provided, sets up the sandbox for
            the API key's own account.
    SetupSandboxResponse:
      type: object
      required:
        - status
        - runId
      properties:
        status:
          type: string
          enum:
            - success
          description: Status of the setup operation
        runId:
          type: string
          description: >-
            The Trigger.dev run ID for the setup-sandbox background task. Use
            this with [GET /api/tasks/runs](/api-reference/tasks/runs) to check
            the status and retrieve results.
          example: run_abc123def456
    SandboxErrorResponse:
      type: object
      required:
        - error
      properties:
        error:
          type: string
          description: Error message describing what went wrong
          example: Failed to create sandbox

````