260 lines
5.8 KiB
Markdown
260 lines
5.8 KiB
Markdown
# 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"
|
|
}
|
|
```
|