Workflows API

The platform's most powerful layer: multi-step processes drawn as a graph in the portal — several agents, if/else branching on structured results, data transforms, and human approval gates — executed durably. A workflow that waits three days for a manager's approval loses nothing: runs are checkpointed and resume exactly where they stopped, surviving restarts and deploys.

Build visually (drag nodes, connect edges, publish); trigger from anywhere: this API, a schedule, an inbound webhook, chat, or another agent. Verified live — every call below was executed against production.

Base URL: https://platform.senaiy.ai/v1

Authorization: scope + binding (TR-5)

Two layers, both required:

The key needs the workflows.run scope — without it: Key lacks scope(s): workflows.run.
The key must be bound to the specific workflow (portal → API key → workflow allowlist). An unbound key is refused even with the scope — binding is deny-by-default.

Start a run

curl -X POST "https://platform.senaiy.ai/v1/workflows/{code}/runs" \
  -H "Authorization: Bearer sk-sf-..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-4711" \
  -d '{"input": "{\"note\": \"launch it\"}"}'

Returns 202 with {"message": {"run_id": "WFR-…", "status": "Queued"}}. Replaying the same Idempotency-Key returns the original run with "replayed": true — retries are free. Payloads over 256 KB return 413. If the workflow declares an input schema, non-conforming payloads are rejected with pointer errors.

Observe

curl https://platform.senaiy.ai/v1/workflow-runs/{run_id}
# → status, per-run cost and tokens, output, error

curl https://platform.senaiy.ai/v1/workflow-runs/{run_id}/trace
# → the full tree: every node, every agent run underneath, nested sub-workflows

Statuses: Queued → Running → Completed | Failed | Cancelled, plus the parked states Waiting Approval, Waiting Budget, Waiting Capacity. A run at an approval gate stays parked until a human decides in the portal — hours or days; nothing is lost across restarts (checkpointed). Poll, or register a result webhook (portal → Webhooks) for workflow.run.finished.

Trigger by inbound webhook

A workflow with webhooks enabled accepts POST /v1/workflows/{code}/webhook — HMAC-SHA256 signed (X-AI-Platform-Timestamp / X-AI-Platform-Signature, 300 s skew), with an optional source-IP allowlist. Fails closed when unconfigured.