Add full documentation: MkDocs setup, API reference, user guide, deployment guide
Some checks failed
Build and Push Docker Image / build-and-push (push) Failing after 55s
Some checks failed
Build and Push Docker Image / build-and-push (push) Failing after 55s
This commit is contained in:
Lennie S.
259
docs/api.md
Normal file
259
docs/api.md
Normal file
@@ -0,0 +1,259 @@
|
||||
# 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"
|
||||
}
|
||||
```
|
||||
Reference in New Issue
Block a user