Jobs
Push, inspect, and monitor background jobs in the Savannah Cloud queue system.
Base URL
http://localhost:8080All job endpoints require authentication. Use either a JWT or an API key.
Push a job
POST /jobs
X-API-Key: sc_your_key_here
Content-Type: application/jsonRequest body
{
"ID": "unique-job-id",
"Type": "send_email",
"Payload": {
"to": "user@example.com",
"subject": "Hello"
},
"MaxRetries": 3
}| Field | Type | Required | Description |
|---|---|---|---|
ID | string | Yes | Unique identifier for the job |
Type | string | Yes | Job type; determines the worker handler |
Payload | object | Yes | Arbitrary JSON passed to the worker |
MaxRetries | integer | No | Maximum retry count before failing |
Response 202 Accepted
{
"id": "unique-job-id",
"status": "pending"
}See Job Types for the built-in job handlers and payload schemas.
List jobs
GET /jobs
Authorization: Bearer <token>Optional filter:
GET /jobs?status=pendingQuery parameters
| Param | Values | Description |
|---|---|---|
status | pending, processing, done, failed | Filter by current 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 logs
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 | Accepted and waiting for a worker |
processing | A worker has picked it up |
done | Completed successfully |
failed | Retries were exhausted |
Quick examples
# Push a job
curl -X POST http://localhost:8080/jobs \
-H "X-API-Key: sc_your_key_here" \
-H "Content-Type: application/json" \
-d '{"ID":"job-001","Type":"send_email","Payload":{"to":"user@example.com"}}'
# List jobs
curl http://localhost:8080/jobs \
-H "Authorization: Bearer YOUR_JWT"
# Get a single job
curl http://localhost:8080/jobs/job-001 \
-H "Authorization: Bearer YOUR_JWT"
# Get logs
curl http://localhost:8080/jobs/job-001/logs \
-H "Authorization: Bearer YOUR_JWT"