Orchestrator API¶

The Orchestrator API is the execution surface for MeshFlows workflows.

Base URL examples:

Local: http://localhost:8083
Cluster: http://orchestrator:8083

Authentication Model¶

Authentication depends on endpoint group and runtime configuration:

Workflow HTTP execution (POST /run*):
- 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.
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.

Health and Readiness¶

`GET /healthz`¶

Returns process health and version.

curl -s http://localhost:8083/healthz

Example response:

{
    "status": "ok",
    "version": "dev"
}

`GET /readyz`¶

Returns readiness and currently loaded runtime counts.

curl -s http://localhost:8083/readyz

Workflow Discovery¶

`GET /workflows`¶

List all loaded workflows with invocation metadata and step summaries.

curl -s http://localhost:8083/workflows

`GET /workflows/http`¶

List only workflows invokable via HTTP (invocation.type contains http).

curl -s http://localhost:8083/workflows/http

`GET /workflows/{workflow_name}`¶

Return full workflow details including serialized steps.

curl -s http://localhost:8083/workflows/demo

Runtime Configuration Resolution¶

`GET /api/runtime/config/resolved`¶

Resolve merged runtime configuration for a workflow and/or group.

Query parameters:

workflow (optional)
group (optional)

curl -s "http://localhost:8083/api/runtime/config/resolved?workflow=demo&group=default"

Execution Endpoints¶

Request bodies¶

POST /run/{workflow_name} expects:

{
    "xml": "<root><message>Hello</message></root>"
}

POST /run and POST /invoke/scheduled expect:

{
    "workflow": "demo",
    "xml": "<root><message>Hello</message></root>"
}

`POST /run/{workflow_name}`¶

Execute a workflow selected by URL path.

curl -s -X POST http://localhost:8083/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`¶

Legacy/body-based workflow selection.

curl -s -X POST http://localhost:8083/run \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer <token>" \
    -d '{"workflow":"demo","xml":"<root><message>Hello</message></root>"}'

`POST /invoke/scheduled`¶

Scheduled/internal execution path. Target workflow must have invocation.type containing schedule.

curl -s -X POST http://localhost:8083/invoke/scheduled \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer <schedule-token-or-jwt>" \
    -d '{"workflow":"nightly-demo","xml":"<root/>"}'

Response behavior¶

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 invocation mode not allowed or auth failure
- 429 throttling conditions hit (when configured)

Admin Endpoints¶

`POST /admin/validate`¶

Validate a workflow YAML document without loading it.

Validation is layered:

Contract validation (always executed by orchestrator).
Provider semantic validation (optional; executed when capability provider supports validation).

Headers:

X-Reload-Token: <token> when required.

curl -s -X POST http://localhost:8083/admin/validate \
    -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: error | warning | info
code: stable machine-readable code
message: human-readable explanation
path: optional field path within step/request

Recommended publish/reload behavior:

Contract errors always block (valid=false).
Provider validation errors block only in strict mode.
Provider unavailability returns provider_status=skipped and warning diagnostics in non-strict mode.

Strict mode toggle (recommended):

WORKFLOW_VALIDATE_PROVIDER_STRICT=true

Example response (provider warning, non-strict mode):

{
    "valid": true,
    "contract_status": "passed",
    "provider_status": "warning",
    "steps": [
        {
            "step_id": "publish_order",
            "contract": {
                "status": "passed",
                "diagnostics": []
            },
            "provider": {
                "status": "warning",
                "diagnostics": [
                    {
                        "severity": "warning",
                        "code": "JMS_HEADER_NON_STANDARD",
                        "message": "Header 'content-type' is mapped to provider-specific property.",
                        "path": "request.headers.content-type"
                    }
                ]
            }
        }
    ]
}

Example response (contract failure):

{
    "valid": false,
    "contract_status": "failed",
    "provider_status": "skipped",
    "steps": [
        {
            "step_id": "publish_order",
            "contract": {
                "status": "failed",
                "diagnostics": [
                    {
                        "severity": "error",
                        "code": "STEP_REQUIRED_FIELD_MISSING",
                        "message": "request.destination is required",
                        "path": "request.destination"
                    }
                ]
            },
            "provider": {
                "status": "skipped",
                "diagnostics": []
            }
        }
    ]
}

`POST /admin/reload`¶

Reload workflows, connections, and policies from runtime storage/directories.

curl -s -X POST http://localhost:8083/admin/reload \
    -H "X-Reload-Token: <reload-token>"

Trace and Trigger APIs¶

`GET /api/traces`¶

List execution traces.

Query parameters:

limit (default 50, max 500)
workflow (optional)
status (optional, for example success, failed, ignored, canceled, skipped)
since_minutes (optional)

curl -s "http://localhost:8083/api/traces?limit=20&workflow=demo&status=failed"

`GET /api/traces/{request_id}`¶

Get a single trace document.

curl -s http://localhost:8083/api/traces/req-123

`GET /api/traces/{request_id}/steps/{step_path}/{kind}`¶

Get step-level stored data (for dashboard drill-down).

curl -s http://localhost:8083/api/traces/req-123/steps/0.transform/input

`GET /api/trigger-events`¶

List trigger events, including accepted and failed trigger attempts.

curl -s "http://localhost:8083/api/trigger-events?limit=50"

`GET /api/trigger-events/{request_id}`¶

List trigger events correlated to a request id.

curl -s http://localhost:8083/api/trigger-events/req-123

Scheduler Proxy Endpoints¶

These endpoints proxy scheduler operations through the Dashboard service (/api/scheduler/*). They are listed here for operational convenience when testing the platform surface.

GET /api/scheduler/schedules
POST /api/scheduler/schedules
DELETE /api/scheduler/schedules/{job_id}
GET /api/scheduler/named-schedules
POST /api/scheduler/named-schedules
PUT /api/scheduler/named-schedules/{schedule_id}
DELETE /api/scheduler/named-schedules/{schedule_id}

User context:

Dashboard forwards identity context to scheduler.
For direct service calls, scheduler expects Bearer JWT authorization.

Example:

curl -s -X POST http://localhost:8090/api/scheduler/schedules \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer <jwt>" \
    -d '{"workflow":"nightly-demo","cron":"0 2 * * *","payload_xml":"<root/>"}'

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

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.

Orchestrator API¶

Authentication Model¶

Health and Readiness¶

GET /healthz¶

GET /readyz¶

Workflow Discovery¶

GET /workflows¶

GET /workflows/http¶

GET /workflows/{workflow_name}¶