openapi: 3.1.0
info:
title: Conflux Web Monitoring API
version: 1.0.0
description: |
REST API and WebSocket interface for monitoring Conflux orchestrator state.
This API provides access to changes, orchestrator state, and real-time updates.
servers:
- url: http://localhost:8080
description: Local development server
paths:
/api/health:
get:
summary: Health check endpoint
description: Returns the health status and version of the orchestrator
operationId: getHealth
responses:
'200':
description: Successful health check
content:
application/json:
schema:
$ref: '#/components/schemas/HealthResponse'
example:
status: ok
version: v0.1.0 (12345)
/api/state:
get:
summary: Get full orchestrator state
description: |
Returns the complete orchestrator state including all changes, logs, worktrees, and app mode.
The response includes Cache-Control: no-store header to prevent caching.
operationId: getState
responses:
'200':
description: Successful state retrieval
headers:
Cache-Control:
description: Cache control directive
schema:
type: string
example: no-store
content:
application/json:
schema:
$ref: '#/components/schemas/OrchestratorState'
/api/changes:
get:
summary: List all changes
description: Returns a list of all changes with their current status and progress
operationId: listChanges
responses:
'200':
description: Successful retrieval of changes list
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/ChangeStatus'
/api/changes/{id}:
get:
summary: Get a specific change by ID
description: Returns detailed information about a specific change
operationId: getChange
parameters:
- name: id
in: path
required: true
description: The unique identifier of the change
schema:
type: string
example: add-web-api-openapi-docs
responses:
'200':
description: Successful retrieval of change
content:
application/json:
schema:
$ref: '#/components/schemas/ChangeStatus'
'404':
description: Change not found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
error: "Change 'nonexistent-id' not found"
/api/changes/{id}/approve:
post:
summary: Approve a change
description: |
Marks a change as approved and broadcasts the update to WebSocket clients.
The approval status is persisted to disk.
operationId: approveChange
parameters:
- name: id
in: path
required: true
description: The unique identifier of the change to approve
schema:
type: string
example: add-web-api-openapi-docs
responses:
'200':
description: Change successfully approved
content:
application/json:
schema:
$ref: '#/components/schemas/ChangeStatus'
'404':
description: Change not found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
error: "Change 'nonexistent-id' not found"
'500':
description: Internal server error during approval
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
error: "Failed to approve change: IO error"
/api/changes/{id}/unapprove:
post:
summary: Unapprove a change
description: |
Removes the approval status from a change and broadcasts the update to WebSocket clients.
The approval status is persisted to disk.
operationId: unapproveChange
parameters:
- name: id
in: path
required: true
description: The unique identifier of the change to unapprove
schema:
type: string
example: add-web-api-openapi-docs
responses:
'200':
description: Change successfully unapproved
content:
application/json:
schema:
$ref: '#/components/schemas/ChangeStatus'
'404':
description: Change not found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
error: "Change 'nonexistent-id' not found"
'500':
description: Internal server error during unapproval
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
error: "Failed to unapprove change: IO error"
/api/control/start:
post:
summary: Start or resume processing
description: |
Initiates processing of selected changes or resumes from stopped state.
Returns 409 Conflict if already running or stopping.
operationId: controlStart
responses:
'200':
description: Processing started successfully
content:
application/json:
schema:
$ref: '#/components/schemas/ControlResponse'
example:
success: true
message: "Processing started"
'409':
description: Cannot start (already running or stopping)
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
error: "Cannot start: already running"
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
error: "Failed to start processing: control channel not available"
/api/control/stop:
post:
summary: Stop processing (graceful shutdown)
description: |
Initiates graceful stop of processing. Current change will complete before stopping.
Returns 409 Conflict if not running.
operationId: controlStop
responses:
'200':
description: Stop initiated successfully
content:
application/json:
schema:
$ref: '#/components/schemas/ControlResponse'
example:
success: true
message: "Stopping after current change completes..."
'409':
description: Cannot stop (not running)
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
error: "Cannot stop: not running (current mode: select)"
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
/api/control/cancel-stop:
post:
summary: Cancel a pending stop request
description: |
Cancels a graceful stop request and continues processing.
Returns 409 Conflict if not in stopping mode.
operationId: controlCancelStop
responses:
'200':
description: Stop canceled successfully
content:
application/json:
schema:
$ref: '#/components/schemas/ControlResponse'
example:
success: true
message: "Stop canceled, continuing..."
'409':
description: Cannot cancel stop (not stopping)
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
error: "Cannot cancel stop: not stopping (current mode: running)"
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
/api/control/force-stop:
post:
summary: Force stop immediately
description: |
Immediately terminates processing without waiting for current change to complete.
Returns 409 Conflict if not running or stopping.
operationId: controlForceStop
responses:
'200':
description: Force stop initiated successfully
content:
application/json:
schema:
$ref: '#/components/schemas/ControlResponse'
example:
success: true
message: "Force stopping..."
'409':
description: Cannot force stop (not running or stopping)
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
error: "Cannot force stop: not running or stopping (current mode: select)"
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
/api/control/retry:
post:
summary: Retry error changes
description: |
Retries changes that failed with errors. Resets error changes to queued and starts processing.
Returns 409 Conflict if not in error mode.
operationId: controlRetry
responses:
'200':
description: Retry initiated successfully
content:
application/json:
schema:
$ref: '#/components/schemas/ControlResponse'
example:
success: true
message: "Retrying error changes..."
'409':
description: Cannot retry (not in error mode)
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
error: "Cannot retry: not in error mode (current mode: select)"
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
/ws:
get:
summary: WebSocket endpoint for real-time updates
description: |
WebSocket connection for receiving real-time state updates.
The WebSocket sends InitialState on connection and StateUpdate messages on state changes.
operationId: websocketConnection
x-websocket: true
x-websocket-messages:
send:
- name: InitialState
description: Initial state sent immediately after WebSocket connection
schema:
$ref: '#/components/schemas/StateUpdate'
- name: StateUpdate
description: State update broadcast when changes occur
schema:
$ref: '#/components/schemas/StateUpdate'
responses:
'101':
description: WebSocket connection established
'400':
description: Invalid WebSocket upgrade request
components:
schemas:
HealthResponse:
type: object
description: Health check response containing service status and version
required:
- status
- version
properties:
status:
type: string
description: Health status of the service
enum:
- ok
example: ok
version:
type: string
description: Version string including build number
example: v0.1.0 (12345)
ErrorResponse:
type: object
description: Error response for API errors
required:
- error
properties:
error:
type: string
description: Human-readable error message
example: "Change 'my-change' not found"
ControlResponse:
type: object
description: Response for control operations (start/stop/retry)
required:
- success
- message
properties:
success:
type: boolean
description: Whether the operation was successful
example: true
message:
type: string
description: Human-readable status message
example: "Processing started"
ChangeStatus:
type: object
description: Status and progress information for a change
required:
- id
- completed_tasks
- total_tasks
- progress_percent
- status
- is_approved
- dependencies
properties:
id:
type: string
description: Unique identifier for the change
example: add-web-api-openapi-docs
completed_tasks:
type: integer
description: Number of completed tasks
minimum: 0
example: 3
total_tasks:
type: integer
description: Total number of tasks
minimum: 0
example: 5
progress_percent:
type: number
format: float
description: Progress percentage (0-100)
minimum: 0
maximum: 100
example: 60.0
status:
type: string
description: Current status of the change
enum:
- pending
- in_progress
- complete
- error
- archived
example: in_progress
is_approved:
type: boolean
description: Whether the change is approved
example: true
dependencies:
type: array
description: List of change IDs that this change depends on
items:
type: string
example:
- other-change-id
queue_status:
type: string
description: |
Queue status for parallel/serial execution tracking.
Aligned with TUI QueueStatus display values.
nullable: true
enum:
- not queued
- queued
- processing
- completed
- archiving
- archived
- merged
- merge wait
- resolving
- error
example: processing
iteration_number:
type: integer
description: Current iteration number for apply/archive loops
nullable: true
minimum: 1
example: 2
OrchestratorState:
type: object
description: Complete orchestrator state including changes, logs, worktrees, and app mode
required:
- changes
- total_changes
- completed_changes
- in_progress_changes
- pending_changes
- last_updated
- logs
- worktrees
- app_mode
properties:
changes:
type: array
description: List of all changes with their status
items:
$ref: '#/components/schemas/ChangeStatus'
total_changes:
type: integer
description: Total number of changes
minimum: 0
example: 10
completed_changes:
type: integer
description: Number of completed changes
minimum: 0
example: 3
in_progress_changes:
type: integer
description: Number of in-progress changes
minimum: 0
example: 2
pending_changes:
type: integer
description: Number of pending changes
minimum: 0
example: 5
last_updated:
type: string
format: date-time
description: ISO 8601 timestamp of last update
example: "2024-01-19T12:34:56.789Z"
logs:
type: array
description: Log entries (TUI-equivalent)
items:
$ref: '#/components/schemas/LogEntry'
worktrees:
type: array
description: Worktree list (TUI-equivalent)
items:
$ref: '#/components/schemas/WorktreeInfo'
app_mode:
type: string
description: |
Application mode indicating current execution state.
- select: Initial state, ready to start processing
- running: Processing changes
- stopping: Graceful stop initiated, waiting for current change to complete
- stopped: Processing stopped, can be resumed
- error: Error occurred during processing
enum:
- select
- running
- stopping
- stopped
- error
example: select
StateUpdate:
type: object
description: State update message sent to WebSocket clients
required:
- type
- timestamp
- changes
properties:
type:
type: string
description: Type of update message
enum:
- state_update
example: state_update
timestamp:
type: string
format: date-time
description: ISO 8601 timestamp of the update
example: "2024-01-19T12:34:56.789Z"
changes:
type: array
description: List of changes with current status
items:
$ref: '#/components/schemas/ChangeStatus'
logs:
type: array
description: Log entries (optional, sent with log events)
nullable: true
items:
$ref: '#/components/schemas/LogEntry'
worktrees:
type: array
description: Worktree list (optional, sent with worktree refresh events)
nullable: true
items:
$ref: '#/components/schemas/WorktreeInfo'
app_mode:
type: string
description: Application mode (optional, sent with mode change events)
nullable: true
enum:
- select
- running
- stopping
- stopped
- error
example: running
LogEntry:
type: object
description: Log entry for execution events
required:
- timestamp
- level
- message
properties:
timestamp:
type: string
format: date-time
description: ISO 8601 timestamp of the log entry
example: "2024-01-19T12:34:56.789Z"
level:
type: string
description: Log level
enum:
- debug
- info
- warn
- error
example: info
message:
type: string
description: Log message content
example: "Processing change: add-web-api-openapi-docs"
change_id:
type: string
description: Associated change ID (optional)
nullable: true
example: add-web-api-openapi-docs
WorktreeInfo:
type: object
description: Git worktree information
required:
- path
- branch
- is_main
properties:
path:
type: string
description: Absolute path to the worktree
example: /Users/user/worktrees/my-change
branch:
type: string
description: Branch name associated with the worktree
nullable: true
example: ws-session-1234567890
is_main:
type: boolean
description: Whether this is the main worktree
example: false
is_detached:
type: boolean
description: Whether the worktree is in detached HEAD state
example: false
conflict_count:
type: integer
description: Number of merge conflicts (optional)
nullable: true
minimum: 0
example: 0