Townhall REST API

townhall is Tinytown’s REST control plane daemon. It exposes the same orchestration services used by the tt CLI over HTTP.

Start the Server

# From a town directory
townhall

# Explicit REST mode
townhall rest

# Override bind/port
townhall rest --bind 127.0.0.1 --port 8080

Defaults come from tinytown.toml:

[townhall]
bind = "127.0.0.1"
rest_port = 8080
request_timeout_ms = 30000

Endpoint Groups

The router is split into public/read/write/management groups:

• Public: GET /health, GET /ready, GET /metrics
• Read (town.read): GET /v1/town, GET /v1/status, GET /v1/agents, GET /v1/tasks/pending, GET /v1/backlog, GET /v1/agents/{agent}/inbox
• Write (town.write): POST /v1/tasks/assign, POST /v1/backlog, POST /v1/backlog/{task_id}/claim, POST /v1/backlog/assign-all, DELETE /v1/backlog/{task_id}, POST /v1/messages/send
• Agent management (agent.manage): POST /v1/agents, POST /v1/agents/{agent}/kill, POST /v1/agents/{agent}/restart, POST /v1/agents/prune, POST /v1/recover, POST /v1/reclaim

The public probes have distinct purposes:

• /health: lightweight process liveness with uptime_secs
• /ready: verifies townhall can still reach Redis, reporting Redis latency, town name, and dispatcher heartbeat state
• /metrics: Prometheus-style text metrics for agent counts by state, task queue depth, completed tasks, active missions, and Redis latency

Compatibility aliases /healthz and /readyz remain available for existing deployments.

Authentication

townhall supports three auth modes in config:

• none (default): local/no-auth mode
• api_key: API key via Authorization: Bearer <key> or X-API-Key
• oidc: declared in config, not yet implemented in middleware

Generate an API key + Argon2 hash:

tt auth gen-key

Then configure:

[townhall.auth]
mode = "api_key"
api_key_hash = "$argon2id$..."
api_key_scopes = ["town.read", "town.write", "agent.manage"]

Example request:

curl -H "Authorization: Bearer $TOWNHALL_API_KEY" \
  http://127.0.0.1:8080/v1/status

Startup Safety Rules

At startup, townhall fails fast when:

• Binding to a non-loopback address with auth.mode = "none"
• TLS is enabled but cert_file/key_file are missing or invalid
• mTLS is required but ca_file is missing or invalid

OpenAPI Spec

The REST contract is documented in:

• docs/openapi/townhall-v1.yaml

You can load this file in Swagger UI, Stoplight, or Redoc for interactive exploration.