Gas City OpenAPI Reference — v0¶

Parsed from openapi.json Local copy: Scratch/gc-openapi/openapi.json (49,954 lines)

127 endpoints · 300+ schemas · OpenAPI 3.1 · Base path: /v0

API Surface by Domain¶

🏙️ City (Supervisor)¶

Method	Path	Operation
GET	`/v0/cities`	List registered cities
POST	`/v0/cities`	Create a city (async → 202)
GET	`/v0/city/{cityName}`	Get city info (name, path, uptime, agent/rig counts)
PATCH	`/v0/city/{cityName}`	Patch city (suspend/resume)
POST	`/v0/city/{cityName}/unregister`	Unregister city (async → 202)
GET	`/v0/city/{cityName}/status`	City status
GET	`/v0/city/{cityName}/readiness`	City readiness probe
GET	`/v0/city/{cityName}/pending`	Pending human interactions
GET	`/v0/city/{cityName}/usage`	Usage/cost data

🤖 Agents¶

Method	Path	Operation
GET	`/v0/city/{cityName}/agents`	List all agents
POST	`/v0/city/{cityName}/agents`	Create agent
GET	`/v0/city/{cityName}/agent/{name}`	Get agent by name
PUT	`/v0/city/{cityName}/agent/{name}`	Update agent
DELETE	`/v0/city/{cityName}/agent/{name}`	Delete agent
GET	`/v0/city/{cityName}/agent/{name}/output`	Get agent output
GET	`/v0/city/{cityName}/agent/{rig}/{name}`	Get qualified agent (rig-scoped)
PUT	`/v0/city/{cityName}/agent/{rig}/{name}`	Update qualified agent
DELETE	`/v0/city/{cityName}/agent/{rig}/{name}`	Delete qualified agent

Key schema: AgentResponse — name, running, suspended, state, available, provider, rig, model, active_bead, context_pct, context_window, session info

Key schema: AgentPatch — Full mutable agent surface: Provider, Scope, Dir, Rig, Skills, MCP, Env, Pool, Lifecycle, Nudge, IdleTimeout, MaxSessionAge, SessionSetup, SessionLive, InstallAgentHooks, InjectFragments, PromptTemplate, StartCommand, ResumeCommand, WakeMode, MouseMode, MinActiveSessions, MaxActiveSessions, ScaleCheck, ContextAdvisory, etc.

📿 Beads¶

Method	Path	Operation
GET	`/v0/city/{cityName}/beads`	List beads (supports filtering)
POST	`/v0/city/{cityName}/beads`	Create bead
GET	`/v0/city/{cityName}/beads/health`	Beads health check
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
GET	`/v0/city/{cityName}/bead/{id}/deps`	Get bead dependencies
GET	`/v0/city/{cityName}/bead/{id}/graph`	Get bead graph

Key schema: Bead — id, title, status, issue_type, created_at, updated_at, assignee, description, priority, parent, labels[], metadata{}, needs[], dependencies[], ref, from, ephemeral, is_blocked, no_history, defer_until

Key schema: BeadCreateInputBody — title (required), type, description, assignee, rig, priority, parent, labels[], metadata{}, defer_until

Key schema: BeadUpdateBody — title, status, description, assignee, priority, parent, type, labels[], remove_labels[], metadata{}

🚚 Convoys¶

Method	Path	Operation
GET	`/v0/city/{cityName}/convoys`	List convoys
POST	`/v0/city/{cityName}/convoys`	Create convoy
GET	`/v0/city/{cityName}/convoy/{id}`	Get convoy
GET	`/v0/city/{cityName}/convoy/{id}/check`	Check convoy completeness
POST	`/v0/city/{cityName}/convoy/{id}/add`	Add beads to convoy
POST	`/v0/city/{cityName}/convoy/{id}/remove`	Remove beads from convoy
POST	`/v0/city/{cityName}/convoy/{id}/close`	Close convoy

Key schema: ConvoyCheckResponse — convoy_id, total, closed, complete (boolean: all children closed & total > 0)

💬 Sessions¶

