> ## Documentation Index
> Fetch the complete documentation index at: https://taskdaemon.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

<ParamField body="type" type="string" required>
  Handler name (must match a handler in `handlers.toml`)
</ParamField>

<ParamField body="data" type="object" required>
  Task data passed to the handler
</ParamField>

<ParamField body="priority" type="integer" default="50">
  Task priority (0-100). Higher = processed first when using priority selection.
</ParamField>

<CodeGroup>
  ```bash Request theme={null}
  curl -X POST http://localhost:8080/queue \
    -H "Content-Type: application/json" \
    -d '{"type": "resize", "data": {"url": "https://example.com/image.jpg"}, "priority": 75}'
  ```

  ```json Response theme={null}
  {
    "task_id": "550e8400-e29b-41d4-a716-446655440000"
  }
  ```
</CodeGroup>

### Get Task

Retrieve task details and status.

```http theme={null}
GET /api/tasks/{task_id}
```

<CodeGroup>
  ```bash Request theme={null}
  curl http://localhost:8080/api/tasks/550e8400-e29b-41d4-a716-446655440000
  ```

  ```json Response theme={null}
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "task_type": "resize",
    "status": "completed",
    "task_data": {"url": "https://example.com/image.jpg"},
    "result": {"processed": true},
    "created_at": "2024-01-15T10:30:00Z",
    "completed_at": "2024-01-15T10:30:05Z",
    "attempts": 1
  }
  ```
</CodeGroup>

**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.

```http theme={null}
GET /api/tasks
```

<CodeGroup>
  ```bash Request theme={null}
  curl http://localhost:8080/api/tasks
  ```

  ```json Response theme={null}
  [
    {"id": "...", "task_type": "resize", "status": "completed", "created_at": "..."},
    {"id": "...", "task_type": "process", "status": "pending", "created_at": "..."}
  ]
  ```
</CodeGroup>

### Delete Task

Delete a task from the queue.

```http theme={null}
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.

```http theme={null}
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.

<CodeGroup>
  ```bash Request theme={null}
  curl http://localhost:8080/health
  ```

  ```json Response theme={null}
  {
    "status": "healthy",
    "queue_size": 42,
    "workers": 100,
    "timestamp": "2024-01-15T10:30:00Z"
  }
  ```
</CodeGroup>

### Metrics

Prometheus metrics endpoint.

```http theme={null}
GET /metrics
```

```text Response theme={null}
# 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](/monitoring/prometheus) for all available metrics.

### API Metrics

JSON metrics summary.

<CodeGroup>
  ```bash Request theme={null}
  curl http://localhost:8080/api/metrics
  ```

  ```json Response theme={null}
  {
    "tasks_received": 1234,
    "tasks_processed_success": 1200,
    "tasks_processed_failed": 34,
    "queue_size": 42,
    "daemon_healthy": true
  }
  ```
</CodeGroup>

### Swagger UI

Interactive API documentation.

```
GET /docs
```

## Error Responses

```json theme={null}
{
  "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:

```bash theme={null}
# 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}'
```

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