openapi: 3.1.0
info:
title: Conflux Web Monitoring API
description: REST API for monitoring and controlling Conflux orchestration
contact:
name: Conflux
url: https://github.com/anomalyco/conflux
license:
name: MIT
identifier: MIT
version: 0.5.44
paths:
/api/changes:
get:
tags:
- changes
summary: List all changes
operationId: list_changes
responses:
'200':
description: List of all changes
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/ChangeStatus'
/api/changes/{id}:
get:
tags:
- changes
summary: Get a specific change by ID
operationId: get_change
parameters:
- name: id
in: path
description: Change ID
required: true
schema:
type: string
responses:
'200':
description: Change found
content:
application/json:
schema:
$ref: '#/components/schemas/ChangeStatus'
'404':
description: Change not found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
/api/control/cancel-stop:
post:
tags:
- control
summary: Cancel a pending stop request
description: |-
# Endpoint
POST /api/control/cancel-stop
# Returns
- 200 OK if stop is canceled
- 409 Conflict if not in stopping mode
- 500 Internal Server Error if control channel not available
operationId: control_cancel_stop
responses:
'200':
description: Stop canceled
content:
application/json:
schema:
$ref: '#/components/schemas/ControlResponse'
'409':
description: Not in stopping mode
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: Control channel error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
/api/control/force-stop:
post:
tags:
- control
summary: Force stop immediately
description: |-
# Endpoint
POST /api/control/force-stop
# Returns
- 200 OK if force stop is initiated
- 409 Conflict if not running or stopping
- 500 Internal Server Error if control channel not available
operationId: control_force_stop
responses:
'200':
description: Force stop initiated
content:
application/json:
schema:
$ref: '#/components/schemas/ControlResponse'
'409':
description: Not running or stopping
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: Control channel error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
/api/control/retry:
post:
tags:
- control
summary: Retry error changes
description: |-
# Endpoint
POST /api/control/retry
# Returns
- 200 OK if retry is initiated
- 409 Conflict if not in error mode
- 500 Internal Server Error if control channel not available
operationId: control_retry
responses:
'200':
description: Retry initiated
content:
application/json:
schema:
$ref: '#/components/schemas/ControlResponse'
'409':
description: Not in error mode
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: Control channel error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
/api/control/start:
post:
tags:
- control
summary: Start or resume processing
description: |-
# Endpoint
POST /api/control/start
# Returns
- 200 OK if start/resume is successful
- 409 Conflict if already running or stopping
- 500 Internal Server Error if control channel not available
operationId: control_start
responses:
'200':
description: Processing started
content:
application/json:
schema:
$ref: '#/components/schemas/ControlResponse'
'409':
description: Already running or stopping
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: Control channel error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
/api/control/stop:
post:
tags:
- control
summary: Stop processing (graceful shutdown)
description: |-
# Endpoint
POST /api/control/stop
# Returns
- 200 OK if stop is initiated
- 409 Conflict if not running
- 500 Internal Server Error if control channel not available
operationId: control_stop
responses:
'200':
description: Stop initiated
content:
application/json:
schema:
$ref: '#/components/schemas/ControlResponse'
'409':
description: Not running
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: Control channel error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
/api/health:
get:
tags:
- health
summary: Health check endpoint
operationId: health
responses:
'200':
description: Health check successful
content:
application/json:
schema:
$ref: '#/components/schemas/HealthResponse'
/api/state:
get:
tags:
- state
summary: Get full orchestrator state
operationId: get_state
responses:
'200':
description: Current orchestrator state
content:
application/json:
schema:
$ref: '#/components/schemas/OrchestratorStateSnapshot'
/api/v1/stats/overview:
get:
tags:
- state
summary: Get aggregated orchestration statistics
operationId: get_stats_overview
responses:
'200':
description: Aggregated success/failure counts and average duration
content:
application/json:
schema:
$ref: '#/components/schemas/StatsOverviewResponse'
'503':
description: Server database is not enabled
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
/api/v1/stats/projects/{id}/history:
get:
tags:
- state
summary: Get recent change event history for a project
operationId: get_project_history
parameters:
- name: id
in: path
description: Project ID
required: true
schema:
type: string
- name: limit
in: query
required: false
schema:
type: integer
minimum: 1
maximum: 1000
default: 100
responses:
'200':
description: Recent persisted change events
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/ChangeEventRow'
'404':
description: Project not found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'503':
description: Server database is not enabled
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
/api/v1/logs:
get:
tags:
- state
summary: Query persisted server logs
operationId: get_logs
parameters:
- name: limit
in: query
required: false
schema:
type: integer
minimum: 1
maximum: 1000
default: 100
- name: before
in: query
required: false
schema:
type: string
description: ISO-8601 timestamp upper bound
- name: project_id
in: query
required: false
schema:
type: string
responses:
'200':
description: Persisted logs
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/LogEntryRow'
'503':
description: Server database is not enabled
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
/ws:
get:
tags:
- websocket
summary: WebSocket connection handler for real-time state updates
description: |-
This endpoint upgrades the HTTP connection to a WebSocket connection
and streams state updates to the client in real-time.
# Protocol
- Upon connection, the server sends an initial state message
- Subsequently, the server broadcasts state updates as they occur
- The client can send ping frames to keep the connection alive
- The server responds with pong frames automatically
# Message Format
All messages are JSON-encoded with the following structure:
```json
{
"type": "initial_state" | "state_update",
"timestamp": "ISO 8601 timestamp",
"state": { ... } // OrchestratorStateSnapshot
}
```
operationId: ws_handler
responses:
'101':
description: Switching Protocols - WebSocket connection established
'400':
description: Bad Request - Not a valid WebSocket upgrade request
components:
schemas:
ChangeStatus:
type: object
description: Change status for WebSocket updates
required:
- id
- completed_tasks
- total_tasks
- progress_percent
- status
- dependencies
properties:
completed_tasks:
type: integer
format: int32
description: Number of completed tasks
minimum: 0
dependencies:
type: array
items:
type: string
description: Dependencies on other changes
id:
type: string
description: Change ID
iteration_number:
type:
- integer
- 'null'
format: int32
description: Current iteration number for apply/archive loops
minimum: 0
progress_percent:
type: number
format: float
description: Progress percentage (0-100)
queue_status:
type:
- string
- 'null'
description: |-
Queue status (for parallel/serial execution tracking)
Aligned with TUI QueueStatus display values: "not queued", "queued", "blocked", "processing",
"accepting", "archiving", "archived", "merged", "merge wait", "resolving", "resolve pending", "error"
status:
type: string
description: 'Current status: "pending", "in_progress", "complete"'
total_tasks:
type: integer
format: int32
description: Total number of tasks
minimum: 0
ControlResponse:
type: object
description: Success response for control operations
required:
- success
- message
properties:
message:
type: string
success:
type: boolean
ErrorResponse:
type: object
description: Error response for API errors
required:
- error
properties:
error:
type: string
HealthResponse:
type: object
description: Health check response
required:
- status
- version
properties:
status:
type: string
version:
type: string
LogEntry:
type: object
description: Log entry for the TUI
required:
- timestamp
- created_at
- message
- level
properties:
change_id:
type:
- string
- 'null'
description: Optional change_id for parallel mode logs
created_at:
type: string
format: date-time
description: Creation time (actual timestamp for relative time calculation)
iteration:
type:
- integer
- 'null'
format: int32
description: Optional iteration number (for apply operations)
minimum: 0
level:
$ref: '#/components/schemas/LogLevel'
description: Log level
message:
type: string
description: Log message
operation:
type:
- string
- 'null'
description: Optional operation type (apply, archive, resolve)
timestamp:
type: string
description: Timestamp (formatted for display)
workspace_path:
type:
- string
- 'null'
description: Optional workspace path (for parallel mode logs with workspace context)
LogLevel:
type: string
description: Log level for TUI logs
enum:
- info
- success
- warn
- error
MergeConflictInfo:
type: object
description: Merge conflict information for a worktree
required:
- conflict_files
properties:
conflict_files:
type: array
items:
type: string
description: List of files with merge conflicts
ChangeEventRow:
type: object
required:
- id
- project_id
- change_id
- operation
- attempt
- success
- duration_ms
- created_at
properties:
attempt:
type: integer
format: int64
change_id:
type: string
commit_hash:
type:
- string
- 'null'
continuation_reason:
type:
- string
- 'null'
created_at:
type: string
duration_ms:
type: integer
format: int64
error:
type:
- string
- 'null'
exit_code:
type:
- integer
- 'null'
format: int64
findings:
type:
- string
- 'null'
id:
type: integer
format: int64
operation:
type: string
project_id:
type: string
run_id:
type:
- integer
- 'null'
format: int64
stderr_tail:
type:
- string
- 'null'
stdout_tail:
type:
- string
- 'null'
success:
type: boolean
verification_result:
type:
- string
- 'null'
LogEntryRow:
type: object
required:
- id
- level
- message
- created_at
properties:
change_id:
type:
- string
- 'null'
created_at:
type: string
id:
type: integer
format: int64
iteration:
type:
- integer
- 'null'
format: int64
level:
type: string
message:
type: string
operation:
type:
- string
- 'null'
project_id:
type:
- string
- 'null'
StatsOverviewResponse:
type: object
required:
- success_count
- failure_count
- average_duration_ms
properties:
average_duration_ms:
type: number
format: double
failure_count:
type: integer
format: int64
success_count:
type: integer
format: int64
OrchestratorStateSnapshot:
type: object
description: Full orchestrator state snapshot for REST API
required:
- changes
- total_changes
- completed_changes
- in_progress_changes
- pending_changes
- last_updated
- logs
- worktrees
- app_mode
- is_resolving
properties:
app_mode:
type: string
description: Application mode (e.g., "select", "running", "stopped")
changes:
type: array
items:
$ref: '#/components/schemas/ChangeStatus'
description: List of all changes
completed_changes:
type: integer
description: Number of completed changes
minimum: 0
in_progress_changes:
type: integer
description: Number of in-progress changes
minimum: 0
is_resolving:
type: boolean
description: Whether resolve is currently running
last_updated:
type: string
description: Timestamp of last update
logs:
type: array
items:
$ref: '#/components/schemas/LogEntry'
description: Log entries (TUI-equivalent)
pending_changes:
type: integer
description: Number of pending changes
minimum: 0
total_changes:
type: integer
description: Total number of changes
minimum: 0
worktrees:
type: array
items:
$ref: '#/components/schemas/WorktreeInfo'
description: Worktree list (TUI-equivalent)
StateUpdate:
type: object
description: State update message sent to WebSocket clients
required:
- type
- timestamp
- changes
properties:
app_mode:
type:
- string
- 'null'
description: Application mode (optional, sent with mode change events)
changes:
type: array
items:
$ref: '#/components/schemas/ChangeStatus'
description: List of changes with current status
logs:
type:
- array
- 'null'
items:
$ref: '#/components/schemas/LogEntry'
description: Log entries (optional, sent with log events)
timestamp:
type: string
description: ISO 8601 timestamp
type:
type: string
description: Type of update message
worktrees:
type:
- array
- 'null'
items:
$ref: '#/components/schemas/WorktreeInfo'
description: Worktree list (optional, sent with worktree refresh events)
WorktreeInfo:
type: object
description: Information about a git worktree
required:
- path
- head
- branch
- is_detached
- is_main
- has_commits_ahead
- is_merging
properties:
branch:
type: string
description: Branch name (empty if detached)
has_commits_ahead:
type: boolean
description: Whether this worktree has commits ahead of the base branch
head:
type: string
description: Current HEAD commit (short hash or symbolic ref)
is_detached:
type: boolean
description: Whether HEAD is detached
is_main:
type: boolean
description: Whether this is the main worktree
is_merging:
type: boolean
description: Whether a merge operation is in progress for this worktree
merge_conflict:
oneOf:
- type: 'null'
- $ref: '#/components/schemas/MergeConflictInfo'
description: Merge conflict information (None if not checked or no conflicts)
path:
type: string
description: Path to the worktree
tags:
- name: health
description: Health check endpoints
- name: state
description: State management endpoints
- name: changes
description: Change management endpoints
- name: control
description: Orchestrator control endpoints
- name: websocket
description: WebSocket endpoints for real-time updates