OpenAPI Specification
openapi: 3.1.0
info:
description: Workflow management API for B3OS
title: B3OS Workflow Action Runs API
version: '1.0'
tags:
- name: Runs
paths:
/v1/runs:
get:
description: List all runs
parameters:
- description: Number of items (default 20, max 100)
in: query
name: limit
schema:
type: integer
- description: Offset for pagination (default 0)
in: query
name: offset
schema:
type: integer
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/ListRunsSuccessResponse'
description: OK
tags:
- Runs
post:
description: Execute an inline workflow definition (ephemeral run). The definition must use "manual" trigger type. No workflow is saved — the definition is executed once and the run is recorded with workflowId="". Requires WorkflowCreate permission.
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/EphemeralRunParams'
description: Inline workflow definition and optional payload/props
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/RunSuccessResponse'
description: Run created and enqueued for execution
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/github_com_b3-fun_b3-mono_services_b3os-workflow_internal_app_api_http.ErrorResponse'
description: Invalid definition (400228), non-manual trigger (400229), invalid run ID (400078), or duplicate run ID (400079)
'402':
content:
application/json:
schema:
$ref: '#/components/schemas/github_com_b3-fun_b3-mono_services_b3os-workflow_internal_app_api_http.ErrorResponse'
description: Insufficient CU balance
'403':
content:
application/json:
schema:
$ref: '#/components/schemas/github_com_b3-fun_b3-mono_services_b3os-workflow_internal_app_api_http.ErrorResponse'
description: Missing org context or insufficient permissions
tags:
- Runs
/v1/runs/{id}:
get:
description: Get a specific run by ID
parameters:
- description: Run ID
in: path
name: id
required: true
schema:
type: string
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/GetRunSuccessResponse'
description: OK
'404':
content:
application/json:
schema:
$ref: '#/components/schemas/github_com_b3-fun_b3-mono_services_b3os-workflow_internal_app_api_http.ErrorResponse'
description: Not Found
tags:
- Runs
/v1/runs/{id}/cancel:
post:
description: Cancel a running or waiting run
parameters:
- description: Run ID
in: path
name: id
required: true
schema:
type: string
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/GetRunSuccessResponse'
description: OK
'404':
content:
application/json:
schema:
$ref: '#/components/schemas/github_com_b3-fun_b3-mono_services_b3os-workflow_internal_app_api_http.ErrorResponse'
description: Not Found
'409':
content:
application/json:
schema:
$ref: '#/components/schemas/github_com_b3-fun_b3-mono_services_b3os-workflow_internal_app_api_http.ErrorResponse'
description: Conflict
tags:
- Runs
/v1/runs/{id}/stream:
get:
description: SSE endpoint for real-time run status updates. Clients MUST subscribe BEFORE triggering the run to avoid missing the initial run_started event. Use pre-subscription with client-provided runId.
parameters:
- description: Run ID
in: path
name: id
required: true
schema:
type: string
responses:
'200':
content:
text/event-stream:
schema:
type: string
description: SSE stream with run events
'400':
content:
text/event-stream:
schema:
$ref: '#/components/schemas/github_com_b3-fun_b3-mono_services_b3os-workflow_internal_app_api_http.ErrorResponse'
description: Bad Request
'403':
content:
text/event-stream:
schema:
$ref: '#/components/schemas/github_com_b3-fun_b3-mono_services_b3os-workflow_internal_app_api_http.ErrorResponse'
description: Forbidden
summary: Stream run execution events
tags:
- Runs
/v1/workflows/batch-stats:
post:
description: Fetch run counts and recent runs for multiple workflows
requestBody:
content:
application/json:
schema:
oneOf:
- type: object
- $ref: '#/components/schemas/BatchWorkflowStatsRequest'
summary: body
description: Workflow IDs
description: Workflow IDs
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/BatchWorkflowStatsSuccessResponse'
description: OK
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/github_com_b3-fun_b3-mono_services_b3os-workflow_internal_app_api_http.ErrorResponse'
description: Bad Request
summary: Batch workflow stats
tags:
- Runs
components:
schemas:
RecentRunItem:
properties:
finishedAt:
type: string
id:
type: string
startedAt:
type: string
status:
type: string
type: object
github_com_b3-fun_b3-mono_services_b3os-workflow_internal_pkg_entity.ConnectorReference:
description: nil if action doesn't need connector
properties:
id:
description: Connector ID (or subOrgId for turnkey)
type: string
type:
description: Connector type (e.g., "slack", "turnkey")
type: string
type: object
github_com_b3-fun_b3-mono_services_b3os-workflow_internal_pkg_entity.WorkflowInput:
properties:
description:
type: string
key:
type: string
required:
type: boolean
type:
description: '"string", "number", "boolean", "object", "array"'
type: string
type: object
BatchWorkflowStatsResponse:
additionalProperties:
$ref: '#/components/schemas/WorkflowStatsSummary'
type: object
github_com_b3-fun_b3-mono_services_b3os-workflow_internal_pkg_entity.WorkflowNode:
properties:
branch:
description: '"then" or "else", only when parent is "if" node'
type: string
children:
items:
type: string
type: array
uniqueItems: false
connector:
$ref: '#/components/schemas/github_com_b3-fun_b3-mono_services_b3os-workflow_internal_pkg_entity.ConnectorReference'
description:
description: AI-generated 1-sentence description
type: string
loopBody:
description: Loop body nodes (only for for-each nodes)
items:
type: string
type: array
uniqueItems: false
payload:
additionalProperties: {}
type: object
resultSchema:
additionalProperties: {}
description: 'ResultSchema describes the output structure of this node (populated dynamically for x402 endpoints).
This is used by the frontend to show available output variables in the variable picker.'
type: object
titleOverride:
description: AI-generated short title (2-6 words), only when more descriptive than default
type: string
type:
type: string
required:
- payload
- type
type: object
ListRunsSuccessResponse:
properties:
code:
example: 200
type: integer
data:
$ref: '#/components/schemas/PaginatedData-github_com_b3-fun_b3-mono_services_b3os-workflow_internal_pkg_entity_RunListItem'
message:
example: success
type: string
requestId:
example: abc-123
type: string
type: object
github_com_b3-fun_b3-mono_services_b3os-workflow_internal_app_api_http.ErrorResponse:
properties:
code:
type: integer
details:
items: {}
type: array
uniqueItems: false
message:
type: string
requestId:
type: string
type: object
github_com_b3-fun_b3-mono_services_b3os-workflow_internal_pkg_entity.Run:
properties:
executionState:
additionalProperties:
$ref: '#/components/schemas/github_com_b3-fun_b3-mono_services_b3os-workflow_internal_pkg_entity.ExecutionNode'
type: object
finishedAt:
type: string
id:
type: string
organizationId:
type: string
propValues:
additionalProperties: {}
type: object
startedAt:
type: string
status:
$ref: '#/components/schemas/github_com_b3-fun_b3-mono_services_b3os-workflow_internal_pkg_entity.RunStatus'
triggerSource:
type: string
triggeredBy:
type: string
workflowDefinition:
$ref: '#/components/schemas/github_com_b3-fun_b3-mono_services_b3os-workflow_internal_pkg_entity.WorkflowDefinition'
workflowId:
type: string
workflowVersion:
type: integer
type: object
github_com_b3-fun_b3-mono_services_b3os-workflow_internal_pkg_entity.RunStatus:
enum:
- running
- waiting
- success
- failure
- cancelled
type: string
x-enum-comments:
RunStatusCancelled: Run was cancelled by user
RunStatusFailure: Run failed
RunStatusRunning: Run is executing
RunStatusSuccess: Run completed successfully
RunStatusWaiting: Run is paused, waiting for a trigger to resume
x-enum-varnames:
- RunStatusRunning
- RunStatusWaiting
- RunStatusSuccess
- RunStatusFailure
- RunStatusCancelled
github_com_b3-fun_b3-mono_services_b3os-workflow_internal_pkg_entity.ExecutionNode:
properties:
connector:
additionalProperties: {}
description: Safe connector metadata (e.g., wallet address)
type: object
context:
$ref: '#/components/schemas/github_com_b3-fun_b3-mono_services_b3os-workflow_internal_pkg_entity.ExecutionContext'
finishedAt:
type: string
input:
additionalProperties: {}
description: Input payload at time of completion/failure (may be raw or resolved)
type: object
iterations:
description: 'For for-each nodes only: tracks execution state of each iteration.
Each iteration is a mini ExecutionState graph (nodeID → ExecutionNode).'
items:
additionalProperties:
$ref: '#/components/schemas/github_com_b3-fun_b3-mono_services_b3os-workflow_internal_pkg_entity.ExecutionNode'
type: object
type: array
uniqueItems: false
result:
additionalProperties: {}
description: Output from execution
type: object
secretKeys:
description: Input keys that contain connector secrets (for masking)
items:
type: string
type: array
uniqueItems: false
startedAt:
type: string
status:
$ref: '#/components/schemas/github_com_b3-fun_b3-mono_services_b3os-workflow_internal_pkg_entity.ExecutionNodeStatus'
type:
description: Node type (e.g., "webhook", "send-erc20-token")
type: string
type: object
github_com_b3-fun_b3-mono_services_b3os-workflow_internal_pkg_entity.ExecutionContext:
properties:
loopVars:
additionalProperties: {}
description: Loop variables (for for-each nodes)
type: object
orgStorage:
additionalProperties: {}
description: Organization storage values snapshot (default store)
type: object
orgStores:
additionalProperties:
additionalProperties: {}
type: object
description: 'Named store snapshots: storeName → key → value'
type: object
props:
additionalProperties: {}
description: Template prop values snapshot
type: object
storage:
additionalProperties: {}
description: Workflow storage values snapshot
type: object
type: object
EphemeralRunParams:
properties:
definition:
$ref: '#/components/schemas/github_com_b3-fun_b3-mono_services_b3os-workflow_internal_pkg_entity.WorkflowDefinition'
payload:
additionalProperties: {}
description: 'Payload is merged into the trigger result (root node output),
accessible via {{root.result.key}} expressions. A "triggeredAt"
timestamp is always added automatically.'
type: object
propValues:
additionalProperties: {}
description: 'PropValues are template parameter values injected into the run
context, accessible via {{$props.key}} expressions.'
type: object
runId:
description: 'RunID is an optional client-generated run ID. Must start with
"run_" prefix. If omitted, a run ID is generated server-side.
Use this to subscribe to SSE stream before triggering the run.'
example: run_abc123
type: string
required:
- definition
type: object
github_com_b3-fun_b3-mono_services_b3os-workflow_internal_pkg_entity.WorkflowDefinition:
description: 'Definition is the full workflow graph to execute. Must contain a
"root" node with type "manual". All action nodes referenced in
children arrays must be present.'
properties:
inputSchema:
items:
$ref: '#/components/schemas/github_com_b3-fun_b3-mono_services_b3os-workflow_internal_pkg_entity.WorkflowInput'
type: array
uniqueItems: false
nodes:
additionalProperties:
$ref: '#/components/schemas/github_com_b3-fun_b3-mono_services_b3os-workflow_internal_pkg_entity.WorkflowNode'
type: object
sensitivePropKeys:
items:
type: string
type: array
uniqueItems: false
required:
- nodes
type: object
GetRunSuccessResponse:
properties:
code:
example: 200
type: integer
data:
$ref: '#/components/schemas/github_com_b3-fun_b3-mono_services_b3os-workflow_internal_pkg_entity.Run'
message:
example: success
type: string
requestId:
example: abc-123
type: string
type: object
RunSuccessResponse:
properties:
code:
example: 200
type: integer
data:
$ref: '#/components/schemas/RunResponse'
message:
example: success
type: string
requestId:
example: abc-123
type: string
type: object
github_com_b3-fun_b3-mono_services_b3os-workflow_internal_pkg_entity.RunListItem:
properties:
finishedAt:
type: string
id:
type: string
startedAt:
type: string
status:
$ref: '#/components/schemas/github_com_b3-fun_b3-mono_services_b3os-workflow_internal_pkg_entity.RunStatus'
triggerSource:
type: string
triggeredBy:
type: string
workflowId:
type: string
workflowVersion:
type: integer
type: object
WorkflowRunCount:
properties:
failure:
type: integer
running:
type: integer
success:
type: integer
total:
type: integer
waiting:
type: integer
type: object
RunResponse:
properties:
runId:
example: run_c9i6j8k2l0m3
type: string
type: object
PaginatedData-github_com_b3-fun_b3-mono_services_b3os-workflow_internal_pkg_entity_RunListItem:
properties:
hasMore:
type: boolean
items:
items:
$ref: '#/components/schemas/github_com_b3-fun_b3-mono_services_b3os-workflow_internal_pkg_entity.RunListItem'
type: array
uniqueItems: false
limit:
type: integer
offset:
type: integer
type: object
BatchWorkflowStatsSuccessResponse:
properties:
code:
example: 0
type: integer
data:
$ref: '#/components/schemas/BatchWorkflowStatsResponse'
message:
example: successfully
type: string
requestId:
type: string
type: object
github_com_b3-fun_b3-mono_services_b3os-workflow_internal_pkg_entity.ExecutionNodeStatus:
enum:
- pending
- running
- success
- failure
- skipped
- waiting
- scheduled
- cancelled
type: string
x-enum-comments:
ExecutionNodeStatusCancelled: Set when run is cancelled by user
ExecutionNodeStatusFailure: Set when node execution fails
ExecutionNodeStatusPending: Set when run is created (all non-root nodes start as pending)
ExecutionNodeStatusRunning: Set when node execution begins
ExecutionNodeStatusScheduled: Set when node is scheduled for future execution
ExecutionNodeStatusSkipped: Set when node is skipped (e.g., non-taken if branch)
ExecutionNodeStatusSuccess: Set when node execution completes successfully
ExecutionNodeStatusWaiting: Set when node is paused waiting for a trigger
x-enum-varnames:
- ExecutionNodeStatusPending
- ExecutionNodeStatusRunning
- ExecutionNodeStatusSuccess
- ExecutionNodeStatusFailure
- ExecutionNodeStatusSkipped
- ExecutionNodeStatusWaiting
- ExecutionNodeStatusScheduled
- ExecutionNodeStatusCancelled
WorkflowStatsSummary:
properties:
counts:
$ref: '#/components/schemas/WorkflowRunCount'
recentRuns:
items:
$ref: '#/components/schemas/RecentRunItem'
type: array
uniqueItems: false
type: object
BatchWorkflowStatsRequest:
properties:
workflowIds:
items:
type: string
maxItems: 200
minItems: 1
type: array
uniqueItems: false
required:
- workflowIds
type: object