Method	Path	Operation
GET	`/v0/city/{cityName}/sessions`	List sessions
POST	`/v0/city/{cityName}/sessions`	Create session (async → 202)
GET	`/v0/city/{cityName}/session/{id}`	Get session
PATCH	`/v0/city/{cityName}/session/{id}`	Patch session
POST	`/v0/city/{cityName}/session/{id}/messages`	Send message to session
POST	`/v0/city/{cityName}/session/{id}/submit`	Submit message (async → 202)
POST	`/v0/city/{cityName}/session/{id}/respond`	Respond to pending interaction
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}/agents`	List session agents
GET	`/v0/city/{cityName}/session/{id}/agents/{agentId}`	Get session agent by ID
GET	`/v0/city/{cityName}/session/{id}/pending`	Get session pending interactions
POST	`/v0/city/{cityName}/session/{id}/close`	Close session
POST	`/v0/city/{cityName}/session/{id}/kill`	Kill 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}/wake`	Wake session
POST	`/v0/city/{cityName}/session/{id}/rename`	Rename session
POST	`/v0/city/{cityName}/session/{id}/permission-mode`	Set permission mode

📧 Mail¶

Method	Path	Operation
GET	`/v0/city/{cityName}/mail`	List mail
POST	`/v0/city/{cityName}/mail`	Send mail
GET	`/v0/city/{cityName}/mail/{id}`	Get mail
DELETE	`/v0/city/{cityName}/mail/{id}`	Delete mail
POST	`/v0/city/{cityName}/mail/{id}/archive`	Archive mail
POST	`/v0/city/{cityName}/mail/{id}/read`	Mark mail read
POST	`/v0/city/{cityName}/mail/{id}/reply`	Reply to mail
POST	`/v0/city/{cityName}/mail/{id}/unread`	Mark mail unread

📡 Events¶

Method	Path	Operation
GET	`/v0/city/{cityName}/events`	List events
GET	`/v0/city/{cityName}/events/stream`	Stream city events (SSE) — use `after_seq` to resume
POST	`/v0/city/{cityName}/events/emit`	Emit custom event
POST	`/v0/city/{cityName}/events/maintenance/rotate`	Rotate events
GET	`/v0/events`	List supervisor events
GET	`/v0/events/stream`	Stream supervisor events (SSE) — use `after_cursor` to resume

Key schema: AsyncAcceptedBody — status, request_id, event_cursor (for SSE resume)

🔧 Providers¶

Method	Path	Operation
GET	`/v0/city/{cityName}/providers`	List providers
POST	`/v0/city/{cityName}/providers`	Create provider
GET	`/v0/city/{cityName}/providers/public`	Public provider listing
GET	`/v0/city/{cityName}/provider/{name}`	Get provider
PATCH	`/v0/city/{cityName}/provider/{name}`	Patch provider
DELETE	`/v0/city/{cityName}/provider/{name}`	Delete provider
GET	`/v0/city/{cityName}/provider-readiness`	Provider readiness
GET	`/v0/provider-readiness`	Supervisor provider readiness

🏗️ Rigs¶

Method	Path	Operation
GET	`/v0/city/{cityName}/rigs`	List rigs
POST	`/v0/city/{cityName}/rigs`	Create rig (async → 202)
GET	`/v0/city/{cityName}/rig/{name}`	Get rig
PATCH	`/v0/city/{cityName}/rig/{name}`	Patch rig
DELETE	`/v0/city/{cityName}/rig/{name}`	Delete rig
POST	`/v0/city/{cityName}/rig/{name}/{action}`	Rig action (provision, etc.)

📜 Formulas & Orders¶

Method	Path	Operation
GET	`/v0/city/{cityName}/formulas`	List formulas
POST	`/v0/city/{cityName}/formulas`	Create formula
GET	`/v0/city/{cityName}/formulas/compile`	Compile formulas
POST	`/v0/city/{cityName}/formulas/install`	Install formula
GET	`/v0/city/{cityName}/formulas/{name}`	Get formula
POST	`/v0/city/{cityName}/formulas/{name}/graph`	Get formula graph
POST	`/v0/city/{cityName}/formulas/{name}/run`	Run formula
DELETE	`/v0/city/{cityName}/formula/{name}`	Delete formula
GET	`/v0/city/{cityName}/orders`	List orders
POST	`/v0/city/{cityName}/orders`	Create order
GET	`/v0/city/{cityName}/orders/pending`	Get pending orders
POST	`/v0/city/{cityName}/orders/evaluate`	Evaluate orders
GET	`/v0/city/{cityName}/order/{name}`	Get order
PUT	`/v0/city/{cityName}/order/{name}`	Update order
DELETE	`/v0/city/{cityName}/order/{name}`	Delete order
POST	`/v0/city/{cityName}/order/{name}/fire`	Fire order
POST	`/v0/city/{cityName}/order/{name}/toggle`	Toggle order

