Register an externally-triggered run with the platform and receive a short-lived credentials token. Use this when you trigger the runtime directly (not the platform) but still need platform credentials and tracking.
Endpoint
POST /api/agents/{agentId}/runs/register
Auth: Authorization: Bearer <ingest_api_key>
Eligibility
Same as trigger:
managed_by = 'platform'status = 'active'allow_external_triggers = true— flipped on the agent's Integration page by a platform admin.
The run record is created in the running state immediately. There is no queued step — once you have a runId, your runtime is expected to be executing the run.
Request
{
"externalRunId": "run_abc123",
"input": { "url": "https://example.com" },
"metadata": { "source": "scheduler-x" }
}
| Field | Type | Required | Description |
|---|---|---|---|
externalRunId | string | yes | Your runtime-side execution id, 1–255 chars. Idempotency key. |
input | object | no | Input payload mirrored on the platform record. |
metadata | object | no | Free-form metadata stored alongside the run. |
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). |
The endpoint is idempotent on (agentId, externalRunId) — repeating a call with the same external id returns the same runId.
Response — 200 OK
{
"runId": 1234,
"credentialsToken": "eyJhbGciOiJIUzI1NiJ9.…",
"expiresInSeconds": 3600,
"connectionIds": {
"openai": { "integrationId": "openai", "connectionId": "12" },
"google-sheets": { "integrationId": "google-sheets", "connectionId": "13" }
}
}
| Field | Type | Description |
|---|---|---|
runId | number | Platform-side run identity. |
credentialsToken | string? | Short-lived HS256 JWT for /api/credentials/{connectionId}/resolve. |
expiresInSeconds | number? | TTL of the credentials token (typically 3600). |
connectionIds | object? | Map of integration_id → { integrationId, connectionId } for the agent's active connections — the directory the token is spent against. |
credentialsToken and connectionIds are returned together or not at all. An agent with no active connections receives neither, because there would be nothing to resolve. A credential requirement nobody has connected is simply an absent key in the map.
This mirrors what the platform puts in the task payload when it triggers a run itself, so a task can read connections from the same shape on either path.
Errors
See Errors. Common cases: 401 (bad ingest key), 403 (agent not eligible), 429 (rate limit), 422 (validation).
SDK
import { registerRun } from '@cxpa/sdk/agent'
const { runId, credentialsToken } = await registerRun({
baseUrl: process.env.CXPA_API_URL!,
ingestApiKey: process.env.CXPA_REVENUE_CHAT_INGEST_API_KEY!,
agentId: 42,
externalRunId: 'run_abc123',
input: { url: 'https://example.com' },
userId: '00000000-0000-4000-8000-000000000000', // optional attribution
})