Jobs
Push, list, and inspect background jobs via the REST API.
Base URL
http://localhost:8080All job endpoints require authentication. Use either a JWT or an API key.
Push a Job
Enqueues a new background job.
POST /jobs
X-API-Key: sc_your_key_here
Content-Type: application/jsonRequest body
{
"type": "send_email",
"payload": {
"to": "user@example.com",
"subject": "Hello",
"body": "Hello from Savannah"
},
"max_retries": 3
}| Field | Type | Required | Description |
|---|---|---|---|
type | string | Yes | Job type; determines which handler runs |
payload | object | Yes | Arbitrary JSON passed to the worker handler |
max_retries | integer | No | Max attempts before marking failed (default: 0) |
Response 202 Accepted
{
"id": "unique-job-id",
"status": "pending"
}See Job Types for the list of built-in handlers and their expected payload shapes.
List Jobs
Returns all jobs in the organization, optionally filtered by status.
GET /jobs
GET /jobs?status=pending
Authorization: Bearer <token>Query parameters
| Param | Values | Description |
|---|---|---|
status | pending, processing, done, failed | Filter by job status |
Response 200
[
{
"id": "job-001",
"type": "send_email",
"status": "done",
"retries": 0,
"max_retries": 3,
"created_at": "2026-05-24T10:00:00Z",
"updated_at": "2026-05-24T10:00:05Z"
}
]Get a Single Job
GET /jobs/{id}
Authorization: Bearer <token>Response 200
{
"id": "job-001",
"type": "send_email",
"status": "done",
"payload": { "to": "user@example.com", "subject": "Hello" },
"retries": 0,
"max_retries": 3,
"created_at": "2026-05-24T10:00:00Z",
"updated_at": "2026-05-24T10:00:05Z"
}Get Job Execution Logs
Returns per-attempt log lines for a job.
GET /jobs/{id}/logs
Authorization: Bearer <token>Response 200
[
{
"attempt": 1,
"message": "Processing send_email for user@example.com",
"level": "info",
"timestamp": "2026-05-24T10:00:01Z"
},
{
"attempt": 1,
"message": "Email sent successfully",
"level": "info",
"timestamp": "2026-05-24T10:00:05Z"
}
]Job Status Reference
| Status | Description |
|---|---|
pending | Enqueued, waiting for a worker |
processing | A worker has picked it up |
completed | Completed successfully |
failed | All retry attempts exhausted |
Quick Reference
# Push a job
curl -X POST http://localhost:8080/jobs \
-H "X-API-Key: sc_your_key_here" \
-H "Content-Type: application/json" \
-d '{"type":"send_email","payload":{"to":"user@example.com","subject":"Hi","body":"Hello"}}'
# List all jobs
curl http://localhost:8080/jobs \
-H "Authorization: Bearer YOUR_JWT"
# List only failed jobs
curl "http://localhost:8080/jobs?status=failed" \
-H "Authorization: Bearer YOUR_JWT"
# Get a single job
curl http://localhost:8080/jobs/job-001 \
-H "Authorization: Bearer YOUR_JWT"
# Get logs for a job
curl http://localhost:8080/jobs/job-001/logs \
-H "Authorization: Bearer YOUR_JWT"