📦 Packs & Config¶

Method	Path	Operation
GET	`/v0/city/{cityName}/packs`	List packs
POST	`/v0/city/{cityName}/packs/refresh`	Refresh packs
GET	`/v0/city/{cityName}/config`	Get effective config
GET	`/v0/city/{cityName}/config/explain`	Explain config (annotated)
GET	`/v0/city/{cityName}/config/validate`	Validate config
POST	`/v0/city/{cityName}/config/reload`	Reload config

🔀 Patches (Runtime Overrides)¶

Method	Path	Operation
GET/PUT	`/v0/city/{cityName}/patches/agents`	List/set all agent patches
GET	`/v0/city/{cityName}/patches/agent/{dir}/{base}`	Get specific agent patch
GET/PUT	`/v0/city/{cityName}/patches/providers`	List/set all provider patches
GET/DELETE	`/v0/city/{cityName}/patches/provider/{name}`	Get/delete provider patch
GET/PUT	`/v0/city/{cityName}/patches/rigs`	List/set all rig patches
GET/DELETE	`/v0/city/{cityName}/patches/rig/{name}`	Get/delete rig patch

🔄 Runs (Workflow Execution)¶

Method	Path	Operation
GET	`/v0/city/{cityName}/runs`	List runs
GET	`/v0/city/{cityName}/runs/census`	Run census
GET	`/v0/city/{cityName}/runs/{run_id}`	Get run
POST	`/v0/city/{cityName}/runs/{run_id}/cancel`	Cancel run
GET	`/v0/city/{cityName}/runs/{run_id}/steps`	Get run steps

🔌 External Messaging (extmsg)¶

Method	Path	Operation
GET	`/v0/city/{cityName}/extmsg/groups`	List messaging groups
POST	`/v0/city/{cityName}/extmsg/groups`	Create group
GET	`/v0/city/{cityName}/extmsg/group/{id}`	Get group
DELETE	`/v0/city/{cityName}/extmsg/group/{id}`	Delete group
PATCH	`/v0/city/{cityName}/extmsg/group/{id}`	Patch group
GET	`/v0/city/{cityName}/extmsg/group/{id}/participants`	List participants
POST	`/v0/city/{cityName}/extmsg/group/{id}/participants`	Add participant
DELETE	`/v0/city/{cityName}/extmsg/group/{id}/participant/{pid}`	Remove participant
GET	`/v0/city/{cityName}/extmsg/group/{id}/transcript`	Get transcript
POST	`/v0/city/{cityName}/extmsg/group/{id}/send`	Send external message

🛡️ Sling, Services, Workflows, Waits¶

Method	Path	Operation
POST	`/v0/city/{cityName}/sling`	Sling bead to target
GET	`/v0/city/{cityName}/services`	List services
GET	`/v0/city/{cityName}/service/{name}`	Get service
POST	`/v0/city/{cityName}/service/{name}/restart`	Restart service
GET	`/v0/city/{cityName}/workflow/{workflow_id}`	Get workflow
DELETE	`/v0/city/{cityName}/workflow/{workflow_id}`	Delete workflow
GET	`/v0/city/{cityName}/waits`	List waits
GET	`/v0/city/{cityName}/wait/{id}`	Get wait

🩺 Health & Readiness¶

Method	Path	Operation
GET	`/v0/readiness`	Supervisor readiness
GET	`/v0/city/{cityName}/readiness`	City readiness
GET	`/v0/city/{cityName}/beads/health`	Beads health
GET	`/v0/city/{cityName}/provider-readiness`	Provider readiness

Key Event Types (from `EventPayload` oneOf)¶

The event stream emits typed envelopes for these categories:

