Cassette
Sign in

Cassette API

v1 (latest)

Simple, stable JSON API for managing cassettes programmatically.

Overview

  • Base URL (prod): https://cassette.sh
  • Base URL (dev): http://localhost:3000
  • Versioning: prefixed paths (e.g. /api/v1/…).
  • Format: JSON only. Set Content-Type: application/json for POST bodies.

Authentication

Create API keys under "API Keys" (org‑scoped). Send as Bearer token:

Authorization: Bearer <API_KEY>

Alternatively, X-Api-Key: <API_KEY>.

Generate an API key (requires org admin)

Endpoints

GET /api/v1/cassettes
List all cassettes in your org
Request
curl -s -H "Authorization: Bearer $API_KEY" \
  $BASE_URL/api/v1/cassettes
Response 200
[{
  "id": "8b6a…",
  "name": "autumn-sky-1",
  "status": "running",
  "plan_id": "small",
  "region_id": "us-east-1",
  "image_id": "ubuntu",
  "vmid": 101,
  "ip_address": "203.0.113.10",
  "created_at": "2025-09-08T12:34:56Z",
  "updated_at": "2025-09-08T12:35:10Z"
}]
GET /api/v1/cassettes/:id
Fetch one cassette
Request
curl -s -H "Authorization: Bearer $API_KEY" \
  $BASE_URL/api/v1/cassettes/<INSTANCE_ID>
Response 200
{
  "id": "8b6a…",
  "name": "autumn-sky-1",
  "status": "running",
  "plan_id": "small",
  "region_id": "us-east-1",
  "image_id": "ubuntu",
  "vmid": 101,
  "ip_address": "203.0.113.10",
  "created_at": "2025-09-08T12:34:56Z",
  "updated_at": "2025-09-08T12:35:10Z"
}
Response 404
{"error":"not_found"}
POST /api/v1/cassettes
Provision a new cassette
Request
curl -s -X POST -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"plan_id":"small","region_id":"us-east-1","image_id":"ubuntu"}' \
  $BASE_URL/api/v1/cassettes
Body fields: plan_id, region_id, image_id (all required)
Response 201
{
  "id": "9c33…",
  "name": "breezy-river-2",
  "status": "provisioning",
  "plan_id": "small",
  "region_id": "us-east-1",
  "image_id": "ubuntu",
  "vmid": null,
  "ip_address": null,
  "created_at": "2025-09-08T13:45:10Z",
  "updated_at": "2025-09-08T13:45:10Z"
}
Response 402
{"error":"no_active_subscription"}
Response 422
{"error":"insufficient_capacity"}
POST /api/v1/cassettes/:id/resize
Change plan/size
Request
curl -s -X POST -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"plan_id":"medium"}' \
  $BASE_URL/api/v1/cassettes/<INSTANCE_ID>/resize
Response 202
{
  "id": "8b6a…",
  "name": "autumn-sky-1",
  "status": "provisioning",
  "plan_id": "medium",
  "region_id": "us-east-1",
  "image_id": "ubuntu",
  "vmid": 101,
  "ip_address": "203.0.113.10",
  "created_at": "2025-09-08T12:34:56Z",
  "updated_at": "2025-09-08T13:50:00Z"
}
Response 422
{"error":"insufficient_capacity"}
DELETE /api/v1/cassettes/:id
Delete a cassette
Request
curl -s -X DELETE -H "Authorization: Bearer $API_KEY" \
  $BASE_URL/api/v1/cassettes/<INSTANCE_ID>
Response 204
(no content)
GET /status/api
Get platform status (no auth required)
Request
curl -s $BASE_URL/status/api
Response 200
{
  "status": "operational",
  "components": [
    {
      "name": "API",
      "status": "operational",
      "last_checked": "2024-01-15T12:30:45Z",
      "response_time_ms": 45
    },
    {
      "name": "Web Application",
      "status": "operational",
      "last_checked": "2024-01-15T12:30:45Z",
      "response_time_ms": 23
    }
  ],
  "incidents": []
}
Status Values
  • operational - Everything working normally
  • degraded - Minor issues, reduced performance
  • partial - Partial outage affecting some users
  • major - Major outage affecting most users

Errors

  • 401 Unauthorized: missing/invalid API key
  • 402 Payment Required: no active organization subscription
  • 404 Not Found: resource not found within your organization
  • 422 Unprocessable Entity: validation or capacity error (see error field)