Skip to content

Orchestrator API

The Orchestrator API is the execution surface for MeshFlows workflows.

Base URL examples:

  • Local (compose / port-forward): often http://localhost:8083 depending 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_TOKEN or per-workflow tokens.
  • Scheduled execution (POST /invoke/scheduled):
  • Optional SCHEDULE_INVOCATION_TOKEN.
  • Or OAuth2 scopes when OAUTH2_APPLY_TO_SCHEDULED is enabled.
  • Dashboard execution (POST /invoke/dashboard):
  • Optional DASHBOARD_INVOCATION_TOKEN and/or OAuth2 after IAM scope check.
  • Admin reload/validate:
  • X-Reload-Token header 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 for service_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 /run with {"workflow":"…"} is not the supported public contract. Use path-based /run/{name} (or gateway aliases). Prefer /run/{name}/enqueue for 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-ID response header for correlation.
  • Typical errors: 404 unknown workflow, 403 auth/mode, 429 throttling.

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=skipped and 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/schedules
  • GET|POST /api/scheduler/named-schedules
  • related update/delete routes as deployed

Internal Operational Endpoints

OAuth token cache and connection tests

  • GET /internal/oauth/stats
  • POST /internal/oauth/health
  • DELETE /internal/oauth/tokens/{connection_name}
  • POST /internal/oauth/connections/test
  • POST /internal/connections/{name}/test

Idempotency store operations

  • GET /internal/idempotency/stats
  • DELETE /internal/idempotency/{workflow_name}/{idempotency_key}
  • POST /internal/idempotency/cleanup
  • DELETE /internal/idempotency

These endpoints are intended for operations/admin usage and should not be publicly exposed.