Gas City Supervisor API — Full Surface
Source: https://raw.githubusercontent.com/gastownhall/gascity/main/docs/reference/schema/openapi.json
Version: OpenAPI 3.1.0 | Gas City Supervisor API v0.1.0
Total Endpoints: 127
Health & Readiness
| Method |
Path |
Purpose |
| GET |
/health |
Health check |
| GET |
/v0/readiness |
Global readiness |
| GET |
/v0/provider-readiness |
Global provider readiness |
Cities
| Method |
Path |
Purpose |
| GET |
/v0/cities |
List all cities |
| POST |
/v0/city |
Register a city |
| GET |
/v0/city/{cityName} |
Get city details |
| PATCH |
/v0/city/{cityName} |
Update city |
| GET |
/v0/city/{cityName}/status |
City status (agents, sessions, stores) |
| GET |
/v0/city/{cityName}/config |
Get expanded config |
| GET |
/v0/city/{cityName}/config/defaults |
Get config defaults |
| GET |
/v0/city/{cityName}/config/explain |
Explain config resolution |
| GET |
/v0/city/{cityName}/config/validate |
Validate config |
| GET |
/v0/city/{cityName}/readiness |
City readiness |
| GET |
/v0/city/{cityName}/provider-readiness |
City provider readiness |
| GET |
/v0/city/{cityName}/pending |
Pending operations |
| GET |
/v0/city/{cityName}/usage |
Token/cost usage |
| POST |
/v0/city/{cityName}/unregister |
Unregister city |
Agents (18 endpoints)
| Method |
Path |
Purpose |
| GET |
/v0/city/{cityName}/agents |
List agents |
| POST |
/v0/city/{cityName}/agents |
Create agent |
| GET |
/v0/city/{cityName}/agent/{base} |
Get agent (unqualified) |
| PATCH |
/v0/city/{cityName}/agent/{base} |
Update agent |
| DELETE |
/v0/city/{cityName}/agent/{base} |
Delete agent |
| GET |
/v0/city/{cityName}/agent/{base}/output |
Get agent output |
| GET |
/v0/city/{cityName}/agent/{base}/output/stream |
Stream agent output (SSE) |
| POST |
/v0/city/{cityName}/agent/{base}/{action} |
Agent action (suspend/resume/restart) |
| GET |
/v0/city/{cityName}/agent/{dir}/{base} |
Get agent (qualified: rig/agent) |
| PATCH |
/v0/city/{cityName}/agent/{dir}/{base} |
Update agent (qualified) |
| DELETE |
/v0/city/{cityName}/agent/{dir}/{base} |
Delete agent (qualified) |
| GET |
/v0/city/{cityName}/agent/{dir}/{base}/output |
Get agent output (qualified) |
| GET |
/v0/city/{cityName}/agent/{dir}/{base}/output/stream |
Stream agent output (qualified, SSE) |
| POST |
/v0/city/{cityName}/agent/{dir}/{base}/{action} |
Agent action (qualified) |
Beads (10 endpoints)
| Method |
Path |
Purpose |
| GET |
/v0/city/{cityName}/beads |
List beads |
| POST |
/v0/city/{cityName}/beads |
Create bead |
| GET |
/v0/city/{cityName}/beads/ready |
Federated ready frontier |
| GET |
/v0/city/{cityName}/beads/graph/{rootID} |
Get bead dependency graph |
| GET |
/v0/city/{cityName}/bead/{id} |
Get bead |
| PATCH |
/v0/city/{cityName}/bead/{id} |
Update bead |
| DELETE |
/v0/city/{cityName}/bead/{id} |
Delete bead |
| POST |
/v0/city/{cityName}/bead/{id}/assign |
Assign bead |
| POST |
/v0/city/{cityName}/bead/{id}/close |
Close bead |
| POST |
/v0/city/{cityName}/bead/{id}/reopen |
Reopen bead |
| POST |
/v0/city/{cityName}/bead/{id}/update |
Update bead (POST variant) |
| GET |
/v0/city/{cityName}/bead/{id}/deps |
Get bead dependencies |
Convoys (11 endpoints)
| Method |
Path |
Purpose |
| GET |
/v0/city/{cityName}/convoys |
List convoys |
| POST |
/v0/city/{cityName}/convoys |
Create convoy |
| GET |
/v0/city/{cityName}/convoy/{id} |
Get convoy |
| DELETE |
/v0/city/{cityName}/convoy/{id} |
Delete convoy |
| POST |
/v0/city/{cityName}/convoy/{id}/add |
Add bead to convoy |
| POST |
/v0/city/{cityName}/convoy/{id}/remove |
Remove bead from convoy |
| POST |
/v0/city/{cityName}/convoy/{id}/close |
Close convoy |
| GET |
/v0/city/{cityName}/convoy/{id}/check |
Check convoy completion |
Events (5 endpoints)
| Method |
Path |
Purpose |
| GET |
/v0/city/{cityName}/events |
List events |
| POST |
/v0/city/{cityName}/events |
Emit custom event |
| GET |
/v0/city/{cityName}/events/stream |
Stream events (SSE) |
| POST |
/v0/city/{cityName}/events/rotate |
Force rotate event log |
| GET |
/v0/events |
Global events |
| GET |
/v0/events/stream |
Global event stream (SSE) |
Mail (8 endpoints)
| Method |
Path |
Purpose |
| GET |
/v0/city/{cityName}/mail |
List mail |
| POST |
/v0/city/{cityName}/mail |
Send mail |
| GET |
/v0/city/{cityName}/mail/{id} |
Read mail |
| PATCH |
/v0/city/{cityName}/mail/{id} |
Update mail (mark read/archive) |
| DELETE |
/v0/city/{cityName}/mail/{id} |
Delete mail |
| GET |
/v0/city/{cityName}/mail/count |
Mail count |
| GET |
/v0/city/{cityName}/mail/inbox |
Inbox view |
| GET |
/v0/city/{cityName}/mail/threads |
Thread view |
Orders (9 endpoints)
| Method |
Path |
Purpose |
| GET |
/v0/city/{cityName}/orders |
List orders |
| GET |
/v0/city/{cityName}/orders/check |
Check order health |
| GET |
/v0/city/{cityName}/orders/feed |
Order activity feed |
| GET |
/v0/city/{cityName}/orders/history |
Order execution history |
| GET |
/v0/city/{cityName}/order/{name} |
Get order details |
| GET |
/v0/city/{cityName}/order/history/{bead_id} |
Order history by bead |
| POST |
/v0/city/{cityName}/order/{name}/run |
Manual order trigger |
| POST |
/v0/city/{cityName}/order/{name}/enable |
Enable order |
| POST |
/v0/city/{cityName}/order/{name}/disable |
Disable order |
Rigs (7 endpoints)
| Method |
Path |
Purpose |
| GET |
/v0/city/{cityName}/rigs |
List rigs |
| POST |
/v0/city/{cityName}/rigs |
Add rig |
| GET |
/v0/city/{cityName}/rig/{name} |
Get rig |
| PATCH |
/v0/city/{cityName}/rig/{name} |
Update rig |
| DELETE |
/v0/city/{cityName}/rig/{name} |
Remove rig |
| POST |
/v0/city/{cityName}/rig/{name}/{action} |
Rig action (suspend/resume/restart) |
Sessions (20 endpoints)
| Method |
Path |
Purpose |
| GET |
/v0/city/{cityName}/sessions |
List sessions |
| POST |
/v0/city/{cityName}/sessions |
Create session |
| GET |
/v0/city/{cityName}/session/{id} |
Get session |
| PATCH |
/v0/city/{cityName}/session/{id} |
Update session |
| POST |
/v0/city/{cityName}/session/{id}/messages |
Send message to session |
| POST |
/v0/city/{cityName}/session/{id}/submit |
Submit work to session |
| POST |
/v0/city/{cityName}/session/{id}/respond |
Respond to session prompt |
| POST |
/v0/city/{cityName}/session/{id}/permission-mode |
Set permission mode |
| POST |
/v0/city/{cityName}/session/{id}/rename |
Rename session |
| POST |
/v0/city/{cityName}/session/{id}/wake |
Wake session |
| POST |
/v0/city/{cityName}/session/{id}/stop |
Stop session |
| POST |
/v0/city/{cityName}/session/{id}/suspend |
Suspend session |
| POST |
/v0/city/{cityName}/session/{id}/close |
Close session |
| POST |
/v0/city/{cityName}/session/{id}/kill |
Kill session |
| GET |
/v0/city/{cityName}/session/{id}/stream |
Stream session output (SSE) |
| GET |
/v0/city/{cityName}/session/{id}/transcript |
Get session transcript |
| GET |
/v0/city/{cityName}/session/{id}/pending |
Pending session operations |
| GET |
/v0/city/{cityName}/session/{id}/agents |
List session agents |
| GET |
/v0/city/{cityName}/session/{id}/agents/{agentId} |
Get session agent |
Sling
| Method |
Path |
Purpose |
| POST |
/v0/city/{cityName}/sling |
Route work to agent/pool/formula |
Workflows (Runs)
| Method |
Path |
Purpose |
| GET |
/v0/city/{cityName}/runs |
List workflow runs |
| GET |
/v0/city/{cityName}/runs/census |
Workflow census |
| GET |
/v0/city/{cityName}/runs/{run_id} |
Get workflow run |
| POST |
/v0/city/{cityName}/runs/{run_id}/cancel |
Cancel workflow run |
| GET |
/v0/city/{cityName}/runs/{run_id}/steps |
Get workflow steps |
| GET |
/v0/city/{cityName}/workflow/{workflow_id} |
Get workflow |
| DELETE |
/v0/city/{cityName}/workflow/{workflow_id} |
Delete workflow |
External Messaging (8 endpoints)
| Method |
Path |
Purpose |
| GET |
/v0/city/{cityName}/extmsg/adapters |
List adapters |
| POST |
/v0/city/{cityName}/extmsg/adapters |
Register adapter |
| DELETE |
/v0/city/{cityName}/extmsg/adapters |
Remove adapter |
| GET |
/v0/city/{cityName}/extmsg/groups |
List groups |
| POST |
/v0/city/{cityName}/extmsg/groups |
Create group |
| GET |
/v0/city/{cityName}/extmsg/bindings |
List bindings |
| POST |
/v0/city/{cityName}/extmsg/bind |
Bind agent to group |
| POST |
/v0/city/{cityName}/extmsg/inbound |
Inbound message |
| POST |
/v0/city/{cityName}/extmsg/outbound |
Outbound message |
| DELETE |
/v0/city/{cityName}/extmsg/participants |
Remove participants |
Patches (Runtime Config Overrides)
| Method |
Path |
Purpose |
| GET |
/v0/city/{cityName}/patches/agents |
List agent patches |
| PUT |
/v0/city/{cityName}/patches/agents |
Set agent patches |
| GET |
/v0/city/{cityName}/patches/agent/{base} |
Get agent patch |
| DELETE |
/v0/city/{cityName}/patches/agent/{base} |
Remove agent patch |
| GET |
/v0/city/{cityName}/patches/agent/{dir}/{base} |
Get qualified agent patch |
| DELETE |
/v0/city/{cityName}/patches/agent/{dir}/{base} |
Remove qualified agent patch |
| GET |
/v0/city/{cityName}/patches/providers |
List provider patches |
| PUT |
/v0/city/{cityName}/patches/providers |
Set provider patches |
| GET |
/v0/city/{cityName}/patches/provider/{name} |
Get provider patch |
| DELETE |
/v0/city/{cityName}/patches/provider/{name} |
Remove provider patch |
| GET |
/v0/city/{cityName}/patches/rigs |
List rig patches |
| PUT |
/v0/city/{cityName}/patches/rigs |
Set rig patches |
| GET |
/v0/city/{cityName}/patches/rig/{name} |
Get rig patch |
| DELETE |
/v0/city/{cityName}/patches/rig/{name} |
Remove rig patch |
Providers
| Method |
Path |
Purpose |
| GET |
/v0/city/{cityName}/providers |
List providers |
| POST |
/v0/city/{cityName}/providers |
Create provider |
| GET |
/v0/city/{cityName}/providers/public |
List public providers |
| GET |
/v0/city/{cityName}/provider/{name} |
Get provider |
| PATCH |
/v0/city/{cityName}/provider/{name} |
Update provider |
| DELETE |
/v0/city/{cityName}/provider/{name} |
Delete provider |
Packs
| Method |
Path |
Purpose |
| GET |
/v0/city/{cityName}/packs |
List packs |
| POST |
/v0/city/{cityName}/packs |
Install pack |
| DELETE |
/v0/city/{cityName}/packs/{name} |
Remove pack |
Services
| Method |
Path |
Purpose |
| GET |
/v0/city/{cityName}/services |
List services |
| GET |
/v0/city/{cityName}/service/{name} |
Get service |
| POST |
/v0/city/{cityName}/service/{name}/restart |
Restart service |
Waits
| Method |
Path |
Purpose |
| GET |
/v0/city/{cityName}/waits |
List durable waits |
| GET |
/v0/city/{cityName}/wait/{id} |
Get wait |
🔑 Hidden Gems for Bluefly
Endpoints we should be using but probably aren't:
-
POST /v0/city/{cityName}/sling — HTTP API for gc sling. Could wire ContextControl or webhooks to dispatch work via REST.
-
GET .../agent/{dir}/{base}/output/stream — Real-time SSE stream of agent output. Could power a live dashboard without tmux attach.
-
GET .../events/stream — SSE event stream. Could power real-time observability in ContextControl or AgentDash.
-
GET .../beads/ready — Federated ready frontier via API. Could power a "ready work" dashboard.
-
GET .../beads/graph/{rootID} — Bead dependency graph via API. Could visualize convoy/workflow progress.
-
GET .../runs + GET .../runs/{run_id}/steps — Workflow run inspection. Formula v2 execution visibility.
-
POST .../events — Emit custom events. Could fire Bluefly-specific events for order triggers.
-
External Messaging (extmsg) — Full adapter system for bridging Gas City to Slack, Discord, etc. 8 endpoints.
-
Patches API — Runtime config overrides for agents, providers, rigs WITHOUT editing TOML files. Hot-reconfigure.
-
GET .../usage — Token/cost accounting via API. Could power the economic scorecard.
-
GET .../config/explain — Shows how config was resolved (which pack contributed what). Debug tool.
-
GET .../session/{id}/transcript — Session transcript via API. Could power audit/review workflows.