Category	Events
Bead lifecycle	`bead.created`, `bead.updated`, `bead.closed`, `bead.deleted`, `bead.claim.rejected`, `bead.claim.released`, `bead.dead_assignee.reopened`, `bead.worktree.reaped`, `bead.worktree.reap_skipped`
Session lifecycle	`session.created`, `session.updated`, `session.stopped`, `session.crashed`, `session.suspended`, `session.woke`, `session.idle_killed`, `session.max_age_killed`, `session.stranded`, `session.quarantined`, `session.unknown_state`, `session.wake_refused`, `session.reset_stalled`, `session.draining`, `session.undrained`, `session.drain_stop_escalated`, `session.drain_acked_with_assigned_work`, `session.drain_fence_unavailable`, `session.pool_slot_retired_at_drain_deadline`, `session.cold_start_timeout`, `session.demand_claim_divergence`, `session.work_query_failed`
City lifecycle	`city.created`, `city.resumed`, `city.suspended`, `city.unregister_requested`
Controller	`controller.started`, `controller.stopped`, `control.stalled`, `control.root_settle_failed`, `control.dispatcher_scope_gap`
Convoy	`convoy.created`, `convoy.closed`
Mail	`mail.sent`, `mail.read`, `mail.replied`, `mail.archived`, `mail.deleted`, `mail.marked_read`, `mail.marked_unread`
Order/Formula	`order.fired`, `order.completed`, `order.failed`, `order.suppressed`
Execution	`execution.run_anchored`, `execution.step.defined`, `execution.step.started`, `execution.step.completed`, `execution.step.stalled`, `execution.claim.stalled`, `execution.claim_window.expired`, `execution.work.associated`
External Messaging	`extmsg.adapter.added`, `extmsg.adapter.removed`, `extmsg.bound`, `extmsg.unbound`, `extmsg.group.created`, `extmsg.inbound`, `extmsg.outbound`, `extmsg.outbound_channel_mismatch`
Storage	`storage_binding.converged`, `storage_binding.genesis`, `storage_binding.not_configured`, `storage_binding.uncheckable`, `storage_binding.unconverged`, `gc.store.disk.warn`, `gc.store.disk.critical`, `gc.store.maintenance.done`, `gc.store.maintenance.failed`, `beads.conditional_writes.degraded`
Supervisor	`supervisor.started`, `supervisor.shutdown_requested`, `supervisor.fs_pressure_skipped_tick`, `supervisor.request`
Other	`events.rotated`, `project_identity.stamped`, `rig.provision.progress`, `rig.created`, `provider.swapped`, `hook.claim.reclaimed_stale`, `molecule.resolved`, `webhook.received`, `webhook.rejected`, `worker.operation`, `emergency.signaled`, `emergency.acked`, `custom`, `backend.credential.resolved`

Error URNs¶

All errors follow RFC 7807 Problem Details. The type field uses urn:gascity:error:*:

agent-not-found          ambiguous-reference       bad-gateway
bead-not-found           city-not-found            conflict-concurrent-delete
conflict-concurrent-modify  conflict-wrong-state   convoy-not-found
extmsg-group-not-found   forbidden                 formula-not-found
gateway-timeout          idempotency-in-flight     idempotency-mismatch
internal                 invalid-cursor            invalid-request
mail-not-found           method-not-allowed        not-implemented
operation-in-progress    order-not-found           pack-credential-required
pack-not-found           patch-not-found           provider-not-found
rig-not-found            run-not-found             scope-not-found
service-not-found        service-unavailable       session-conflict
session-not-found        sling-cross-rig           sling-cross-store-route
sling-missing-bead       sling-source-workflow-conflict  store-unavailable
transcript-cursor-invalidated  validation-failed   wait-not-found
webhook-rejected         workflow-not-found

Async Request Pattern¶

Many mutating operations return 202 Accepted with:

{
  "status": "accepted",
  "request_id": "<correlation-id>",
  "event_cursor": "<resume-position>"
}

To get the result: Watch /v0/city/{cityName}/events/stream?after_seq={event_cursor} for request.result.* or request.failed with the matching request_id.

Response Header¶

Every response carries:

X-GC-Request-Id: <opaque-id>

For log correlation across requests.