Skip to content

API Reference

Complete REST API reference for Spooled Cloud. All endpoints require authentication via Bearer token (JWT) or API key.

Base URL: https://api.spooled.cloud

Authentication

Include your API key or JWT token in the Authorization header: 

Authorization: Bearer sk_live_your_api_key

See Authentication for details on obtaining tokens.

Endpoints

Authentication

Method Endpoint Description
POST /api/v1/auth/login Exchange API key for JWT tokens
POST /api/v1/auth/refresh Refresh access token
GET /api/v1/auth/me Get current user/organization info
POST /api/v1/auth/email/start Start passwordless email login
POST /api/v1/auth/email/verify Verify email login code

Jobs

Method Endpoint Description
POST /api/v1/jobs Create/enqueue a new job
GET /api/v1/jobs List jobs with filtering
GET /api/v1/jobs/:id Get job details
POST /api/v1/jobs/claim Claim jobs for processing
POST /api/v1/jobs/:id/complete Mark job as completed
POST /api/v1/jobs/:id/fail Mark job as failed (triggers retry)
POST /api/v1/jobs/:id/retry Manually retry a job
DELETE /api/v1/jobs/:id Cancel/delete a job

Queues

Method Endpoint Description
POST /api/v1/queues Create a new queue
GET /api/v1/queues List all queues
GET /api/v1/queues/:name Get queue details and stats
PATCH /api/v1/queues/:name Update queue settings
DELETE /api/v1/queues/:name Delete a queue
POST /api/v1/queues/:name/pause Pause queue processing
POST /api/v1/queues/:name/resume Resume queue processing

Workers

Method Endpoint Description
POST /api/v1/workers/register Register a new worker
GET /api/v1/workers List active workers
POST /api/v1/workers/:id/heartbeat Send worker heartbeat
DELETE /api/v1/workers/:id Deregister a worker

Webhooks

Method Endpoint Description
POST /api/v1/webhooks Create webhook subscription
GET /api/v1/webhooks List webhook subscriptions
GET /api/v1/webhooks/:id Get webhook details
PATCH /api/v1/webhooks/:id Update webhook
DELETE /api/v1/webhooks/:id Delete webhook
POST /api/v1/webhooks/:org_id/github Receive GitHub webhooks
POST /api/v1/webhooks/:org_id/stripe Receive Stripe webhooks

Billing

Method Endpoint Description
GET /api/v1/billing/status Get billing/subscription status
POST /api/v1/billing/portal Create Stripe billing portal session

Real-time

Method Endpoint Description
GET /api/v1/events/sse Server-Sent Events stream
WS /api/v1/events/ws WebSocket connection

gRPC API

Spooled also provides a gRPC API on port 50051 for high-performance worker communication using HTTP/2 + Protobuf. The gRPC API supports streaming for real-time job delivery.

gRPC Services

Service RPC Description
QueueService Enqueue Create a new job
QueueService Dequeue Claim jobs for processing (batch)
QueueService Complete Mark job as completed
QueueService Fail Mark job as failed
QueueService StreamJobs Server streaming for real-time job delivery
QueueService ProcessJobs Bidirectional streaming for workers
WorkerService Register Register a worker
WorkerService Heartbeat Send worker heartbeat

gRPC Authentication

Include your API key in gRPC metadata:

x-api-key: sk_live_your_api_key

When to Use gRPC vs REST

Use Case Recommended
Web/mobile appsREST API
Dashboard/adminREST API
High-throughput workersgRPC
Streaming job deliverygRPC

Response Format

All responses are JSON. Successful responses include the data directly:

{
  "id": "job_abc123",
  "queue": "emails",
  "status": "pending",
  "payload": { "to": "user@example.com" },
  "created_at": "2024-01-15T10:30:00Z"
}

Error responses include an error object:

{
  "error": "validation_error",
  "message": "Queue name is required",
  "status": 422
}

Rate Limiting

API requests are rate-limited based on your plan. Rate limit headers are included in responses:

  • X-RateLimit-Limit — Requests per second allowed
  • X-RateLimit-Remaining — Remaining requests in current window
  • X-RateLimit-Reset — Unix timestamp when limit resets

See Rate Limits for plan-specific limits.

Pagination

List endpoints support cursor-based pagination:

  • limit — Number of items per page (default: 20, max: 100)
  • cursor — Cursor for next page (from previous response)
GET /api/v1/jobs?limit=50&cursor=eyJpZCI6Impv...

Need more details?