Start a run for a platform-managed agent. The platform delegates to the agent's configured runtime and returns immediately with a runId.
Endpoint
POST /api/agents/{agentId}/runs/trigger
Auth: Authorization: Bearer <ingest_api_key>
Eligibility
The agent must satisfy all of:
managed_by = 'platform'status = 'active'allow_external_triggers = true— a per-agent toggle that platform admins flip on the agent's Integration page.
Otherwise the call returns 403.
Request
json
{
"input": {
"url": "https://example.com"
}
}
| Field | Type | Required | Description |
|---|---|---|---|
input | object | no | Merged on top of the agent's saved default input; caller's values win. |
userId | uuid | no | Attribution for runs.created_by. Must be a member of the agent's organization (or a platform admin); unknown / non-member values are dropped silently and the run is still created with no creator. Use this when the caller has already verified the user identity on its side (e.g. a chat zone). |
Response — 200 OK
json
{
"runId": 1234,
"status": "queued"
}
| Field | Type | Description |
|---|---|---|
runId | number | Platform-side run identity. Use this in callbacks and reads. |
status | "queued" | Initial state; transitions to running once the runtime picks it up. |
Errors
| Status | Reason |
|---|---|
401 | Missing or invalid bearer token. |
403 | Agent not eligible (see eligibility above). |
429 | Per-agent rate limit exceeded. |
500 | Runtime invocation failed (e.g. the configured runtime was unreachable). |
SDK
ts
import { triggerRun } from '@cxpa/sdk/agent'
const { runId } = await triggerRun({
baseUrl: process.env.CXPA_API_URL!,
ingestApiKey: process.env.CXPA_INGEST_KEY!,
agentId: 42,
input: { url: 'https://example.com' },
userId: '00000000-0000-4000-8000-000000000000', // optional attribution
})