Workflows API

Start a workflow run from the API, send a chat turn, and poll the run for its status and steps.

Summary

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.

Starting a run is asynchronous; reading its status is a normal request. A workflow can pause at an approval step, so the start response cannot promise a completion time. Poll using the returned execution ID.

Capabilities

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.

Prerequisites

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. Your effective role must retain the required scope. Starting a run also requires write access to its workflow namespace, an active workflow, a valid promoted definition, and API execution enabled. See Authentication.

Concepts

MCP boundary

The remote MCP endpoint includes workflow listing, run-status lookup, and execution tools. It does not provide a workflow builder or a history-list operation. Its execution tool requires both workflows.read and workflows.write; its accepted trigger types differ from REST. See MCP workflows.

Workflow

Start a run

POST /workflows/{id}/execute

The path id is the workflow UUID. The run uses the promoted version, not the draft.

Request

Field	Type	Default	Description
`triggerType`	`invoice_overdue`, `manual`, `webhook`, `payment_failed`, or `customer_segment_entered`	`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	Reuses a matching retained job/execution for this team and workflow.

Record identifiers inside triggerData resolve against your team only. A request that names another team's record is rejected.

Supply a body idempotencyKey when a caller may retry. Without it, a retry can start another run. The key is shared across execute, chat, and MCP starts for the same team and workflow; it does not compare request bodies or caller identities. Use a different key for a different intended run. Reuse still passes workflow access and readiness checks.

This body key is separate from the optional HTTP Idempotency-Key header described in Errors and Safe Retries. Neither replaces idempotency for external effects performed by workflow steps.

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": "0b8f0000-0000-4000-8000-000000000001",
  "runId": "7123",
  "queuedAt": "2026-07-11T14:02:11.000Z",
  "status": "queued"
}

The start response uses HTTP 200 and status: queued. It can also refer to an existing execution found through the body key. Read the execution to learn its current state; this acknowledgment does not prove a fresh queue entry or a completed step.

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	An identifier echoed in the response and passed to the workflow. It does not automatically restore earlier messages or resume a run.
`triggerData`	object	No	Extra context merged alongside the message. Top-level `message` and, when supplied, `conversationId` take precedence.
`idempotencyKey`	string, 1 to 255 characters	No	Uses the same team/workflow key space as execute and MCP.

Response

{
  "executionId": "0b8f0000-0000-4000-8000-000000000001",
  "conversationId": "conv-7f3a",
  "queuedAt": "2026-07-11T14:02:11.000Z",
  "status": "queued"
}

Each accepted chat request starts or reuses an execution; it is not a synchronous chat-completion API. The start response and run-status endpoint do not return generated reply text or step outputs. Check the output destination configured by the workflow.

When the top-level conversationId is omitted, the response returns null. A value inside triggerData can still reach the workflow, so use the top-level field when you need a consistent echoed identifier.

Poll a run

GET /workflows/runs/{executionId}

Returns the run, its current node, and recorded step summaries for an execution in your team. The path requires an execution UUID. It does not return step inputs, outputs, or a generated chat reply.

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 `id`, `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.

Behavior specification

Errors

The following outcomes depend on the stage at which a request is refused:

Status	Common cause
`400`	Trigger dispatch is invalid, or referenced trigger data cannot be loaded for this team
`401`	Credentials are absent, invalid, or have no effective scopes
`403`	Required scope or namespace write access is missing, or API execution is disabled
`404`	The workflow or execution does not exist in your team
`409`	The workflow is inactive, has no promoted version, has a malformed promoted definition, or has no trigger
`422`	Request schema validation failed; this is not the specific cross-team-record response
`429`	A rate limit applied; respect `Retry-After`
`500`	An unexpected server failure occurred

Request parsing can also return 400. If you opt into the shared HTTP idempotency header, its guard can return 409 while a matching request is running or 503 when that guard is unavailable. A repeated workflow body key does not itself mean a conflict.

See Errors and Safe Retries and Rate Limits.

Diagrams

Rendering diagram…

Screenshots

Not applicable: this page describes an API or a non-visual workflow rather than an application screen.

Verification

