work-queue-api/docs/index.md

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

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

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