List sandboxes

{
  "operationId": "getSandboxes",
  "description": "List all sandboxes associated with the authenticated account and their current statuses. Returns sandbox details including lifecycle state, timeout remaining, and creation timestamp. Authentication is handled via the x-api-key header or Authorization Bearer token.\n\nSet `metadata_only=true` when you only need the existing saved metadata. This skips live sandbox status lookups and returns an empty `sandboxes` array alongside `snapshot_id`, `github_repo` and `filetree`, preserving their existing nullable behavior. Stored metadata reads and the optional GitHub filetree lookup still run. The empty array in this mode does not establish whether any sandbox is running.\n\nOmitting `metadata_only` or sending literal `false` preserves normal live-status behavior. Authentication, account access checks and sandbox filters remain the same in either mode. Supplied values must be literal lowercase `true` or `false`; other values, including an empty value, return 400 through query validation.\n\nOmit `account_id` to read the authenticated account. An explicit UUID must pass the existing account-access policy: the caller itself, an organization the caller belongs to, a shared-organization account, or existing Recoup administrative access. Invalid UUIDs return 400; denied targets return 403 before snapshot or repository lookup. A target read never falls back to the caller's repository. Successful explicit-target reads echo `account_id`; omitted-target responses do not add that field. This delegates reads only, not upload, replacement or deletion rights.",
  "parameters": [
    {
      "name": "sandbox_id",
      "in": "query",
      "required": false,
      "description": "Filter by a specific sandbox ID. When provided, returns only the sandbox matching this ID. Must be a sandbox that your account or organization is an admin of.",
      "schema": {
        "type": "string",
        "example": "sbx_abc123def456"
      }
    },
    {
      "name": "account_id",
      "in": "query",
      "description": "Optional target account UUID authorized by the existing account-access policy. Omit for the authenticated account. Successful explicit-target reads echo this value as account_id; this does not grant file-write access.",
      "required": false,
      "schema": {
        "type": "string",
        "format": "uuid"
      },
      "example": "11111111-1111-4111-8111-111111111111"
    },
    {
      "name": "metadata_only",
      "in": "query",
      "required": false,
      "description": "Send literal lowercase true to skip live sandbox status lookups and return the existing metadata with an empty sandboxes array. Omitted or false retains live-status lookups. Database metadata reads and optional GitHub filetree retrieval still run; authentication, access checks and sandbox filters are unchanged. Other supplied values, including an empty value, return 400.",
      "schema": {
        "type": "boolean",
        "default": false
      }
    }
  ],
  "responses": {
    "200": {
      "description": "Sandboxes retrieved successfully. In metadata_only mode, sandboxes is empty while the existing saved metadata fields are retained. Explicit authorized account_id requests echo that account_id; omitted-target requests keep the existing response shape.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/SandboxesResponse"
          },
          "examples": {
            "ownMetadata": {
              "summary": "Authenticated account metadata (metadata_only=true)",
              "value": {
                "status": "success",
                "sandboxes": [],
                "snapshot_id": null,
                "github_repo": null,
                "filetree": null
              }
            },
            "targetMetadata": {
              "summary": "Authorized explicit account metadata (account_id and metadata_only=true)",
              "value": {
                "status": "success",
                "sandboxes": [],
                "snapshot_id": null,
                "github_repo": null,
                "filetree": null,
                "account_id": "11111111-1111-4111-8111-111111111111"
              }
            }
          }
        }
      }
    },
    "400": {
      "description": "Invalid query parameters, including an invalid account_id UUID or a supplied metadata_only value other than literal lowercase true or false.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/SandboxErrorResponse"
          }
        }
      }
    },
    "401": {
      "description": "Unauthorized - invalid or missing API key",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/SandboxErrorResponse"
          }
        }
      }
    },
    "403": {
      "description": "Access denied to the explicit account_id. No target snapshot/repository lookup or fallback to the caller's repository occurs.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/SandboxErrorResponse"
          }
        }
      }
    }
  }
}