Skip to main content
POST
Create a WebSocket session

Authorizations

Authorization
string
header
default:$CARTESIA_API_KEY
required

Cartesia API key (sk_car_...). Get one at play.cartesia.ai/keys.

Headers

Cartesia-Version
enum<string>
default:2026-08-14
required

API version header.

Available options:
2026-08-14
Example:

"2026-08-14"

Path Parameters

agent_id
string
required

Unique identifier for the agent.

Minimum string length: 1

Body

application/json
dynamic_variables
object

Trusted values that Cartesia stores on the call and supplies to the agent.

config_overrides
object

Per-call overrides using the same field structure as agent configuration. Omitted fields use the agent's published configuration.

Response

The pre-created call and its browser session token

call_id
string
required

ID of the pre-created call. The session_ready event returns the same value.

url
string<uri>
required

WebSocket URL for this agent. Append the returned session token as the access_token query parameter.

token
string
required

Opaque, short-lived, single-use session token. Do not inspect or log it.

expires_at
string<date-time>
required

Connection deadline, currently four minutes after creation. Use this timestamp rather than calculating the deadline.