> ## Documentation Index > Fetch the complete documentation index at: https://docs.roark.ai/llms.txt > Use this file to discover all available pages before exploring further. # Start a conversation with an agent > Starts a voice conversation (`modality: voice`) or chat (`modality: chat`) with this Roark-hosted agent and returns its id right away. `channel: web` is a conversation in a browser on your site. Call this endpoint from your server, never the browser: it needs your API key. Give the page only `web.clientToken`; the web SDK spends it to join from one of `allowedOrigins` before `web.clientTokenExpiresAt`. Read it back with `GET /v1/conversation/{conversationId}` straight away: `PENDING` until the browser joins, `IN_PROGRESS`, then `ENDED`. One nobody joins ends without ever starting and is never billed. Starting a voice conversation needs `call:create`, a chat `chat:create`, and the agent a published version that takes that kind. ## OpenAPI ````yaml /api-reference/openapi.documented.json post /v1/agent/{agentId}/conversations openapi: 3.1.0 info: title: Roark Analytics API description: >- The Roark Analytics API gives you access to the same API that powers the award winning Roark Analytics platform. version: 1.0.0 servers: - description: Production url: https://api.roark.ai security: - Bearer: [] tags: - name: Agent - name: Customer - name: Agent Endpoint - name: Tool - name: Phone Number - name: Call - name: Chat - name: Conversation - name: Metric - name: Metric Policy - name: Metric Collection Job - name: Customer Flow - name: Customer Flow Edge Case - name: Simulation - name: Simulation Persona - name: Simulation Environment - name: Simulation Scenario - name: Simulation Run Plan - name: Simulation Template - name: Simulation Audio Clip - name: Simulation Run Plan Job - name: Simulation Job - name: HTTP Request Definition - name: Webhook - name: Issue - name: Autoimprove - name: Agent Config - name: Knowledge Base - name: Calendar Integration - name: MCP Server Integration - name: Config - name: Organization Project - name: Organization Project Member - name: Organization Project API Key - name: Organization Config - name: CLI Auth - name: Me - name: Project - name: Usage - name: Analytics - name: Dashboard - name: Live Report - name: Benchmark - name: Health - name: Campaign Credit paths: /v1/agent/{agentId}/conversations: post: tags: - Agent summary: Start a conversation with an agent description: >- Starts a voice conversation (`modality: voice`) or chat (`modality: chat`) with this Roark-hosted agent and returns its id right away. `channel: web` is a conversation in a browser on your site. Call this endpoint from your server, never the browser: it needs your API key. Give the page only `web.clientToken`; the web SDK spends it to join from one of `allowedOrigins` before `web.clientTokenExpiresAt`. Read it back with `GET /v1/conversation/{conversationId}` straight away: `PENDING` until the browser joins, `IN_PROGRESS`, then `ENDED`. One nobody joins ends without ever starting and is never billed. Starting a voice conversation needs `call:create`, a chat `chat:create`, and the agent a published version that takes that kind. operationId: postV1AgentByAgentIdConversations parameters: - in: path name: agentId schema: type: string format: uuid required: true requestBody: content: application/json: schema: $ref: '#/components/schemas/CreateAgentConversationInput' responses: '201': description: The conversation, waiting for the browser to join. content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/AgentConversationCreated' required: - data '400': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Validation error example: type: validation code: invalid_parameter message: The request was invalid param: email description: Bad Request '401': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Authentication error example: type: authentication code: unauthorized message: Authentication required description: Unauthorized '403': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Permission error example: type: forbidden code: permission_denied message: You do not have permission to access this resource description: Forbidden '404': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Not found error example: type: not_found code: resource_not_found message: The requested resource could not be found description: Not Found '409': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Conflict error example: type: conflict code: resource_in_use message: The resource is in use and cannot be deleted description: Conflict '429': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Rate limit error example: type: rate_limit code: too_many_requests message: Rate limit exceeded description: Too Many Requests '500': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Server error example: type: internal code: internal_error message: Internal server error description: Internal Server Error x-codeSamples: - lang: JavaScript source: |- import Roark from '@roarkanalytics/sdk'; const client = new Roark({ bearerToken: process.env['ROARK_API_BEARER_TOKEN'], // This is the default and can be omitted }); const agentConversation = await client.agentConversation.create( '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e', { allowedOrigins: ['https://app.example.com'], channel: 'web', modality: 'voice' }, ); console.log(agentConversation.data); - lang: Python source: |- import os from roark_analytics import Roark client = Roark( bearer_token=os.environ.get("ROARK_API_BEARER_TOKEN"), # This is the default and can be omitted ) agent_conversation = client.agent_conversation.create( agent_id="182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e", allowed_origins=["https://app.example.com"], channel="web", modality="voice", ) print(agent_conversation.data) components: schemas: CreateAgentConversationInput: oneOf: - $ref: '#/components/schemas/CreateAgentWebConversationInput' discriminator: propertyName: channel mapping: web: '#/components/schemas/CreateAgentWebConversationInput' AgentConversationCreated: oneOf: - $ref: '#/components/schemas/AgentWebConversationCreated' discriminator: propertyName: channel mapping: web: '#/components/schemas/AgentWebConversationCreated' ErrorResponse: type: object properties: type: type: string enum: - validation - authentication - forbidden - not_found - conflict - payment_required - rate_limit - internal description: The error type category examples: - validation - authentication code: type: string description: Machine-readable error code identifier examples: - invalid_parameter - missing_required_field - unauthorized message: type: string description: Human-readable error message examples: - The request was invalid - Authentication required param: type: string description: The parameter that caused the error (if applicable) examples: - email - user_id details: description: Additional error context information required: - type - code - message CreateAgentWebConversationInput: type: object properties: modality: type: string enum: - voice - chat - call description: '`voice` or `chat`. The agent must have that modality turned on.' example: voice channel: type: string const: web description: >- How it is reached. `web`: in a browser on one of `allowedOrigins`, joined with the web SDK. allowedOrigins: type: array items: type: string minLength: 1 maxLength: 255 minItems: 1 maxItems: 10 description: >- The origins your page may join from, exactly as the browser sends them: https only (http on localhost for development), no paths or wildcards. example: - https://app.example.com clientTokenTtlSeconds: type: integer minimum: 30 maximum: 600 description: How long the browser has to join, in seconds. Default 120. example: 120 required: - modality - channel - allowedOrigins AgentWebConversationCreated: type: object properties: id: type: string format: uuid description: >- The conversation id. Read it with `GET /v1/conversation/{conversationId}`; once it is recorded it is also its call or chat id, and a call's tools get it as `{{conversation.id}}`. agentId: type: string format: uuid modality: type: string enum: - voice - chat channel: type: string const: web status: type: string const: PENDING description: Waiting for the browser to join. web: $ref: '#/components/schemas/AgentWebJoin' createdAt: type: string description: When it was created (ISO 8601). required: - id - agentId - modality - channel - status - web - createdAt AgentWebJoin: type: object properties: clientToken: type: string description: >- A single-use token for the browser, and the only thing your page should get. The web SDK spends it to join from one of `allowedOrigins` before `clientTokenExpiresAt`, and runs the connection itself. It is not an API key. clientTokenExpiresAt: type: string description: When the browser can no longer join (ISO 8601). example: '2026-11-10T09:02:00.000Z' allowedOrigins: type: array items: type: string description: The origins the browser may join from, normalized. required: - clientToken - clientTokenExpiresAt - allowedOrigins description: What a browser needs to join the conversation. securitySchemes: Bearer: type: http scheme: bearer bearerFormat: JWT ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.