Skip to main content

Workflow Integration

Trusted deployment owners or administrator clients can trigger an existing workflow through standalone Workflow Service, then use its returned Run ID to observe events and read history. This page covers global workflows that the administrator has deployed, verified, and approved for the Webhook entry point. It grants no authority to execute arbitrary workflows or user resources.

Obtain the Separate Address and Credential​

InformationWhere to obtain it
WORKFLOW_URLWorkflow Service address supplied by the administrator. Use its actual listener for local calls or a separately configured HTTPS address for remote calls
WORKFLOW_SERVICE_TOKENWORKFLOW_SERVICE_TOKEN in the standalone workflow process startup configuration; when not set separately, the deployment may use its configured AGENT_SERVICE_TOKEN, which the administrator must confirm
WORKFLOW_IDAn existing global workflow ID supplied by the administrator, verifiable through the list below; a display name cannot replace it
Parameter contractAdministrator-defined inputs, operations, and outcomes; first verify access with a test workflow that has no external side effects

The workflow service binds to loopback by default. Obtain its actual port from startup readiness information or the administrator. Its address and request header differ from Agent Service. Even if a deployment reuses the same token value, send X-Workflow-Service-Token.

The default Agent Service container deployment provides no public workflow service entry point, and its reverse proxy rejects /api/workflow/*. Adding a workflow path to an Agent Service URL does not make it available. The administrator must supply a separately reachable Workflow Service address.

For the standalone access described here, every business request below, including SSE, needs a valid X-Workflow-Service-Token. This is a service access credential, not separate execution authority for a user, task, or workflow. Run and workflow IDs do not replace credentials or resource permission checks.

Check the Workflow to Trigger​

GET /api/workflows​

No request body or pagination parameters. Returns { "workflows": [...] } with these item fields:

FieldMeaning
id, name, description, creatorWorkflow ID, display name, description, and creator description
nodeCountNumber of nodes in the definition
dslPathService-managed definition path, not a file on the caller's computer or an access credential
lastRunOptional compressed last-run summary with status and taskBoardBound, possibly completion time and duration
WORKFLOW_URL='https://workflow.example.com'
WORKFLOW_SERVICE_TOKEN='replace-with-the-configured-workflow-service-token'
WORKFLOW_ID='your-workflow-id'

curl --silent --show-error \
  --header "X-Workflow-Service-Token: ${WORKFLOW_SERVICE_TOKEN}" \
  "${WORKFLOW_URL}/api/workflows"

Use discovery to check the definition supplied by the administrator. It does not authorize every workflow to run, and unparseable definitions may be absent from the list.

Trigger a Preconfigured Workflow​

POST /api/workflow/webhook?id=...​

ItemContract
Query parameter idRequired ID of an existing global workflow
HeadersX-Workflow-Service-Token and Content-Type: application/json
Request bodyThis example uses a JSON object as workflow parameters; omission is treated as an empty object
Success200 with runId, workflowId, and status: "started"

This example assumes the administrator has defined a name input for the workflow. Replace fields according to its input contract:

curl --silent --show-error --include --request POST \
  --header "X-Workflow-Service-Token: ${WORKFLOW_SERVICE_TOKEN}" \
  --header 'Content-Type: application/json' \
  --data '{"name":"API"}' \
  "${WORKFLOW_URL}/api/workflow/webhook?id=${WORKFLOW_ID}"
{
  "runId": "00000000-0000-4000-8000-000000000010",
  "workflowId": "your-workflow-id",
  "status": "started"
}

Save the actual runId. started means the service received and scheduled the asynchronous execution. Definition parsing, nodes, permissions, or dependencies can still fail later; it does not mean completion.

This workflow Webhook uses the service token and differs from the Bearer secret and event body used by Agent Webhook. It has no request deduplication or public idempotency key. Putting a business event ID in parameters does not enable deduplication. A lost response may follow execution, so do not resend just to guess its outcome.

Observe Realtime Events​

GET /api/workflow/events?runId=...​

Send the returned runId and service token to receive text/event-stream:

WORKFLOW_RUN_ID='replace-with-the-returned-run-id'

curl --no-buffer --silent --show-error --get \
  --header "X-Workflow-Service-Token: ${WORKFLOW_SERVICE_TOKEN}" \
  --data-urlencode "runId=${WORKFLOW_RUN_ID}" \
  "${WORKFLOW_URL}/api/workflow/events"

Each event has an event: name and JSON data:. Common events include:

EventWhat to observe
workflow:startedWorkflow and Run IDs, name, and total node count
workflow:node_startNode ID, type, and optional display name
workflow:node_completeNode inputs, outputs, and duration
workflow:node_errorNode ID and error; continue observing the whole-run outcome
workflow:human_gateA human confirmation wait, not completion
workflow:completeRun status and any final outputs; inspect status
workflow:errorExecution error, possibly with the failed node

Use one active subscription per Run. The stream grants access at the service credential boundary for trusted administrator clients. It does not implement arbitrary end-user resource access by Run ID. Native browser EventSource cannot directly set this custom authentication header; use a fetch stream that sends headers, and keep tokens out of URLs.

Reconnecting to a Run that already ended in the current service process can return only one workflow:complete, whose status can also be failed. The event name alone does not establish success. Historical executions or realtime context lost after process restart can return 404; use the history endpoints below.

SSE does not durably replay every event. Disconnection, stream closure, or no events cannot independently establish success. Read state and history by the Run ID, and preserve unknown outcomes when unconfirmed.

Read Execution History​

GET /api/workflow/:id/runs​

Returns { "runs": [...] }, merging active and persisted executions ordered by startedAt, newest first. No pagination parameters. Example key fields of a summary item:

{
  "runs": [
    {
      "runId": "00000000-0000-4000-8000-000000000010",
      "status": "completed",
      "startedAt": "2026-10-14T02:00:00.000Z",
      "nodeCount": 2,
      "completedNodeCount": 2,
      "taskBoardBound": false
    }
  ]
}

Summaries can also include completedAt, totalDurationMs, error, and authorized task/execution ownership information. Active executions can temporarily have node counts of 0, which does not mean their definitions contain no nodes.

GET /api/workflow/:id/runs/:runId​

Returns one execution detail object with workflowId, runId, status, startedAt, and taskBoardBound. Terminal executions can include completedAt, totalDurationMs, nodeResults, finalOutputs, and error; a human confirmation wait can include humanGate.

curl --silent --show-error \
  --header "X-Workflow-Service-Token: ${WORKFLOW_SERVICE_TOKEN}" \
  "${WORKFLOW_URL}/api/workflow/${WORKFLOW_ID}/runs/${WORKFLOW_RUN_ID}"

running and waiting_human mean execution or pending confirmation. Terminal states are completed, failed, cancelled, and interrupted. Evaluate the actual status, error, and outputs. A Workflow runId belongs to Workflow Service and cannot be used with Agent Service /api/runs/:id/receipt.

TaskBoard-Associated Records​

History lists and details check permissions for associated TaskBoard resources; unreadable task records are not returned as visible results. Task-scoped queries use:

Query parameterCondition
boardIdRequired when specifying task scope
workflowBindingIdRequired for task scope and must belong to this workflow and Board/Task
taskIdOptional; must be nonempty and match the binding when supplied

These parameters identify and filter resources; they grant no access. Invalid combinations or insufficient permissions can return 403. Detail outside the requested task scope returns 404. An empty list can also result from permission filtering or unreadable history, so it does not establish that nothing ran.

Manual Execution and Definition Write Scope​

POST /api/workflow/run requires a valid executionGrantId, idempotencyKey, and the corresponding definition reference or authorized path. A service access token does not replace execution authority. The trigger and read endpoints above do not issue it. Manual execution requires product-supported workflow operations or a separately supplied authorization integration; the quick start here uses a preconfigured Webhook. Do not invent a grant or copy an internal permission object.

The old POST /api/workflows definition creation and PUT /api/workflow/:id replacement endpoints are retired and return 410. Maintain definitions through the existing workflow management process. This page only triggers administrator-preconfigured workflows suitable for its Webhook. Use the corresponding product flow for human confirmation; receiving a human_gate message is not approval.

Errors and Recovery​

HTTP status or conditionMeaning and action
401 unauthorizedMissing or invalid workflow service token; check the dedicated header and address
503 workflow_service_not_initializedWorkflow access credential is uninitialized; ask the administrator to check startup configuration
503 WORKFLOW_OWNER_FENCEDThe service cannot safely provide the operation; retain the response and ask the administrator to inspect service state, without unconditional trigger replay
Trigger 400 id query parameter is requiredSupply the workflow ID from the administrator
Trigger 404The global workflow is unreadable or missing; check the service and ID
Trigger 503 Unable to reserve workflow runExecution could not be reserved; inspect the actual response and service state
Events 400 runId is required / 404 Run not foundMissing Run ID or no realtime execution in this process; check the ID and read history
History 403 / 404Resource permissions, workflow/Run matching, or task scope do not allow the read; do not bypass ownership checks
Failure after successful trigger or SSE disconnectionReceipt is not completion; read history with the actual returned Run ID and retain unknown outcomes when unconfirmed
Request format, size, or dependency errorsPreserve the actual status and body, correct the request or investigate dependencies; errors do not share a universal envelope

Repeating reads updates observations; triggering again creates another execution. If the trigger response is missing, do not attribute the latest execution directly to this request.