# API Reference

Base URL: `http://app-01:8080`

The Work Queue WebUI connects to the Work Queue API to display and manage work items. All endpoints return JSON.

---

## Work Items

### GET /work

List work items with optional filters.

**Query Parameters:**
| Parameter | Type | Description |
|---|---|---|
| `status` | `string` | Filter by status |
| `agent` | `string` | Filter by assigned agent |
| `project_id` | `uuid` | Filter by project |
| `since` | `ISO8601` | Return items created after this time |
| `type` | `string` | Filter by work item type |

**Status values:** `queued`, `dispatched`, `in_progress`, `completed`, `failed`, `blocked`, `cancelled`

**Response:** `200 OK`
```json
[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "type": "infra_setup",
    "description": "Set up nginx reverse proxy",
    "priority": 2,
    "status": "completed",
    "assigned_agent": "lennie-s",
    "created_by": "marcus-a",
    "created_at": "2026-04-12T00:00:00Z",
    "updated_at": "2026-04-12T00:30:00Z",
    "outcome": "success",
    "notes": "Deployed successfully"
  }
]
```

---

### POST /work

Submit a new work item.

**Request Body:**
```json
{
  "type": "code_review",
  "description": "Review PR #42 in work-queue-api",
  "priority": 1,
  "agent": "steve-w",
  "project_id": "d1457588-d7ad-4bbe-a252-ffe42cb55a77",
  "payload": {
    "pr": 42,
    "repo": "work-queue-api"
  }
}
```

| Field | Type | Required | Description |
|---|---|---|---|
| `type` | `string` | Yes | Work category (e.g. `code_review`, `bug_fix`, `infra_setup`) |
| `description` | `string` | Yes | Human-readable task description |
| `priority` | `integer` | No | 1 (highest) to 5 (lowest), default 3 |
| `agent` | `string` | No | Agent username to assign |
| `project_id` | `uuid` | No | Associated project |
| `payload` | `object` | No | Arbitrary type-specific data |

**Response:** `201 Created`

---

### PATCH /work/{id}

Update a work item.

**Request Body:**
```json
{
  "status": "completed",
  "outcome": "success",
  "notes": "All checks passed",
  "agent": "lennie-s"
}
```

| Field | Type | Required | Description |
|---|---|---|---|
| `status` | `string` | No | New status |
| `outcome` | `string` | Yes | Required when status is terminal (`success`, `failed`, `cancelled`) |
| `notes` | `string` | No | Human-readable notes |
| `agent` | `string` | No | Reassign to different agent |

**Response:** `200 OK`

---

### GET /work/{id}

Get a single work item with dispatch history.

**Response:** `200 OK`
```json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "type": "infra_setup",
  "description": "Set up nginx reverse proxy",
  "priority": 2,
  "status": "completed",
  "assigned_agent": "lennie-s",
  "created_by": "marcus-a",
  "created_at": "2026-04-12T00:00:00Z",
  "updated_at": "2026-04-12T00:30:00Z",
  "completed_at": "2026-04-12T00:30:00Z",
  "outcome": "success",
  "notes": "Deployed successfully",
  "dispatch_log": [
    {
      "id": "dispatch-uuid",
      "work_item_id": "550e8400-e29b-41d4-a716-446655440000",
      "dispatched_at": "2026-04-12T00:05:00Z",
      "agent": "lennie-s",
      "completed_at": "2026-04-12T00:30:00Z",
      "outcome": "success"
    }
  ]
}
```

---

## Projects

### GET /projects

List all projects.

**Response:** `200 OK`
```json
[
  {
    "id": "d1457588-d7ad-4bbe-a252-ffe42cb55a77",
    "name": "Work Queue WebUI",
    "external_ref": "git.danhenry.dev/thelab/work-queue-webui",
    "created_at": "2026-04-11T00:00:00Z"
  }
]
```

---

### POST /projects

Create a new project.

**Request Body:**
```json
{
  "name": "Shopping List API",
  "external_ref": "git.danhenry.dev/thelab/shopping-list-api"
}
```

| Field | Type | Required | Description |
|---|---|---|---|
| `name` | `string` | Yes | Project name |
| `external_ref` | `string` | No | External identifier (repo URL, Todoist ID, etc.) |

**Response:** `201 Created`

---

### PATCH /projects/{id}

Update a project.

**Request Body:**
```json
{
  "name": "Shopping List API (revived)",
  "external_ref": "git.danhenry.dev/thelab/shopping-list-api"
}
```

**Response:** `200 OK`

---

## WorkItem Shape

| Field | Type | Description |
|---|---|---|
| `id` | `uuid` | Unique identifier |
| `type` | `string` | Work category |
| `description` | `string` | Task description |
| `priority` | `integer` | 1 (highest) to 5 (lowest) |
| `status` | `string` | Current lifecycle state |
| `assigned_agent` | `string\|null` | Agent username |
| `created_by` | `string` | Creator username |
| `created_at` | `ISO8601` | Creation timestamp |
| `updated_at` | `ISO8601` | Last update timestamp |
| `completed_at` | `ISO8601\|null` | Completion timestamp |
| `outcome` | `string\|null` | `success`, `failed`, or `cancelled` |
| `notes` | `string\|null` | Optional notes |
| `payload` | `object\|null` | Type-specific data |
| `project_id` | `uuid\|null` | Associated project |
| `dispatch_log` | `array` | Dispatch history entries |

---

## Status Lifecycle

```
queued → dispatched → in_progress → completed
                              ↘ blocked
                              ↘ failed
           ↘ cancelled (from queued or dispatched only)
```

| Transition | From → To | Notes |
|---|---|---|
| submit | — → queued | New work item created |
| dispatch | queued → dispatched | Assigned to agent |
| pick up | dispatched → in_progress | Agent starts work |
| block | in_progress → blocked | Work stalled |
| complete | in_progress → completed | Requires `outcome: success` |
| fail | in_progress → failed | Requires `outcome: failed` |
| cancel | queued/dispatched → cancelled | Requires `outcome: cancelled` |

---

## Agent Queue

### GET /work/agent/{agent}

Get all work items for a specific agent.

**Response:** `200 OK` — array of WorkItem objects

---

## Health

### GET /health

Returns API health status.

**Response:** `200 OK`
```json
{
  "status": "ok"
}
```