API Reference

The Exekra Orchestrator exposes a REST API over HTTPS. All endpoints (except those marked Public) require authentication via a JWT token stored in an HTTP-only cookie.

Authentication

Authenticate a user and receive a session token.

{
  "email": "[email protected]",
  "password": "securepassword"
}

{
  "user": {
    "id": "clx1abc2300001",
    "email": "[email protected]",
    "name": "Admin User",
    "role": "ADMIN"
  }
}

Sets cookie: token (HttpOnly, Secure, SameSite=Lax, 7-day expiry). Returns 401 on invalid credentials.

Register a new user. Role defaults to OPERATOR if not specified.

{
  "email": "[email protected]",
  "password": "securepassword",
  "name": "Jane Developer",
  "role": "DEVELOPER"
}

End the current session. Clears the token cookie.

Get the current authenticated user.

Executions

Create a new execution (trigger a workflow run). Requires a published version.

{
  "workflowId": "clx1wf0001"
}

{
  "execution": {
    "id": "clx1exec001",
    "workflowId": "clx1wf0001",
    "workflow": { "id": "clx1wf0001", "name": "Invoice Processing" },
    "runnerId": null,
    "triggeredBy": "clx1abc2300001",
    "versionId": "clx1ver001",
    "status": "QUEUED",
    "logs": null,
    "startedAt": null,
    "completedAt": null,
    "createdAt": "2025-01-15T10:00:00.000Z"
  }
}

List executions with optional filters.

Get aggregate execution counts (total, queued, running, completed, failed, stopped).

Get a single execution by ID.

Update execution status. Called by runners to report progress.

{
  "status": "COMPLETED",
  "logs": "[2025-01-15T10:00:05Z] Starting workflow...\n...",
  "metrics": {
    "cpuAvg": 35.2,
    "cpuPeak": 78.5,
    "memAvgMB": 512,
    "memPeakMB": 1024
  }
}

Runners

Register a new runner. Returns machine credentials (secret shown only once).

{
  "name": "PROD-Runner-01",
  "type": "UNATTENDED"
}

{
  "id": "clx1runner01",
  "name": "PROD-Runner-01",
  "machineKey": "FC-a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4",
  "machineSecret": "e5f6a1b2c3d4...64 hex chars...",
  "type": "UNATTENDED"
}

Authenticate with machine credentials and receive a JWT token (24h expiry).

{
  "machineKey": "FC-a1b2c3d4...",
  "machineSecret": "e5f6a1b2c3d4..."
}

Send heartbeat with metrics. Sets runner status to ONLINE. TTL: 120 seconds.

{
  "machineKey": "FC-a1b2c3d4...",
  "machineSecret": "e5f6a1b2c3d4...",
  "ipAddress": "10.0.1.50",
  "metrics": {
    "cpu": 45.2,
    "memTotalMB": 16384,
    "memUsedMB": 8192,
    "memUsage": 50.0
  }
}

Poll for assigned work. Returns hasWork: false if no assignment, or the execution with graphJson if work is available.

{
  "hasWork": true,
  "execution": {
    "id": "clx1exec001",
    "workflowId": "clx1wf0001",
    "workflowName": "Invoice Processing",
    "graphJson": "{\"nodes\":[...],\"edges\":[...]}"
  }
}

Create execution directly from an attended runner. Execution created with status RUNNING (bypasses queue).

Get all published workflows available for execution on this runner.

List all runners. Filter by status (ONLINE, OFFLINE, BUSY) or type (ATTENDED, UNATTENDED).

Generate a new machine secret. Invalidates the previous secret immediately.

Delete a runner registration.

Workflows

Create a new workflow.

{
  "name": "Invoice Processing",
  "description": "Processes incoming invoices from the shared mailbox"
}

List all workflows. Supports page and limit query parameters.

Get a single workflow with its versions, triggers, and execution count.

Update workflow name or description.

Delete a workflow and all its versions (cascade).

Save a draft version. Each save creates a new version with auto-incremented number.

{
  "graphJson": "{\"nodes\":[...],\"edges\":[...]}",
  "metadata": "Added browser opening step"
}

Publish the latest draft. Supersedes any previously published version. Returns 400 if no draft exists.

List all versions of a workflow (drafts and published).

Get the latest version (may be a draft).

Triggers

Create a trigger for a workflow.

{
  "workflowId": "clx1wf0001",
  "type": "SCHEDULE",
  "config": "{\"cron\": \"0 9 * * 1-5\"}",
  "enabled": true
}

{
  "workflowId": "clx1wf0001",
  "type": "WEBHOOK",
  "config": "{}",
  "enabled": true
}

List all triggers. Supports page and limit query parameters.

Update trigger config or enabled status. Schedule triggers are rescheduled automatically.

Delete a trigger. Stops the cron job if it is a schedule trigger.

Invoke a webhook trigger. Validates the trigger exists, is type WEBHOOK, and is enabled.

{
  "success": true,
  "executionId": "clx1exec003"
}

System

Check system state: UNACTIVATED, ACTIVATED, BOOTSTRAPPED, or OPERATIONAL.

Health check. Returns status: ok with a timestamp.

Activate the platform license. Requires system state UNACTIVATED.

Get license status: activated flag, status (ACTIVE/GRACE_PERIOD/EXPIRED/INVALID), limits, and days remaining.

Force revalidation of the current license.

List all registered users. Supports page and limit query parameters.

Get per-workflow performance metrics including execution counts, success/failure rates, CPU/memory averages, and duration.