Building a webhook integration? Read the webhook guide for signatures, retries, event schemas, and troubleshooting.

apiProvider-backed

Run workflow

POST /api/agent-workflows/{workflowId}/execute

Execute an explicitly identified saved workflow against a batch of input records. Never use this for a generic content request. Use executionMode=external_agent for ICP/Dream account-first table-only runs: research and scoring pause for claim-agent-work-order and submit-agent-artifact, then continue via delayed-run recovery. Other graphs containing hosted AI require allowHostedAi=true from a hosted-enabled client; external-only clients are rejected before a hosted run is created. Deterministic graphs need no hosted-AI consent. Each record is one row processed by the DAG end-to-end. Execution is fire-and-forget - the route returns 202 with an execution_id immediately; poll list-workflow-runs or get-workflow-run for status.

Parameters

workspaceId

string

Optional workspace ID or slug. Required when this credential can access multiple workspaces and no workspace was configured on the client.

workflowIdrequired

string

Workflow UUID to execute.

executionMode

string

external_agent hands ICP scoring and research to claimable Codex work orders. No hosted AI. Supported table-only graphs only.

external_agent | pipeline_hosted

runMode

string

No description.

pilot | full

pilotLimit

number

Maximum people across the whole source fanout.

resumeExecutionId

string

Resume a failed connections import from its saved checkpoint. An expired cursor requires a fresh run instead.

cancelExecutionId

string

Stop an active connections import. An in-flight provider read cannot be recalled.

allowHostedAi

boolean

Explicit consent for hosted AI nodes. Requires a hosted-enabled client.

records

object[]

Array of input records, one per row to process. Shape matches the workflow's expected input schema.

Example

REST requestbash

curl -X POST "https://app.pipeline.help/api/agent-workflows/00000000-0000-4000-8000-000000000000/execute" \
  -H "Authorization: Bearer $PIPELINE_API_KEY"

Response

The operation is available, but its typed response schema has not been published yet.

HTTP errors

401: Missing or invalid API key.
403: Authenticated but not permitted for the workspace or resource.
404: The requested resource was not found.