Cloud API Reference

The TestBase Cloud API is a REST interface served by @testbase/cloud-api. All authenticated requests must include Authorization: Bearer tb_{env}_{32hex}. Responses are JSON unless noted.

Download: openapi.yaml

The sections below summarise the most frequently used endpoints. The canonical contract lives in the OpenAPI document above.

Containers

Create

POST /api/v1/containers
Authorization: Bearer tb_prod_xxx
Content-Type: application/json
 
{
  "agentType": "worker",
  "workspace": "/workspace",
  "region": "us-central1",
  "model": "gpt-4o-mini",
  "reasoningEffort": "low",
  "persistContainer": false,
  "timeout": 300000
}

Returns container metadata (ID, status, cloudRunServiceUrl).

Retrieve & list

GET /api/v1/containers/:id
GET /api/v1/containers

Includes MCP configuration, last health check, and workspace info.

Update

PATCH /api/v1/containers/:id
Content-Type: application/json
 
{ "model": "gpt-5-mini", "reasoningEffort": "medium" }

Use to upgrade models or adjust reasoning effort without recreating the container.

Delete

DELETE /api/v1/containers/:id

Tears down the runtime but leaves GCS artefacts intact.

MCP servers

Add

POST /api/v1/containers/:id/mcp-servers
Content-Type: application/json
 
{
  "server": {
    "type": "hosted",
    "name": "github",
    "url": "https://github-mcp.example.com/mcp",
    "bearerToken": "ghp_..."
  }
}

For local servers use type: "local" plus package, command, args, and optional env.

Remove / list

DELETE /api/v1/containers/:id/mcp-servers/:name
GET /api/v1/containers/:id/mcp-servers

Install npm packages

POST /api/v1/containers/:id/packages
Content-Type: application/json
 
{
  "package": "@modelcontextprotocol/server-slack",
  "env": { "SLACK_TOKEN": "xoxb-..." }
}

Installs packages inside the container so local MCP servers can launch.

Files

Endpoints mirror the Files API guide:

• GET /api/v1/containers/:id/files?path=/workspace → directory listing
• GET /api/v1/containers/:id/files/download?path=… → binary download
• PUT /api/v1/containers/:id/files → upload/overwrite
• DELETE /api/v1/containers/:id/files?path=… → delete file

All operations are backed by Google Cloud Storage and return 404 if the object does not exist.

Task execution

Each container exposes a private /execute endpoint (URL returned via cloudRunServiceUrl). The Agents SDK calls this automatically; if you invoke it manually, send JSON payloads like:

POST https://<container-host>/execute
Content-Type: application/json
 
{ "task": "Create a Flask API with health checks" }

/status and /logs endpoints on the container host complement the Cloud API’s aggregated health/log routes.

Health & diagnostics

• GET /api/v1/containers/:id/health → { status, healthy }
• GET /api/v1/containers/:id/logs?lines=100 → plain-text logs
• GET /health → Cloud API readiness probe

Use health endpoints to drive automated retries or alerting when containers degrade.

Error responses

Errors follow this shape:

{
  "error": {
    "code": "container_not_found",
    "message": "Container abc123 was not found",
    "details": { "containerId": "abc123" }
  }
}

Common codes include unauthorized, forbidden, validation_error, container_timeout, and mcp_failure. The Cloud SDK raises typed errors that wrap the same payloads.

Consult testbase-cloud/packages/cloud-api for full schema definitions and middleware behaviour.