Workflows API
Start a workflow run from the API, send a chat turn, and poll the run for its status and steps.
The public API can start a run of a published workflow and report what that run did. It cannot create, edit, or deploy a workflow. Build workflows in the Workflows product area, then start them from your own systems.
Every operation is asynchronous. A workflow can pause for a person to approve a customer-facing action, so a run has no bounded completion time. Each call returns a run identifier that you poll.
Scopes
| Operation | Required scope |
|---|---|
POST /workflows/{id}/execute | workflows.write |
POST /workflows/{id}/chat | workflows.write |
GET /workflows/runs/{executionId} | workflows.read |
Both OAuth tokens and API keys are accepted. See Authentication.
Start a run
POST /workflows/{id}/execute
The path id is the workflow. The run uses the promoted version, not the draft.
Request
| Field | Type | Default | Description |
|---|---|---|---|
triggerType | invoice_overdue, manual, webhook, or payment_failed | manual | The trigger that this call asserts. It must match a trigger that the workflow declares. |
triggerData | object | {} | Data that the run starts with. |
idempotencyKey | string, 1 to 255 characters | none | Repeat calls with the same key and workflow collapse to one run. |
Record identifiers inside triggerData resolve against your team only. A request that names another team's record is rejected.
Supply an idempotencyKey on any caller that can retry. Without it, a retry starts a second run and the workflow does its work twice.
curl --request POST \
--url https://api.eigenn.io/v1/workflows/9c1e4c2a-0000-4000-8000-000000000000/execute \
--header "Authorization: Bearer ${EIGENN_API_KEY}" \
--header 'Content-Type: application/json' \
--data '{
"triggerType": "invoice_overdue",
"triggerData": { "invoiceId": "3f2b1c4d-0000-4000-8000-000000000000" },
"idempotencyKey": "invoice-chase-example"
}'Response
{
"executionId": "0b8f...",
"runId": "job_71f2...",
"queuedAt": "2026-07-11T14:02:11.000Z",
"status": "queued"
}status is always queued. It confirms that Eigenn accepted and enqueued the run. It is not proof that any step completed.
Use executionId to poll the run. Use runId to correlate the run with worker logs when you contact support.
Send a chat turn
POST /workflows/{id}/chat
A chat turn starts a run from a conversational message. The workflow must declare a manual trigger. A workflow configured for a webhook or a schedule is refused.
Request
| Field | Type | Required | Description |
|---|---|---|---|
message | string, 1 to 8,000 characters | Yes | The user's turn. The workflow receives it as trigger data under message. |
conversationId | string, 1 to 255 characters | No | Groups turns into one conversation. Eigenn echoes it back and passes it to the workflow. Omit it to start an unlinked turn. |
triggerData | object | No | Extra context merged alongside the message. It cannot overwrite message. |
idempotencyKey | string, 1 to 255 characters | No | Repeat calls with the same key collapse to one run. |
Response
{
"executionId": "0b8f...",
"conversationId": "conv-7f3a",
"queuedAt": "2026-07-11T14:02:11.000Z",
"status": "queued"
}The reply is not in this response. A chat turn is not synchronous, because the workflow can pause for a person to approve what it drafted. Poll the run for the result.
Poll a run
GET /workflows/runs/{executionId}
Returns the run, its current node, and its recorded steps.
| Field | Description |
|---|---|
executionId | The run |
workflowId | The workflow that produced the run |
status | pending, running, waiting, completed, failed, or canceled |
currentNodeId | The node the run is at, or null |
triggerType | The trigger that started the run |
createdAt, completedAt | Timestamps, or null |
steps | Each step with its nodeId, status, startedAt, completedAt, and errorMessage |
waiting means the run is paused, most often for a person to approve a customer-facing action. It does not mean the run is stuck. Use Workflow Pauses to resolve the checkpoint.
Poll with backoff. A run that waits for a person can stay in waiting for as long as the approval takes.
Errors
These operations return 400, 401, 403, 404, 409, 422, 429, and 500.
| Status | Common cause |
|---|---|
400 | The request body failed validation |
403 | The token lacks workflows.read or workflows.write |
404 | The workflow or run does not exist in your team |
409 | The asserted trigger does not match the workflow, or an idempotency key is in flight |
422 | Trigger data named a record that your team does not own |
429 | A rate limit applied. Respect Retry-After |
See Errors and Safe Retries and Rate Limits.
Not in the public API
The public contract has no operation that:
- lists or searches workflow definitions
- creates, updates, or deletes a workflow
- deploys or promotes a version
- lists execution history across runs
- resumes or cancels a workflow pause
Use the Workflows product area for those tasks. Do not call private browser requests from an external integration.
MCP boundary
The remote MCP endpoint gives scoped finance tools, resources, and prompts. It does not give workflow-builder operations or execution history.
An MCP client can prepare input for a workflow with the permitted customer, invoice, transaction, report, and search tools. It is not a workflow execution API.