> ## Documentation Index > Fetch the complete documentation index at: https://docs.eclatira.com/llms.txt > Use this file to discover all available pages before exploring further. # Create a realtime session > Mints a short-lived (60s), single-use token that authorizes opening exactly one connection to the `/ws/{user_id}` realtime voice/video engine, scoped to the given `agent_id` and `user_id`: the only supported way for an API-key holder to authenticate into that engine (it otherwise only accepts a public-widget-style origin allowlist or a dashboard session token, neither appropriate for a third-party API key). Connect using the returned `ws_url` before `expires_at`; the token is consumed on the first successful connection attempt and cannot be reused, including for reconnects. Mint a fresh one for each connection, including after a dropped connection you want to resume. ## OpenAPI ````yaml /openapi.json post /api/v1/realtime/sessions openapi: 3.1.0 info: title: Eclatira API description: >- Programmatically create calls and batches, manage agents/tools/knowledge, and retrieve conversation analytics. contact: name: Eclatira Support email: contact@eclatira.com version: 1.0.0 servers: - url: https://app.eclatira.com description: API Server security: [] tags: - name: developer-api description: >- The API-key-authenticated developer surface: calls, batches, and agents. Authenticate with `Authorization: Bearer ek_...`. - name: Calls description: Place outbound calls with an agent, check status, list history. - name: Batches description: 'Outbound call campaigns: create, list, inspect, cancel, retry.' - name: Agents description: Create and manage the agents that place and receive calls. - name: Tools description: Custom actions an agent can call mid-call, attached per-agent. - name: MCP Servers description: >- Connect an agent to an external MCP (Model Context Protocol) server so it can call that server's tools, with static or OAuth auth. - name: Knowledge Base description: Upload files and index them into an agent's knowledge base. - name: Realtime description: >- Mint a short-lived session token to open a live voice/video WebSocket connection: the only supported way for an API-key holder to authenticate into /ws/{user_id}. - name: Webhooks description: >- Register a durable callback URL to receive call.completed and batch.completed events for every matching workspace event, and fetch the tenant signing secret used to verify X-Webhook-Signature. - name: developer-api-keys description: >- Account-management routes (create/list/revoke API keys), authenticated via dashboard login, not an API key, since they mint the credentials the rest of the developer API uses. paths: /api/v1/realtime/sessions: post: tags: - Realtime - developer-api summary: Create a realtime session description: |- Mints a short-lived (60s), single-use token that authorizes opening exactly one connection to the `/ws/{user_id}` realtime voice/video engine, scoped to the given `agent_id` and `user_id`: the only supported way for an API-key holder to authenticate into that engine (it otherwise only accepts a public-widget-style origin allowlist or a dashboard session token, neither appropriate for a third-party API key). Connect using the returned `ws_url` before `expires_at`; the token is consumed on the first successful connection attempt and cannot be reused, including for reconnects. Mint a fresh one for each connection, including after a dropped connection you want to resume. operationId: createRealtimeSession requestBody: content: application/json: schema: $ref: '#/components/schemas/V1CreateRealtimeSessionRequest' required: true responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/V1CreateRealtimeSessionResponse' '402': description: >- The tenant's billing status blocks new realtime sessions (e.g. a past_due/unpaid subscription). content: application/json: schema: $ref: '#/components/schemas/V1ErrorResponse' '403': description: >- Either an agent exists with this `agent_id` but it belongs to a different tenant; or `source: "screen"` was requested and this agent has screen sharing disabled, or `source: "camera"` was requested and this agent has the camera disabled. Both flags default to enabled, are reported on `GET /api/v1/agents/{agent_id}` as `realtime.enable_screen_share` / `realtime.enable_webcam`, and can be changed with `PATCH /api/v1/agents/{agent_id}` by sending `{"realtime": {"enable_screen_share": true}}` — they are the same toggles the dashboard agent settings expose. content: application/json: schema: $ref: '#/components/schemas/V1ErrorResponse' '404': description: No agent exists with this `agent_id`. content: application/json: schema: $ref: '#/components/schemas/V1ErrorResponse' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' '429': description: >- Burst-abuse rate limit on session minting, independent of plan tier: 60/hour and 500/day per tenant. Includes a Retry-After header. content: application/json: schema: $ref: '#/components/schemas/V1ErrorResponse' security: - ApiKeyAuth: [] components: schemas: V1CreateRealtimeSessionRequest: properties: agent_id: type: string title: Agent Id user_id: type: string title: User Id source: type: string enum: - audio - text - camera - screen title: Source default: audio variables: additionalProperties: type: string type: object title: Variables default: {} additionalProperties: false type: object required: - agent_id - user_id title: V1CreateRealtimeSessionRequest V1CreateRealtimeSessionResponse: properties: session_token: type: string title: Session Token expires_at: type: string title: Expires At ws_url: type: string title: Ws Url type: object required: - session_token - expires_at - ws_url title: V1CreateRealtimeSessionResponse V1ErrorResponse: properties: error: $ref: '#/components/schemas/V1ErrorDetail' type: object required: - error title: V1ErrorResponse description: |- The error envelope every `developer-api`-tagged route returns for non-2xx responses, including `422`; this overrides FastAPI's default validation-error shape. HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' type: array title: Detail type: object title: HTTPValidationError V1ErrorDetail: properties: type: type: string title: Type code: type: string title: Code message: type: string title: Message param: anyOf: - type: string - type: 'null' title: Param request_id: anyOf: - type: string - type: 'null' title: Request Id type: object required: - type - code - message title: V1ErrorDetail ValidationError: properties: loc: items: anyOf: - type: string - type: integer type: array title: Location msg: type: string title: Message type: type: string title: Error Type input: title: Input ctx: type: object title: Context type: object required: - loc - msg - type title: ValidationError securitySchemes: ApiKeyAuth: type: http scheme: bearer description: >- A long-lived, privileged API key (`ek_...` prefix), minted once from the dashboard. Intended for trusted server-side use only; never expose it in client-side code. Send as `Authorization: Bearer ek_...`. Required by every Calls, Batches, Agents, Tools, MCP Servers, Documents, and Realtime route. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.