These are acceptance checks to run with an isolated team, a promoted synthetic workflow, and intercepted external actions. This copy review does not record a successful run.

Start a run using the execute endpoint with a supported trigger and trigger data. Expect a response containing executionId and a status of queued.
Send a chat turn to a workflow with a manual trigger and receive a response containing executionId, conversationId, and a status of queued.
Poll a run using its execution ID and observe its status and step history, expecting statuses like pending, running, waiting, completed, failed, or canceled.
Submit requests with missing scopes or improper input and confirm expected error responses, such as 403 or 400.
Retry a retained execution with the same body key and confirm the same execution ID. Use a new key for a different intended run; do not change inputs under an existing key.
Check inactive, unpromoted, API-disabled, namespace-denied, trigger-mismatch, and cross-team input cases against the error table.
Confirm run polling contains status and step summaries but no generated reply or step output.

Summary

Capabilities

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.

Prerequisites

Scopes

Operation	Required scope
`POST /workflows/{id}/execute`	`workflows.write`
`POST /workflows/{id}/chat`	`workflows.write`
`GET /workflows/runs/{executionId}`	`workflows.read`

Concepts

MCP boundary

Workflow

Start a run

POST /workflows/{id}/execute

The path id is the workflow UUID. The run uses the promoted version, not the draft.

Request

Field	Type	Default	Description
`triggerType`	`invoice_overdue`, `manual`, `webhook`, `payment_failed`, or `customer_segment_entered`	`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	Reuses a matching retained job/execution for this team and workflow.

Record identifiers inside triggerData resolve against your team only. A request that names another team's record is rejected.

This body key is separate from the optional HTTP Idempotency-Key header described in Errors and Safe Retries. Neither replaces idempotency for external effects performed by workflow steps.

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": "0b8f0000-0000-4000-8000-000000000001",
  "runId": "7123",
  "queuedAt": "2026-07-11T14:02:11.000Z",
  "status": "queued"
}

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	An identifier echoed in the response and passed to the workflow. It does not automatically restore earlier messages or resume a run.
`triggerData`	object	No	Extra context merged alongside the message. Top-level `message` and, when supplied, `conversationId` take precedence.
`idempotencyKey`	string, 1 to 255 characters	No	Uses the same team/workflow key space as execute and MCP.

Response

{
  "executionId": "0b8f0000-0000-4000-8000-000000000001",
  "conversationId": "conv-7f3a",
  "queuedAt": "2026-07-11T14:02:11.000Z",
  "status": "queued"
}

Poll a run

GET /workflows/runs/{executionId}

Returns the run, its current node, and recorded step summaries for an execution in your team. The path requires an execution UUID. It does not return step inputs, outputs, or a generated chat reply.

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 `id`, `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.

Behavior specification

Errors

The following outcomes depend on the stage at which a request is refused:

Status	Common cause
`400`	Trigger dispatch is invalid, or referenced trigger data cannot be loaded for this team
`401`	Credentials are absent, invalid, or have no effective scopes
`403`	Required scope or namespace write access is missing, or API execution is disabled
`404`	The workflow or execution does not exist in your team
`409`	The workflow is inactive, has no promoted version, has a malformed promoted definition, or has no trigger
`422`	Request schema validation failed; this is not the specific cross-team-record response
`429`	A rate limit applied; respect `Retry-After`
`500`	An unexpected server failure occurred

See Errors and Safe Retries and Rate Limits.

Start a run using the execute endpoint with a supported trigger and trigger data. Expect a response containing executionId and a status of queued.
Send a chat turn to a workflow with a manual trigger and receive a response containing executionId, conversationId, and a status of queued.
Poll a run using its execution ID and observe its status and step history, expecting statuses like pending, running, waiting, completed, failed, or canceled.
Submit requests with missing scopes or improper input and confirm expected error responses, such as 403 or 400.
Retry a retained execution with the same body key and confirm the same execution ID. Use a new key for a different intended run; do not change inputs under an existing key.
Check inactive, unpromoted, API-disabled, namespace-denied, trigger-mismatch, and cross-team input cases against the error table.
Confirm run polling contains status and step summaries but no generated reply or step output.

On this page

Workflows API

On this page