Sovereign Agent BFF — FSM Worker Command Plane — OpenAPI 1.0.0

Scope: The published reference for Sovereign Agent BFF — FSM Worker Command Plane. 6 paths — the measured spec-vs-implementation coverage lives in the complete API inventory. Status: rendered 2026-11-09 from the OpenAPI source for Sovereign Agent BFF — FSM Worker Command Plane — regenerate with node scripts/render-platform-map-api-docs.mjs. See also: the OpenAPI spec index.

Servers

URL	Notes
http://127.0.0.1:3030

Tag	Summary
fsm	FSM worker control API

Paths — 6 paths / 6 operations

Method	Path	Operation ID	Summary
GET	/v1/fsm/status	getFsmStatus	Aggregate FSM worker + command queue status
GET	/v1/fsm/execution-mode	getFsmExecutionMode	Current inline vs enqueue execution mode
GET	/v1/fsm/commands	listFsmCommands	List fsm_command_log rows
GET	/v1/fsm/commands/{commandId}	getFsmCommand	Get command by id
POST	/v1/fsm/history/export	exportFsmHistory	Archive binding history and file_claim sealed bundle
POST	/v1/pipeline/instances/{bindingId}/transition	pipelineTransition	Execute or enqueue pipeline transition

Operations

GET /v1/fsm/status

Summary: Aggregate FSM worker + command queue status

Tags: fsm Operation ID: getFsmStatus Responses:

Status	Meaning
200	Status snapshot

GET /v1/fsm/execution-mode

Summary: Current inline vs enqueue execution mode

Tags: fsm Operation ID: getFsmExecutionMode Responses:

Status	Meaning
200	Mode

GET /v1/fsm/commands

Summary: List fsm_command_log rows

Tags: fsm Operation ID: listFsmCommands

Parameters:

Name	In	Required	Type	Notes
status	query	no	string enum: pending, completed, failed
limit	query	no	int

Responses:

Status	Meaning
200	Command list

GET /v1/fsm/commands/{commandId}

Summary: Get command by id

Tags: fsm Operation ID: getFsmCommand

Parameters:

Name	In	Required	Type	Notes
commandId	path	yes	string

Responses:

Status	Meaning
200	Command row
404	Not found

POST /v1/fsm/history/export

Summary: Archive binding history and file_claim sealed bundle

Tags: fsm Operation ID: exportFsmHistory Request body:

Content type: application/json

Field	Type	Notes
binding_id	string
vault_id	string

Responses:

Status	Meaning
201	Export + vault claim

POST /v1/pipeline/instances/{bindingId}/transition

Summary: Execute or enqueue pipeline transition

Tags: fsm Operation ID: pipelineTransition

Parameters:

Name	In	Required	Type	Notes
bindingId	path	yes	string

Responses:

Status	Meaning
200	Inline execution result
202	Enqueued to fsm-worker

Full specification — verbatim source of truth

{
  "openapi": "3.1.0",
  "info": {
    "title": "Sovereign Agent BFF — FSM Worker Command Plane",
    "version": "1.0.0",
    "description": "FSM-24 — JetStream command plane for pipeline/worker execution. State in SurrealDB; hooks on fsm-worker."
  },
  "servers": [
    {
      "url": "http://127.0.0.1:3030"
    }
  ],
  "tags": [
    {
      "name": "fsm",
      "description": "FSM worker control API"
    }
  ],
  "paths": {
    "/v1/fsm/status": {
      "get": {
        "tags": [
          "fsm"
        ],
        "summary": "Aggregate FSM worker + command queue status",
        "operationId": "getFsmStatus",
        "responses": {
          "200": {
            "description": "Status snapshot"
          }
        }
      }
    },
    "/v1/fsm/execution-mode": {
      "get": {
        "tags": [
          "fsm"
        ],
        "summary": "Current inline vs enqueue execution mode",
        "operationId": "getFsmExecutionMode",
        "responses": {
          "200": {
            "description": "Mode"
          }
        }
      }
    },
    "/v1/fsm/commands": {
      "get": {
        "tags": [
          "fsm"
        ],
        "summary": "List fsm_command_log rows",
        "operationId": "listFsmCommands",
        "parameters": [
          {
            "name": "status",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "pending",
                "completed",
                "failed"
              ]
            }
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 50
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Command list"
          }
        }
      }
    },
    "/v1/fsm/commands/{commandId}": {
      "get": {
        "tags": [
          "fsm"
        ],
        "summary": "Get command by id",
        "operationId": "getFsmCommand",
        "parameters": [
          {
            "name": "commandId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Command row"
          },
          "404": {
            "description": "Not found"
          }
        }
      }
    },
    "/v1/fsm/history/export": {
      "post": {
        "tags": [
          "fsm"
        ],
        "summary": "Archive binding history and file_claim sealed bundle",
        "operationId": "exportFsmHistory",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "binding_id",
                  "vault_id"
                ],
                "properties": {
                  "binding_id": {
                    "type": "string"
                  },
                  "vault_id": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Export + vault claim"
          }
        }
      }
    },
    "/v1/pipeline/instances/{bindingId}/transition": {
      "post": {
        "tags": [
          "fsm"
        ],
        "summary": "Execute or enqueue pipeline transition",
        "operationId": "pipelineTransition",
        "parameters": [
          {
            "name": "bindingId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Inline execution result"
          },
          "202": {
            "description": "Enqueued to fsm-worker"
          }
        }
      }
    }
  },
  "x-nats-subjects": {
    "fsm.v1.command.start": "Start pipeline binding",
    "fsm.v1.command.transition": "Run transition hooks",
    "fsm.v1.command.resume": "Resume from checkpoint",
    "fsm.v1.event.completed": "Worker success",
    "fsm.v1.event.failed": "Worker failure"
  }
}