Start an outbound call
Starts a real call through an assigned outbound number. The call runs the agent live published version at admission; the request carries no configuration and no revision. Optional expected_version_id only refuses an unexpected live version; it cannot select a historical version. The admitted call keeps that version even if a later publication or rollback changes the live version. Requires current admission capacity. Same key/body replays the original call. The response always carries the executed publication identity (published_version_id). A paused or archived agent is refused with agent_not_live (details.state).
Authentication
Create and manage workspace-owned keys through the existing app session routes, outside this public API. Creator and manager identities are audit actors only. Key validity follows workspace policy, expiry and explicit revocation, independently of creator membership. Do not include a workspace-selection header.
Headers
Stable key per logical intent, 1–255 printable characters. Persist it before sending. Retry the same key/body after an uncertain result for 24 hours. A changed body conflicts. Beyond retention, reconcile the resource before retrying; this is not permanent deduplication. Current authorization is rechecked on replay. Evaluation order: authenticate and check current authorization; look up intent; replay its stored receipt before checking the current revision; only a new intent evaluates If-Match and executes. Fingerprint includes method, path, body and original If-Match. A changed request returns idempotency_key_reused. The server stores only a keyed (HMAC) fingerprint, and no error or response ever returns a fingerprint or hash of a request. In-flight intent returns 409 idempotency_in_progress with Retry-After; retry the same intent after reconciliation. Receipts describe that attempt, not current resource state. A replay returns the original status code and body, with the response header Idempotent-Replayed: true.
Request
Optional precondition: refuse if this is not the live version at admission. Does not select an old version.
Flat object of string values. At most 64 keys; each key matches ^[a-z][a-z0-9_]63$. Each value is at most 4096 characters and contains no control characters except tab and newline. The whole object is at most 16 KiB as JSON. Nested objects and non-string values are refused, never converted. Overrides literal defaults; undeclared names are allowed. Credentials are forbidden.
Bounded customer correlation map: at most 16 keys; each key matches ^[a-z][a-z0-9_]63$ (the same form the metadata_key filter accepts); each value at most 512 characters; at most 4 KiB in total. No credential storage. Metadata is not a uniqueness or permanent deduplication guarantee.
Choose an existing number assigned outbound to this agent. Omission selects the sole eligible assignment, or with several the agent’s primary outbound number when it can dial (outbound_primary_agent_ids on the number). Zero eligible numbers, or several with no primary or a primary that cannot dial, refuse admission; never choose arbitrarily.
Response headers
true when this response replays a stored Idempotency-Key result. The status and body equal the original.
Path-absolute URL of the resource to poll, including the API base path. Agent-scoped knowledge creates point to the canonical knowledge source URL.
Response
Number used for this call; null for non-phone calls.
Seconds to wait before the first GET /calls/{call_id}.