REST API reference
Spooling Cloud's HTTP endpoints, scoped to the workspace your API key authenticates to.
Base URL: https://api.spooling.ai
All endpoints require Authorization: Bearer sk_<token>. Tenancy is enforced server-side: keys can only read or write the workspace they were minted in. See Workspaces for the auth model.
Health
GET /healthzReturns {"status": "ok"} with no auth. Used by the load balancer.
Sessions
Ingest
POST /v1/sessions/batchPush (or copy) sessions from a local Spool DB into the cloud workspace.
Body:
{
"sessions": [
{
"id": "uuid-or-string",
"provider_id": "claude-code",
"project": "toebox",
"title": "fix the auth middleware",
"cwd": "/Users/me/toebox",
"started_at": "2026-04-27T14:00:00Z",
"ended_at": "2026-04-27T14:42:18Z",
"message_count": 87,
"tool_call_count": 14,
"input_tokens": 18400,
"output_tokens": 4200,
"estimated_cost_usd": 0.42,
"source_digest": "sha256:...",
"messages": [
{ "role": "user", "content": "...", "sequence": 0, "timestamp": "..." }
]
}
],
"copy": false
}copy: true triggers deterministic ID rewriting on insert. See --copy semantics.
Response:
{
"accepted": 18,
"rejected": 2,
"user_id": "uuid"
}rejected counts sessions whose IDs are already owned by a different workspace. Use copy: true to share them, or DELETE /v1/sessions on the source workspace first.
Limits:
- 100 sessions per batch
- 5,000 messages per session
- 256 KB per message content
- 60 requests per minute, keyed on the API token
List
GET /v1/sessions?limit=50&offset=0Workspace-scoped session listing, newest first. limit capped at 200, offset at 100,000.
Detail
GET /v1/sessions/{session_id}Returns the session row plus all messages, ordered by sequence. Returns 404 if the session isn't in the caller's workspace (does not leak existence cross-tenant).
Delete
DELETE /v1/sessions?cwd_substr=toebox
DELETE /v1/sessions?project=toebox
DELETE /v1/sessions?dry_run=true&cwd_substr=toeboxBulk-delete sessions in the caller's workspace. At least one of project or cwd_substr is required (refuses to delete a whole workspace by accident; that's a separate flow).
Response:
{
"matched": 31,
"deleted": 31,
"dry_run": false,
"sessions": [
{ "id": "...", "project": "toebox", "title": "..." }
]
}ON DELETE CASCADE on cloud_messages.session_id handles the message rows.
Limits: 30 requests per minute.
Stats
GET /v1/statsWorkspace rollup:
{
"sessions": 108,
"messages": 32593,
"tokens": 2548219,
"cost": 51.26,
"providers": 5
}Authentication
Every authenticated request must include:
Authorization: Bearer sk_<token>API keys are stored as SHA-256 hashes server-side. The cloud never has access to the raw token after creation. To rotate a key: revoke it in Settings in the app and mint a fresh one.
Errors
| Status | Meaning |
|---|---|
400 | Validation error (missing field, oversize payload, invalid filter) |
401 | Missing or invalid bearer token |
403 | Token revoked or no workspace assigned |
404 | Resource not in caller's workspace, or doesn't exist |
429 | Rate limit exceeded |
500 | Server error (please report) |
Error responses are JSON: {"detail": "human-readable message"}.