Spooling
Cloud
Back to spooling.ai

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 /healthz

Returns {"status": "ok"} with no auth. Used by the load balancer.

Sessions

Ingest

POST /v1/sessions/batch

Push (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=0

Workspace-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=toebox

Bulk-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/stats

Workspace 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

StatusMeaning
400Validation error (missing field, oversize payload, invalid filter)
401Missing or invalid bearer token
403Token revoked or no workspace assigned
404Resource not in caller's workspace, or doesn't exist
429Rate limit exceeded
500Server error (please report)

Error responses are JSON: {"detail": "human-readable message"}.

On this page