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
json
{
"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
json
{
"runId": 1234,
"credentialsToken": "eyJhbGciOiJIUzI1NiJ9.…",
"expiresInSeconds": 3600
}
| 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). |
Errors
See Errors. Common cases: 401 (bad ingest key), 403 (agent not eligible), 429 (rate limit), 422 (validation).
SDK
ts
import { registerRun } from '@cxpa/sdk/agent'
const { runId, credentialsToken } = await registerRun({
baseUrl: process.env.CXPA_API_URL!,
ingestApiKey: process.env.CXPA_INGEST_KEY!,
agentId: 42,
externalRunId: 'run_abc123',
input: { url: 'https://example.com' },
userId: '00000000-0000-4000-8000-000000000000', // optional attribution
})