# Work Queue API

## Overview

A lightweight internal API that tracks the full lifecycle of work items across TheLab agents.

## Quick start

1. Start the stack with Docker Compose.
2. Wait for PostgreSQL and the API healthcheck to pass.
3. Call `GET /health`.
4. Create projects and work items with the API endpoints below.

## Status lifecycle diagram

```text
queued -> dispatched -> in_progress -> completed
                               \-> blocked
                               \-> failed
queued/dispatched -> cancelled
```

## API endpoint reference

### Projects
- `POST /projects`
- `GET /projects`
- `GET /projects/{id}`
- `PATCH /projects/{id}`

### Work
- `POST /work`
- `GET /work`
- `GET /work/{id}`
- `PATCH /work/{id}`
- `DELETE /work/{id}`

### Monitoring
- `GET /work?status=in_progress`
- `GET /work?status=blocked`
- `GET /work?status=failed`
- `GET /work?status=completed&since=<ts>`

## Docker Compose

```yaml
version: '3.8'
services:
  api:
    image: git.danhenry.dev/thelab/work-queue-api:latest
    ports:
      - "8080:8080"
    environment:
      - DATABASE_URL=postgresql://postgres:password@db:5432/work_queue
      - PORT=8080
    depends_on:
      db:
        condition: service_healthy
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "wget", "-qO-", "http://localhost:8080/health"]
      interval: 30s
      timeout: 10s
      retries: 3

  db:
    image: postgres:16-alpine
    environment:
      - POSTGRES_PASSWORD=password
      - POSTGRES_DB=work_queue
    volumes:
      - ./data/postgres:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 10s
      timeout: 5s
      retries: 5
```

## Notes
- FastAPI web service
- PostgreSQL storage
- No auth
- One `in_progress` work item per agent is enforced in the database