Savannah Cloud

Jobs

Push, inspect, and monitor background jobs in the Savannah Cloud queue system.

Base URL

http://localhost:8080

All 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/json

Request body

{
  "ID": "unique-job-id",
  "Type": "send_email",
  "Payload": {
    "to": "user@example.com",
    "subject": "Hello"
  },
  "MaxRetries": 3
}
FieldTypeRequiredDescription
IDstringYesUnique identifier for the job
TypestringYesJob type; determines the worker handler
PayloadobjectYesArbitrary JSON passed to the worker
MaxRetriesintegerNoMaximum 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=pending

Query parameters

ParamValuesDescription
statuspending, processing, done, failedFilter 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

StatusDescription
pendingAccepted and waiting for a worker
processingA worker has picked it up
doneCompleted successfully
failedRetries 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"

On this page