API REFERENCE

Setup Sandbox

On this page

POST/api/sandboxes/setup

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.

Authentication

See the authentication guide for API key and account access requirements.

Request

cURL

curl --request POST \
  --url 'https://api.recoupable.dev/api/sandboxes/setup' \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "account_id": "YOUR_ID"
}'

Request body

Optional account targeting parameters

application/json

account_idstring

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.

format: uuid

Responses

200Setup task triggered successfully

application/json

statusstring · enumrequired

Status of the setup operation

Values: "success"

runIdstringrequired

The Trigger.dev run ID for the setup-sandbox background task. Use this with GET /api/tasks/runs to check the status and retrieve results.

400Bad request - invalid account_id format

application/json

errorstringrequired

Error message describing what went wrong

401Unauthorized - invalid or missing API key

application/json

errorstringrequired

Error message describing what went wrong

Full specification

Download the OpenAPI file for complete schemas, constraints, and examples.

Download content.json

View operation source

json

{
  "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"
          }
        }
      }
    }
  }
}