Orchestrator API¶
The Orchestrator API is the execution surface for MeshFlows workflows.
Base URL examples:
- Local (compose / port-forward): often
http://localhost:8083depending on mapping - Cluster DNS:
http://orchestrator:8080
Authentication Model¶
Authentication depends on endpoint group and runtime configuration:
- Workflow HTTP execution (
POST /run/{name},POST /run/{name}/enqueue): - OAuth2/JWT scopes when OAuth is enabled.
- Optional bearer-token fallback using
HTTP_INVOCATION_TOKENor per-workflow tokens. - Scheduled execution (
POST /invoke/scheduled): - Optional
SCHEDULE_INVOCATION_TOKEN. - Or OAuth2 scopes when
OAUTH2_APPLY_TO_SCHEDULEDis enabled. - Dashboard execution (
POST /invoke/dashboard): - Optional
DASHBOARD_INVOCATION_TOKENand/or OAuth2 after IAM scope check. - Admin reload/validate:
X-Reload-Tokenheader when reload token is configured.
Recommendation: expose public entrypoints through Gateway and keep internal/admin routes network-restricted.
Capability discovery¶
Orchestrator resolves service_call targets via the capability registry:
- Env:
CAPABILITY_REGISTRY_URL(required forservice_call; when unset, those steps are disabled) - Optional:
CAPABILITY_REGISTRY_TOKEN,CAPABILITY_REGISTRY_CACHE_TTL_SECONDS - Contract: Capability Provider Contract (17)
Orchestrator does not read EGRESS_*_URL env vars for runtime discovery.
Messaging env (async / queue)¶
Relevant when enqueue/workers are enabled:
| Variable | Role |
|---|---|
ORCH_MESSAGE_RABBITMQ_URL |
Broker URL for command publish/consume |
ORCH_MESSAGE_WORK_EXCHANGE |
Work exchange (default orchestrator.commands) |
ORCH_MESSAGE_TRACK_THRESHOLD_BYTES |
Small/large track split (default 524288) |
ORCH_MESSAGE_STORAGE_UPLOAD_TIMEOUT_SECONDS |
Large-payload offload timeout |
ORCH_MESSAGE_DATABASE_DSN |
Postgres run ledger (API + workers) |
ORCH_ASYNC_QUEUE_ENABLED |
Enables POST /run/{name}/enqueue |
See also Orchestrator microservice and Messaging blueprint.
Health and Readiness¶
GET /healthz¶
Returns process health and version.
curl -s http://orchestrator:8080/healthz
GET /readyz¶
Returns readiness and currently loaded runtime counts.
Workflow Discovery¶
GET /workflows¶
List all loaded workflows with invocation metadata and step summaries.
GET /workflows/http¶
List only workflows invokable via HTTP.
GET /workflows/{workflow_name}¶
Return full workflow details including serialized steps.
GET /triggers¶
List loaded start contracts / triggers.
Runtime Configuration Resolution¶
GET /api/runtime/config/resolved¶
Resolve merged runtime configuration for a workflow and/or group.
Query parameters: workflow, group (optional).
Execution Endpoints¶
Request body¶
HTTP and enqueue entrypoints expect a JSON body with the payload field used by the runtime (commonly xml for the raw body text, which may contain XML or JSON):
{
"xml": "<root><message>Hello</message></root>"
}
Deprecated: a body-selected
POST /runwith{"workflow":"…"}is not the supported public contract. Use path-based/run/{name}(or gateway aliases). Prefer/run/{name}/enqueuefor async.
POST /run/{workflow_name}¶
Synchronous HTTP execution. Workflow must allow HTTP invocation.
curl -s -X POST http://orchestrator:8080/run/demo \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <token>" \
-H "X-Request-ID: req-123" \
-d '{"xml":"<root><message>Hello</message></root>"}'
POST /run/{workflow_name}/enqueue¶
Async queue entry (HTTP 202). Requires ORCH_ASYNC_QUEUE_ENABLED and ORCH_MESSAGE_RABBITMQ_URL.
- Small track: payload inline in the command message
- Large track: payload offloaded; queue carries
payload_ref
Optional header: X-Idempotency-Key.
POST /invoke/scheduled¶
Scheduled/internal execution. Target workflow must allow schedule invocation.
curl -s -X POST http://orchestrator:8080/invoke/scheduled \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <schedule-token-or-jwt>" \
-d '{"workflow":"nightly-demo","xml":"<root/>"}'
POST /invoke/amqp¶
AMQP / RabbitMQ-trigger adapter entry (payload + workflow selection from the trigger subscriber).
POST /invoke/amqp/dispatch¶
Dispatch path used by the messaging/worker pipeline after a queued command is consumed.
POST /invoke/dashboard¶
Dashboard-initiated run after IAM scope checks (token/DASHBOARD_INVOCATION_TOKEN as configured).
Response behavior (sync /run/{name})¶
- Returns workflow output as plain text (often XML/JSON payload text).
- Includes
X-Request-IDresponse header for correlation. - Typical errors:
404unknown workflow,403auth/mode,429throttling.
Run ledger APIs¶
GET /api/runs¶
List workflow runs (operations / dashboard).
Query parameters: limit, workflow, status, since_minutes, since, until (ISO-8601 UTC). since/until take precedence over since_minutes.
POST /api/runs/delivery-failed¶
Record a failed delivery before the run ledger starts (gateway → orchestrator).
GET /api/runs/{run_id}/ledger¶
Fetch persisted run/step ledger for a run.
POST /api/runs/{run_id}/resume¶
Resume a checkpointed run (when run-state persistence is enabled).
Admin Endpoints¶
POST /admin/validate¶
Validate a workflow YAML document without loading it.
Query:
strict=true— missing registry capabilities / provider issues fail validation (recommended for CI publish).
Validation is layered:
- Contract validation (always executed by orchestrator).
- Provider semantic validation (optional; when the capability provider supports validation).
Headers:
X-Reload-Token: <token>when required.
curl -s -X POST "http://orchestrator:8080/admin/validate?strict=true" \
-H "Content-Type: text/yaml" \
-H "X-Reload-Token: <reload-token>" \
--data-binary @flows/workflows/demo.yaml
Response shape:
{
"valid": true,
"contract_status": "passed",
"provider_status": "passed",
"steps": [
{
"step_id": "publish_order",
"contract": { "status": "passed", "diagnostics": [] },
"provider": { "status": "passed", "diagnostics": [] }
}
]
}
Diagnostic fields: severity, code, message, path.
Recommended publish/reload behavior:
- Contract errors always block (
valid=false). - Provider validation errors block in strict mode (
?strict=true/WORKFLOW_VALIDATE_PROVIDER_STRICT). - Provider unavailability returns
provider_status=skippedand warnings in non-strict mode.
POST /admin/reload¶
Reload workflows, connections, and policies from runtime storage/directories.
POST /admin/reload-workflow/{workflow_name}¶
Reload a single workflow artifact.
Trace and Trigger APIs¶
GET /api/traces¶
Query parameters: limit, workflow, status, since_minutes.
GET /api/traces/{request_id}¶
GET /api/traces/{request_id}/related¶
GET /api/traces/{request_id}/neighbors¶
GET /api/traces/{request_id}/steps/{step_path}/{kind}¶
GET /api/trigger-events¶
GET /api/trigger-events/{request_id}¶
Scheduler Proxy Endpoints¶
These endpoints proxy scheduler operations (also exposed via Dashboard /api/scheduler/*):
GET|POST /api/scheduler/schedulesGET|POST /api/scheduler/named-schedules- related update/delete routes as deployed
Internal Operational Endpoints¶
OAuth token cache and connection tests¶
GET /internal/oauth/statsPOST /internal/oauth/healthDELETE /internal/oauth/tokens/{connection_name}POST /internal/oauth/connections/testPOST /internal/connections/{name}/test
Idempotency store operations¶
GET /internal/idempotency/statsDELETE /internal/idempotency/{workflow_name}/{idempotency_key}POST /internal/idempotency/cleanupDELETE /internal/idempotency
These endpoints are intended for operations/admin usage and should not be publicly exposed.