HTTP API

TaskDaemon http api guide

HTTP API

The default address is http://localhost:8080. The daemon serves plaintext HTTP; configure authentication, TLS, and rate limits at your deployment boundary when required.

Queue a Task

POST /queue persists a task and returns HTTP 200 with its ID. Completion is asynchronous.

curl -fsS -X POST http://localhost:8080/queue \
  -H "Content-Type: application/json" \
  -d '{"type":"resize","data":{"image_url":"https://example.com/image.jpg","width":200,"height":200},"priority":75}'

{"task_id":"550e8400-e29b-41d4-a716-446655440000"}

type and data are required. data may be any JSON value supported by your handler. priority is an integer, default 50. Higher values are selected first when DAEMON_TASK_SELECTION=priority; the API does not enforce a 0–100 range. The task stores the daemon’s configured retry budget at enqueue time.

Get a Task

GET /api/tasks/{task_id} returns HTTP 200 or 404 if the task does not exist.

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "task_type": "resize",
  "task_data": {"image_url":"https://example.com/image.jpg","width":200,"height":200},
  "status": "completed",
  "created_at": "2026-10-05T10:30:00Z",
  "completed_at": "2026-10-05T10:30:05Z",
  "attempts": 0,
  "last_error": null,
  "result": {"processed": true}
}

Status	Meaning
pending	Awaiting a claim, possibly delayed by retry backoff
processing	Claimed by a worker, including tasks waiting in its batch or for a handler
completed	Successful result persisted
failed	Permanent error, exhausted retry budget, timeout, or handler transport/protocol failure

attempts starts at zero and increments when a retry is scheduled or the task is marked Failed, including a terminal failure. Successful completion does not increment it. Before execution, the handler request sets attempt = attempts + 1: an initial success therefore sends attempt: 1 but returns API attempts: 0; an initial terminal failure stores attempts: 1. Recovery can repeat an execution with the same request attempt, so neither field is a count of all handler executions.

List Recent Tasks

GET /api/tasks returns an array of up to 20 recent tasks with id, task_type, status, and created_at. This HTTP endpoint has no limit or status query filter.

[
  {"id":"550e8400-e29b-41d4-a716-446655440000","task_type":"resize","status":"completed","created_at":"2026-10-05T10:30:00Z"}
]

Delete a Task

DELETE /api/tasks/{task_id} returns HTTP 204 with an empty body when deleted, or 404 when absent. Deleting a Processing task does not cancel an external action already executing in its handler.

Redrive a Failed Task

POST /api/tasks/{task_id}/redrive returns HTTP 200 with an empty body when a Failed task becomes Pending. It returns 404 for a missing task or a task that is not Failed. Redrive clears the last error and makes the task visible; it preserves its stored attempt count and retry budget.

Health

GET /health reads the exact current Pending count from storage:

{"status":"healthy","queue_size":42,"workers":4,"timestamp":"2026-10-05T10:30:00Z"}

Pending excludes Processing claims and includes retries waiting for visibility. This is a daemon/queue check, not handler readiness. If storage cannot be read, the current HTTP endpoint returns an unhealthy JSON response with a zero fallback count and HTTP 200; health clients must inspect status.

Metrics

GET /metrics exposes Prometheus metrics, for example:

# HELP tasks_received_total Total tasks received
# TYPE tasks_received_total counter
tasks_received_total 1234

GET /api/metrics returns JSON:

{"tasks_received":1234,"tasks_processed_success":1200,"tasks_processed_failed":10,"queue_size":24,"daemon_healthy":true}

Counters describe this daemon process and reset on restart. Queue size is sampled once per second while workers run; it may lag recent mutations. /health performs a fresh count. Failed summary counts include terminal failures and timeouts across all task types; retry scheduling is excluded.

API Schema and Errors

Swagger UI is at /docs; its OpenAPI schema is at /api-docs/openapi.json.

Malformed input or UUIDs return 400; missing tasks return 404; storage/internal failures return 500. These routes generally return empty error bodies rather than a JSON { "error": ... } object.