work-queue-webui/docs/api.md

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

[
  {
    "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:

{
  "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:

{
  "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

{
  "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

[
  {
    "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:

{
  "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:

{
  "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

{
  "status": "ok"
}