Shuttle ↔ Starbase API Contract¶
All requests include Authorization: Bearer <token> and Content-Type: application/json.
§25.1 Pull Desired State¶
Load-bearing — the desired-state payload
This response body is the desired-state contract Shuttle obeys ("Starbase decides, Shuttle
applies"). The payload shape is load-bearing; the canonical model lives at
§32. Never reintroduce customer_id — identity
is project_id + environment + service_id, with workspace_id as the billing-boundary
label.
Response:
{
"version": "abc123",
"cluster_config": {
"lb_size_units": 3
},
"services": [
{
"workspace_id": "...",
"project_id": "...",
"service_id": "...",
"environment": "production",
"tier": "nova",
"image": "registry.digitalocean.com/starform/...",
"replicas": 1,
"env": {"KEY": "value"},
"ports": [{"container_port": 3000, "protocol": "TCP"}],
"hostname": "myapp.starform.app",
"deleted": false
}
]
}
§25.2 Post Snapshot Batch¶
{
"snapshots": [
{
"snapshot_id": "hash(project_id+service_id+pod_id+ts)",
"workspace_id": "...",
"project_id": "...",
"environment": "production",
"service_id": "...",
"pod_id": "...",
"tier": "nova",
"phase": "Running",
"snapshot_timestamp": "2026-04-08T12:34:56Z"
}
]
}
§25.3 Post Capacity Report¶
{
"cluster_id": "...",
"current_pod_count": 423,
"soft_limit": 1000,
"timestamp": "2026-04-08T12:34:56Z"
}