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

apiHosted AI, explicit consent

Trigger agent role

POST /api/agents/run

Create a work order for one Agent Teams role. Hosted mode starts Pipeline inference asynchronously. External mode leaves the work order ready for claim-agent-work-order so a coding agent can use its own subscription. Returns { runId, workOrderId }. The strategist has dedicated tools and is rejected here.

Parameters

workspaceId

string

Optional with an API key (inferred from the key).

rolerequired

string

The agent role to run, e.g. scout, researcher, icp, writer, campaign_builder, closer, coach. Not strategist.

task

string

Optional free-text task/guidance for the run.

briefId

string

Campaign brief ID. Required for Scout, campaign_builder, and Writer in external_agent mode so outputs are bound to the current brief version.

tableId

string

Exact table ID. Required for external Researcher, ICP, and Writer work.

rowIds

string[]

Exact row IDs assigned to the external agent. Required for external Researcher, ICP, and Writer work.

outputColumnIds

string[]

Exact output-role column IDs the agent must populate and complete. Required for external Researcher and ICP work.

executionMode

string

Coding-agent tools default to external_agent. Set pipeline_hosted and allowHostedAi=true to explicitly use workspace BYOK inference.

pipeline_hosted | external_agent

allowHostedAi

boolean

Must be true when this operation uses Pipeline hosted inference.

Example

REST requestbash

curl -X POST "https://app.pipeline.help/api/agents/run" \
  -H "Authorization: Bearer $PIPELINE_API_KEY" \
  -H "X-Pipeline-Execution-Policy: hosted-enabled" \
  -H "Content-Type: application/json" \
  -d '{"role":"example","allowHostedAi":true}'

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.