HTTP API

REST API for task management

HTTP API

TaskDaemon exposes a REST API for task management.

Base URL

http://localhost:8080

Endpoints

Queue Task

Queue a new task for processing.

type · string · required

Handler name (must match a handler in handlers.toml)

data · object · required

Task data passed to the handler

priority · integer · default: "50"

Task priority (0-100). Higher = processed first when using priority selection.

Request

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

Get Task

Retrieve task details and status.

GET /api/tasks/{task_id}

Request

curl http://localhost:8080/api/tasks/550e8400-e29b-41d4-a716-446655440000

Status values:

Status	Description
pending	Queued, waiting for worker
processing	Currently being processed
completed	Successfully completed
failed	Failed after all retries

List Tasks

List recent tasks.

GET /api/tasks

Request

curl http://localhost:8080/api/tasks

Delete Task

Delete a task from the queue.

DELETE /api/tasks/{task_id}

Returns 204 No Content on success, 404 Not Found if task doesn’t exist.

Redrive Task

Retry a failed task.

POST /api/tasks/{task_id}/redrive

Returns 200 OK on success, 404 Not Found if task doesn’t exist or isn’t failed.

Health Check

Check service health.

Request

curl http://localhost:8080/health

Metrics

Prometheus metrics endpoint.

GET /metrics

Response

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

# HELP queue_size Current queue size
# TYPE queue_size gauge
queue_size 42

# HELP container_pool_active Active containers per handler
# TYPE container_pool_active gauge
container_pool_active{handler="resize"} 8

# HELP container_pool_idle Idle containers per handler
# TYPE container_pool_idle gauge
container_pool_idle{handler="resize"} 2

See Prometheus Monitoring for all available metrics.

API Metrics

JSON metrics summary.

Request

curl http://localhost:8080/api/metrics

Swagger UI

Interactive API documentation.

GET /docs

Error Responses

{
  "error": "Task not found"
}

Status Code	Description
200	Success
204	No Content (delete success)
400	Bad request
404	Not found
500	Internal server error

Priority Tasks

When using DAEMON_TASK_SELECTION=priority, tasks are processed in priority order:

# High priority (processed first)
curl -X POST http://localhost:8080/queue \
  -d '{"type": "urgent", "data": {...}, "priority": 100}'

# Normal priority (default)
curl -X POST http://localhost:8080/queue \
  -d '{"type": "normal", "data": {...}}'

# Low priority (processed last)
curl -X POST http://localhost:8080/queue \
  -d '{"type": "background", "data": {...}, "priority": 0}'

Priority range is 0 (lowest) to 100 (highest). Default is 50 if not specified.