openapi: 3.1.0
info:
title: Townhall API
version: 1.0.0
description: |
REST API for Tinytown multi-agent orchestration.
Townhall provides HTTP access to all Tinytown operations that were previously
only available via the `tt` CLI. This enables mobile, web, and automation clients
to manage agent towns.
license:
name: MIT
url: https://opensource.org/licenses/MIT
contact:
name: Tinytown
url: https://github.com/redis-field-engineering/tinytown
servers:
- url: http://localhost:8080
description: Local development server
tags:
- name: Health
description: Health check endpoints
- name: Town
description: Town information and status
- name: Agents
description: Agent lifecycle management
- name: Tasks
description: Task assignment operations
- name: Backlog
description: Global backlog management
- name: Messages
description: Inter-agent messaging
- name: Recovery
description: Recovery and reclaim operations
- name: Missions
description: |
Mission Mode operations for autonomous multi-issue execution.
Missions orchestrate multiple GitHub issues/docs into a dependency-aware
work graph with automatic PR/CI monitoring.
paths:
/health:
get:
tags: [Health]
summary: Liveness check
operationId: healthCheck
responses:
'200':
description: Service is alive
content:
application/json:
schema:
type: object
properties:
status:
type: string
example: ok
uptime_secs:
type: integer
example: 3600
/ready:
get:
tags: [Health]
summary: Readiness check
operationId: readinessCheck
responses:
'200':
description: Service is ready to serve requests
content:
application/json:
schema:
type: object
properties:
status:
type: string
example: ready
redis:
type: string
example: connected
redis_latency_ms:
type: number
format: double
example: 1.2
dispatcher:
type: string
example: running
town:
type: string
example: mytown
'503':
description: Service is running but cannot reach required dependencies
content:
application/json:
schema:
type: object
properties:
status:
type: string
example: not_ready
redis:
type: string
example: disconnected
dispatcher:
type: string
example: unknown
town:
type: string
example: mytown
detail:
type: string
example: Redis ping failed
/metrics:
get:
tags: [Health]
summary: Prometheus metrics
operationId: metrics
responses:
'200':
description: Prometheus text exposition for townhall metrics
content:
text/plain:
schema:
type: string
example: |
# HELP tinytown_up Whether the townhall process is running.
# TYPE tinytown_up gauge
tinytown_up 1
# HELP tinytown_tasks_pending Number of queued tasks across backlog and agent inboxes.
# TYPE tinytown_tasks_pending gauge
tinytown_tasks_pending 5
# HELP tinytown_missions_active Number of active missions.
# TYPE tinytown_missions_active gauge
tinytown_missions_active 1
'503':
description: Metrics scrape failed because backing services are unavailable
content:
text/plain:
schema:
type: string
/api/scaling:
get:
tags: [Health]
summary: Autoscaler scaling signal
operationId: scalingSignal
responses:
'200':
description: JSON scaling snapshot for external autoscalers
content:
application/json:
schema:
type: object
required:
- town
- timestamp
- queue_depth
- pending_tasks
- in_flight_tasks
- active_agents
- cold_agents
- desired_agents
- max_agents
- scaling_recommendation
properties:
town:
type: string
example: mytown
timestamp:
type: string
format: date-time
queue_depth:
type: integer
minimum: 0
example: 3
pending_tasks:
type: integer
minimum: 0
example: 2
in_flight_tasks:
type: integer
minimum: 0
example: 1
active_agents:
type: integer
minimum: 0
example: 1
cold_agents:
type: integer
minimum: 0
example: 0
desired_agents:
type: integer
minimum: 0
example: 3
max_agents:
type: integer
minimum: 1
example: 10
scaling_recommendation:
type: string
enum: [scale_up, steady, scale_down, scale_to_zero]
'503':
description: Scaling signal unavailable because backing services are unavailable
content:
application/json:
schema:
$ref: '#/components/schemas/ProblemDetails'
/v1/town:
get:
tags: [Town]
summary: Get town information
operationId: getTown
responses:
'200':
description: Town information
content:
application/json:
schema:
$ref: '#/components/schemas/TownInfo'
/v1/status:
get:
tags: [Town]
summary: Get comprehensive town status with all agents
operationId: getStatus
parameters:
- name: deep
in: query
schema:
type: boolean
default: false
description: Include detailed agent information
responses:
'200':
description: Town status
content:
application/json:
schema:
$ref: '#/components/schemas/TownStatus'
/v1/agents:
get:
tags: [Agents]
summary: List all agents
operationId: listAgents
responses:
'200':
description: List of agents
content:
application/json:
schema:
$ref: '#/components/schemas/AgentList'
post:
tags: [Agents]
summary: Spawn a new agent
operationId: spawnAgent
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/SpawnAgentRequest'
responses:
'201':
description: Agent spawned
content:
application/json:
schema:
$ref: '#/components/schemas/SpawnAgentResponse'
/v1/agents/{agent}/kill:
post:
tags: [Agents]
summary: Stop an agent gracefully
operationId: killAgent
parameters:
- $ref: '#/components/parameters/AgentName'
responses:
'200':
description: Agent stopped
content:
application/json:
schema:
$ref: '#/components/schemas/AgentActionResponse'
/v1/agents/{agent}/restart:
post:
tags: [Agents]
summary: Restart a stopped agent
operationId: restartAgent
parameters:
- $ref: '#/components/parameters/AgentName'
responses:
'200':
description: Agent restarted
content:
application/json:
schema:
$ref: '#/components/schemas/AgentActionResponse'
/v1/agents/prune:
post:
tags: [Agents]
summary: Prune stopped/error agents from active roster
operationId: pruneAgents
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/PruneRequest'
responses:
'200':
description: Agents pruned
content:
application/json:
schema:
$ref: '#/components/schemas/PruneResponse'
/v1/tasks/assign:
post:
tags: [Tasks]
summary: Assign a task to an agent
operationId: assignTask
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/AssignTaskRequest'
responses:
'201':
description: Task assigned
content:
application/json:
schema:
$ref: '#/components/schemas/AssignTaskResponse'
/v1/tasks/pending:
get:
tags: [Tasks]
summary: List pending tasks across all agents
operationId: listPendingTasks
responses:
'200':
description: Pending tasks
content:
application/json:
schema:
$ref: '#/components/schemas/PendingTaskList'
/v1/backlog:
get:
tags: [Backlog]
summary: List backlog tasks
operationId: listBacklog
responses:
'200':
description: Backlog items
content:
application/json:
schema:
$ref: '#/components/schemas/BacklogList'
post:
tags: [Backlog]
summary: Add task to backlog
operationId: addToBacklog
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/AddBacklogRequest'
responses:
'201':
description: Task added to backlog
content:
application/json:
schema:
$ref: '#/components/schemas/AddBacklogResponse'
/v1/backlog/{task_id}/claim:
post:
tags: [Backlog]
summary: Claim a backlog task for an agent
operationId: claimBacklogTask
parameters:
- $ref: '#/components/parameters/TaskId'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ClaimRequest'
responses:
'200':
description: Task claimed
content:
application/json:
schema:
$ref: '#/components/schemas/ClaimResponse'
/v1/backlog/assign-all:
post:
tags: [Backlog]
summary: Assign all backlog tasks to an agent
operationId: assignAllBacklog
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/AssignAllRequest'
responses:
'200':
description: Tasks assigned
content:
application/json:
schema:
$ref: '#/components/schemas/AssignAllResponse'
/v1/backlog/{task_id}:
delete:
tags: [Backlog]
summary: Remove a backlog task
operationId: removeBacklogTask
parameters:
- $ref: '#/components/parameters/TaskId'
responses:
'200':
description: Task removed
content:
application/json:
schema:
$ref: '#/components/schemas/RemoveBacklogResponse'
/v1/messages/send:
post:
tags: [Messages]
summary: Send a message to an agent
operationId: sendMessage
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/SendMessageRequest'
responses:
'201':
description: Message sent
content:
application/json:
schema:
$ref: '#/components/schemas/SendMessageResponse'
/v1/agents/{agent}/inbox:
get:
tags: [Messages]
summary: Get agent inbox
operationId: getInboxGet
parameters:
- $ref: '#/components/parameters/AgentName'
responses:
'200':
description: Inbox contents
content:
application/json:
schema:
$ref: '#/components/schemas/InboxResponse'
post:
tags: [Messages]
summary: Get agent inbox
operationId: getInboxPost
parameters:
- $ref: '#/components/parameters/AgentName'
responses:
'200':
description: Inbox contents
content:
application/json:
schema:
$ref: '#/components/schemas/InboxResponse'
/v1/recover:
post:
tags: [Recovery]
summary: Recover orphaned agents
operationId: recover
responses:
'200':
description: Recovery complete
content:
application/json:
schema:
$ref: '#/components/schemas/RecoverResponse'
/v1/reclaim:
post:
tags: [Recovery]
summary: Reclaim tasks from dead agents
operationId: reclaim
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ReclaimRequest'
responses:
'200':
description: Tasks reclaimed
content:
application/json:
schema:
$ref: '#/components/schemas/ReclaimResponse'
/v1/missions:
get:
tags: [Missions]
summary: List all missions
operationId: listMissions
parameters:
- name: active_only
in: query
schema:
type: boolean
default: true
description: Only return active missions (planning, running, blocked)
responses:
'200':
description: List of missions
content:
application/json:
schema:
$ref: '#/components/schemas/MissionList'
post:
tags: [Missions]
summary: Start a new mission
description: |
Create and start a new mission with the given objectives.
Objectives can be GitHub issues or local document paths.
operationId: startMission
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/StartMissionRequest'
responses:
'201':
description: Mission created and started
content:
application/json:
schema:
$ref: '#/components/schemas/StartMissionResponse'
'400':
description: Invalid request
content:
application/json:
schema:
$ref: '#/components/schemas/ProblemDetails'
/v1/missions/{mission_id}:
get:
tags: [Missions]
summary: Get mission status
description: |
Get detailed status of a mission including work items and watches.
operationId: getMissionStatus
parameters:
- $ref: '#/components/parameters/MissionId'
- name: include_work
in: query
schema:
type: boolean
default: false
description: Include work item details
- name: include_watches
in: query
schema:
type: boolean
default: false
description: Include watch item details
- name: include_events
in: query
schema:
type: boolean
default: false
description: Include recent activity events
responses:
'200':
description: Mission status
content:
application/json:
schema:
$ref: '#/components/schemas/MissionStatus'
'404':
description: Mission not found
content:
application/json:
schema:
$ref: '#/components/schemas/ProblemDetails'
delete:
tags: [Missions]
summary: Delete a mission
description: |
Delete a mission and all associated data (work items, watches, events).
Only allowed for completed or failed missions unless force=true.
operationId: deleteMission
parameters:
- $ref: '#/components/parameters/MissionId'
- name: force
in: query
schema:
type: boolean
default: false
description: Force delete even if mission is active
responses:
'200':
description: Mission deleted
content:
application/json:
schema:
$ref: '#/components/schemas/DeleteMissionResponse'
'404':
description: Mission not found
content:
application/json:
schema:
$ref: '#/components/schemas/ProblemDetails'
'409':
description: Mission is still active
content:
application/json:
schema:
$ref: '#/components/schemas/ProblemDetails'
/v1/missions/{mission_id}/resume:
post:
tags: [Missions]
summary: Resume a stopped or blocked mission
operationId: resumeMission
parameters:
- $ref: '#/components/parameters/MissionId'
responses:
'200':
description: Mission resumed
content:
application/json:
schema:
$ref: '#/components/schemas/MissionActionResponse'
'404':
description: Mission not found
content:
application/json:
schema:
$ref: '#/components/schemas/ProblemDetails'
'409':
description: Mission cannot be resumed (e.g., already running)
content:
application/json:
schema:
$ref: '#/components/schemas/ProblemDetails'
/v1/missions/{mission_id}/stop:
post:
tags: [Missions]
summary: Stop an active mission
operationId: stopMission
parameters:
- $ref: '#/components/parameters/MissionId'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/StopMissionRequest'
responses:
'200':
description: Mission stopped
content:
application/json:
schema:
$ref: '#/components/schemas/MissionActionResponse'
'404':
description: Mission not found
content:
application/json:
schema:
$ref: '#/components/schemas/ProblemDetails'
/v1/missions/{mission_id}/work:
get:
tags: [Missions]
summary: List work items for a mission
operationId: listWorkItems
parameters:
- $ref: '#/components/parameters/MissionId'
- name: status
in: query
schema:
type: string
enum: [pending, ready, assigned, running, blocked, done]
description: Filter by work item status
responses:
'200':
description: List of work items
content:
application/json:
schema:
$ref: '#/components/schemas/WorkItemList'
'404':
description: Mission not found
content:
application/json:
schema:
$ref: '#/components/schemas/ProblemDetails'
/v1/missions/{mission_id}/work/{work_item_id}:
get:
tags: [Missions]
summary: Get a specific work item
operationId: getWorkItem
parameters:
- $ref: '#/components/parameters/MissionId'
- $ref: '#/components/parameters/WorkItemId'
responses:
'200':
description: Work item details
content:
application/json:
schema:
$ref: '#/components/schemas/WorkItem'
'404':
description: Work item not found
content:
application/json:
schema:
$ref: '#/components/schemas/ProblemDetails'
patch:
tags: [Missions]
summary: Update a work item
description: |
Update work item status or add artifacts. Used by agents to report
progress and completion.
operationId: updateWorkItem
parameters:
- $ref: '#/components/parameters/MissionId'
- $ref: '#/components/parameters/WorkItemId'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateWorkItemRequest'
responses:
'200':
description: Work item updated
content:
application/json:
schema:
$ref: '#/components/schemas/WorkItem'
'404':
description: Work item not found
content:
application/json:
schema:
$ref: '#/components/schemas/ProblemDetails'
/v1/missions/{mission_id}/watches:
get:
tags: [Missions]
summary: List watch items for a mission
operationId: listWatchItems
parameters:
- $ref: '#/components/parameters/MissionId'
- name: status
in: query
schema:
type: string
enum: [active, snoozed, done]
description: Filter by watch status
responses:
'200':
description: List of watch items
content:
application/json:
schema:
$ref: '#/components/schemas/WatchItemList'
'404':
description: Mission not found
content:
application/json:
schema:
$ref: '#/components/schemas/ProblemDetails'
/v1/missions/{mission_id}/watches/{watch_id}/snooze:
post:
tags: [Missions]
summary: Snooze a watch item
description: Temporarily pause monitoring for the specified duration.
operationId: snoozeWatch
parameters:
- $ref: '#/components/parameters/MissionId'
- $ref: '#/components/parameters/WatchId'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/SnoozeWatchRequest'
responses:
'200':
description: Watch snoozed
content:
application/json:
schema:
$ref: '#/components/schemas/WatchItem'
'404':
description: Watch not found
content:
application/json:
schema:
$ref: '#/components/schemas/ProblemDetails'
/v1/missions/{mission_id}/events:
get:
tags: [Missions]
summary: Get mission activity events
operationId: getMissionEvents
parameters:
- $ref: '#/components/parameters/MissionId'
- name: limit
in: query
schema:
type: integer
default: 20
maximum: 100
description: Maximum number of events to return
responses:
'200':
description: Mission events
content:
application/json:
schema:
$ref: '#/components/schemas/MissionEventList'
'404':
description: Mission not found
content:
application/json:
schema:
$ref: '#/components/schemas/ProblemDetails'
components:
parameters:
AgentName:
name: agent
in: path
required: true
schema:
type: string
description: Agent name
TaskId:
name: task_id
in: path
required: true
schema:
type: string
format: uuid
description: Task UUID
MissionId:
name: mission_id
in: path
required: true
schema:
type: string
format: uuid
description: Mission UUID
WorkItemId:
name: work_item_id
in: path
required: true
schema:
type: string
format: uuid
description: Work item UUID
WatchId:
name: watch_id
in: path
required: true
schema:
type: string
format: uuid
description: Watch item UUID
schemas:
TownInfo:
type: object
properties:
name:
type: string
root:
type: string
redis_url:
type: string
TownStatus:
type: object
properties:
name:
type: string
root:
type: string
redis_url:
type: string
agent_count:
type: integer
agents:
type: array
items:
$ref: '#/components/schemas/AgentInfo'
AgentInfo:
type: object
properties:
id:
type: string
format: uuid
name:
type: string
cli:
type: string
state:
type: string
enum: [Idle, Working, Starting, Stopped, Error]
rounds_completed:
type: integer
tasks_completed:
type: integer
inbox_len:
type: integer
urgent_len:
type: integer
AgentList:
type: object
properties:
agents:
type: array
items:
$ref: '#/components/schemas/AgentInfo'
count:
type: integer
SpawnAgentRequest:
type: object
required: [name]
properties:
name:
type: string
cli:
type: string
SpawnAgentResponse:
type: object
properties:
agent_id:
type: string
name:
type: string
cli:
type: string
AgentActionResponse:
type: object
properties:
status:
type: string
agent:
type: string
PruneRequest:
type: object
properties:
all:
type: boolean
default: false
PruneResponse:
type: object
properties:
removed:
type: integer
agents:
type: array
items:
type: string
AssignTaskRequest:
type: object
required: [agent, task]
properties:
agent:
type: string
task:
type: string
AssignTaskResponse:
type: object
properties:
task_id:
type: string
agent_id:
type: string
agent_name:
type: string
PendingTaskList:
type: object
properties:
tasks:
type: array
items:
type: object
properties:
task_id:
type: string
description:
type: string
agent_id:
type: string
agent_name:
type: string
count:
type: integer
AddBacklogRequest:
type: object
required: [description]
properties:
description:
type: string
tags:
type: array
items:
type: string
AddBacklogResponse:
type: object
properties:
task_id:
type: string
description:
type: string
BacklogList:
type: object
properties:
backlog:
type: array
items:
type: object
properties:
task_id:
type: string
description:
type: string
tags:
type: array
items:
type: string
count:
type: integer
ClaimRequest:
type: object
required: [agent]
properties:
agent:
type: string
ClaimResponse:
type: object
properties:
task_id:
type: string
agent_id:
type: string
agent_name:
type: string
AssignAllRequest:
type: object
required: [agent]
properties:
agent:
type: string
AssignAllResponse:
type: object
properties:
assigned:
type: integer
tasks:
type: array
items:
type: string
RemoveBacklogResponse:
type: object
properties:
removed:
type: boolean
task_id:
type: string
SendMessageRequest:
type: object
required: [to, message]
properties:
to:
type: string
message:
type: string
from:
type: string
description: >
Optional sender. Accepts an agent name, agent UUID, or the
"supervisor"/"conductor" alias. When omitted the message is
attributed to the supervisor sentinel.
kind:
type: string
enum: [task, query, info, ack]
default: task
urgent:
type: boolean
default: false
SendMessageResponse:
type: object
properties:
message_id:
type: string
to_agent:
type: string
urgent:
type: boolean
InboxResponse:
type: object
properties:
agent:
type: string
total:
type: integer
urgent:
type: integer
messages:
type: array
items:
type: object
properties:
id:
type: string
from:
type: string
type:
type: string
summary:
type: string
RecoverResponse:
type: object
properties:
checked:
type: integer
recovered:
type: integer
agents:
type: array
items:
type: string
ReclaimRequest:
type: object
properties:
to_backlog:
type: boolean
default: false
to:
type: string
from:
type: string
ReclaimResponse:
type: object
properties:
reclaimed:
type: integer
destination:
type: string
ProblemDetails:
type: object
description: RFC 7807 Problem Details
properties:
type:
type: string
title:
type: string
status:
type: integer
detail:
type: string
MissionState:
type: string
enum: [planning, running, blocked, completed, failed]
description: |
Mission execution state:
- planning: Compiling work graph from objectives
- running: Active execution
- blocked: Waiting on external event
- completed: All objectives completed
- failed: Unrecoverable error
WorkKind:
type: string
enum: [design, implement, test, review, merge_gate, followup]
description: |
Type of work item:
- design: Design/planning work
- implement: Implementation work
- test: Testing work
- review: Code review
- merge_gate: Waiting for approval
- followup: Bug fixes, improvements
WorkStatus:
type: string
enum: [pending, ready, assigned, running, blocked, done]
description: |
Work item execution status:
- pending: Dependencies not satisfied
- ready: Can be assigned (dependencies done)
- assigned: Agent selected, not yet started
- running: In progress
- blocked: Waiting on fix/external
- done: Completed successfully
WatchKind:
type: string
enum: [pr_checks, bugbot_comments, review_comments, mergeability]
description: |
Type of watch item:
- pr_checks: Monitor PR CI checks
- bugbot_comments: Monitor Bugbot comments
- review_comments: Monitor review comments
- mergeability: Monitor PR mergeability
WatchStatus:
type: string
enum: [active, snoozed, done]
description: |
Watch item status:
- active: Actively being monitored
- snoozed: Temporarily paused
- done: Monitoring complete
TriggerAction:
type: string
enum: [create_fix_task, notify_reviewer, advance_pipeline]
description: Action to take when watch triggers
ObjectiveRef:
type: object
description: Reference to an objective (issue or document)
oneOf:
- type: object
title: Issue
required: [type, owner, repo, number]
properties:
type:
type: string
const: issue
owner:
type: string
description: Repository owner
repo:
type: string
description: Repository name
number:
type: integer
description: Issue number
- type: object
title: Doc
required: [type, path]
properties:
type:
type: string
const: doc
path:
type: string
description: Path to document
MissionPolicy:
type: object
description: Execution policy for a mission
properties:
max_parallel_items:
type: integer
default: 2
description: Maximum parallel work items
reviewer_required:
type: boolean
default: true
description: Reviewer required for implement/test items
auto_merge:
type: boolean
default: false
description: Auto-merge PRs when approved
watch_interval_secs:
type: integer
default: 180
description: Watch interval in seconds
MissionSummary:
type: object
description: Summary of a mission for list views
properties:
id:
type: string
format: uuid
state:
$ref: '#/components/schemas/MissionState'
objective_count:
type: integer
description: Number of objectives in the mission
work_item_count:
type: integer
description: Total work items
completed_count:
type: integer
description: Completed work items
created_at:
type: string
format: date-time
updated_at:
type: string
format: date-time
MissionRun:
type: object
description: Full mission orchestration record
properties:
id:
type: string
format: uuid
objective_refs:
type: array
items:
$ref: '#/components/schemas/ObjectiveRef'
state:
$ref: '#/components/schemas/MissionState'
policy:
$ref: '#/components/schemas/MissionPolicy'
created_at:
type: string
format: date-time
updated_at:
type: string
format: date-time
next_wake_at:
type: string
format: date-time
nullable: true
blocked_reason:
type: string
nullable: true
WorkItem:
type: object
description: Individual work unit in the mission DAG
properties:
id:
type: string
format: uuid
mission_id:
type: string
format: uuid
title:
type: string
kind:
$ref: '#/components/schemas/WorkKind'
depends_on:
type: array
items:
type: string
format: uuid
description: Work item IDs this depends on
owner_role:
type: string
nullable: true
description: Preferred agent role
status:
$ref: '#/components/schemas/WorkStatus'
assigned_to:
type: string
format: uuid
nullable: true
description: Assigned agent ID
artifact_refs:
type: array
items:
type: string
description: PR URLs, commit SHAs
source_ref:
type: string
nullable: true
description: Source objective reference
created_at:
type: string
format: date-time
updated_at:
type: string
format: date-time
WatchItem:
type: object
description: PR/CI monitoring task
properties:
id:
type: string
format: uuid
mission_id:
type: string
format: uuid
work_item_id:
type: string
format: uuid
kind:
$ref: '#/components/schemas/WatchKind'
target_ref:
type: string
description: Target reference (PR URL, number)
interval_secs:
type: integer
description: Check interval in seconds
next_due_at:
type: string
format: date-time
status:
$ref: '#/components/schemas/WatchStatus'
on_trigger:
$ref: '#/components/schemas/TriggerAction'
last_check_at:
type: string
format: date-time
nullable: true
consecutive_failures:
type: integer
MissionList:
type: object
properties:
missions:
type: array
items:
$ref: '#/components/schemas/MissionSummary'
count:
type: integer
StartMissionRequest:
type: object
required: [objectives]
properties:
objectives:
type: array
minItems: 1
items:
$ref: '#/components/schemas/ObjectiveRef'
description: Issues or documents to process
policy:
$ref: '#/components/schemas/MissionPolicy'
StartMissionResponse:
type: object
properties:
mission_id:
type: string
format: uuid
state:
$ref: '#/components/schemas/MissionState'
objective_count:
type: integer
MissionStatus:
type: object
properties:
mission:
$ref: '#/components/schemas/MissionRun'
work_items:
type: array
items:
$ref: '#/components/schemas/WorkItem'
description: Included if include_work=true
watches:
type: array
items:
$ref: '#/components/schemas/WatchItem'
description: Included if include_watches=true
events:
type: array
items:
type: string
description: Included if include_events=true
summary:
type: object
properties:
total_work_items:
type: integer
pending:
type: integer
ready:
type: integer
running:
type: integer
done:
type: integer
blocked:
type: integer
active_watches:
type: integer
MissionActionResponse:
type: object
properties:
mission_id:
type: string
format: uuid
status:
type: string
previous_state:
$ref: '#/components/schemas/MissionState'
new_state:
$ref: '#/components/schemas/MissionState'
StopMissionRequest:
type: object
properties:
force:
type: boolean
default: false
description: Force stop without graceful cleanup
DeleteMissionResponse:
type: object
properties:
mission_id:
type: string
format: uuid
deleted:
type: boolean
WorkItemList:
type: object
properties:
mission_id:
type: string
format: uuid
work_items:
type: array
items:
$ref: '#/components/schemas/WorkItem'
count:
type: integer
UpdateWorkItemRequest:
type: object
properties:
status:
$ref: '#/components/schemas/WorkStatus'
artifacts:
type: array
items:
type: string
description: Artifact references to add (PR URLs, commits)
WatchItemList:
type: object
properties:
mission_id:
type: string
format: uuid
watches:
type: array
items:
$ref: '#/components/schemas/WatchItem'
count:
type: integer
SnoozeWatchRequest:
type: object
required: [duration_secs]
properties:
duration_secs:
type: integer
minimum: 60
description: Duration to snooze in seconds
MissionEventList:
type: object
properties:
mission_id:
type: string
format: uuid
events:
type: array
items:
type: string
description: Timestamped event messages
count:
type: integer