> ## 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. # Create a call > Create a new call with recording, transcript, agents, and customers ## OpenAPI ````yaml /api-reference/openapi.documented.json post /v1/call 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: Agent Endpoint - name: Call - name: Chat - name: Metric - name: Metric Policy - name: Metric Collection Job - name: Simulation Persona - name: Simulation Scenario - name: Simulation Run Plan - name: Simulation Run Plan Job - name: Simulation Job - name: HTTP Request Definition - name: Webhook - name: Issue - name: Knowledge Base - name: Call Analysis - name: Health paths: /v1/call: post: tags: - Call summary: Create a call description: Create a new call with recording, transcript, agents, and customers operationId: postV1Call requestBody: content: application/json: schema: $ref: '#/components/schemas/CallCreate' responses: '200': content: application/json: schema: type: object properties: data: type: object properties: id: type: string format: uuid description: Unique identifier for the call example: 550e8400-e29b-41d4-a716-446655440000 projectId: type: string format: uuid description: ID of the project this call belongs to example: 660e8400-e29b-41d4-a716-446655440001 status: type: - string - 'null' enum: - RINGING - IN_PROGRESS - ENDED callDirection: type: string enum: - INBOUND - OUTBOUND description: Direction of the call (inbound or outbound) example: INBOUND startedAt: type: string description: Timestamp when the call started example: '2024-01-15T10:00:00Z' agents: type: - array - 'null' items: type: object properties: id: type: string format: uuid endpoint: type: - object - 'null' properties: id: type: string format: uuid environment: type: string phoneNumberE164: type: - string - 'null' required: - id - environment required: - id customers: type: - array - 'null' items: type: object properties: phoneNumberE164: type: - string - 'null' label: type: - string - 'null' createdAt: type: - string - 'null' externalId: type: - string - 'null' required: - id - projectId - status - callDirection - startedAt - agents - customers - createdAt - externalId title: CallCreateResponse description: Response after creating a call required: - data description: Call created successfully '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 '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 call = await client.call.create({ callDirection: 'INBOUND', interfaceType: 'PHONE', recordingUrl: 'https://example.com', startedAt: 'startedAt', }); console.log(call.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 ) call = client.call.create( call_direction="INBOUND", interface_type="PHONE", recording_url="https://example.com", started_at="startedAt", ) print(call.data) components: schemas: CallCreate: type: object properties: recordingUrl: type: string format: uri description: >- URL of source recording (must be an accessible WAV, MP3, MP4, or OGG file). Can be a signed URL. stereoRecordingUrl: type: string format: uri description: >- URL of source stereo recording. Must be accessible. Can be a signed URL. Supported formats: WAV, MP3, MP4, OGG. startedAt: type: string description: When the call started (ISO 8601 format) interfaceType: type: string enum: - PHONE - WEB description: Interface type of the call (PHONE or WEB) callDirection: type: string enum: - INBOUND - OUTBOUND description: Direction of the call (INBOUND or OUTBOUND) endedStatus: type: string enum: - PARTICIPANTS_DID_NOT_SPEAK - AGENT_DID_NOT_ANSWER - AGENT_DID_NOT_SPEAK - AGENT_STOPPED_SPEAKING - AGENT_ENDED_CALL - AGENT_TRANSFERRED_CALL - AGENT_BUSY - AGENT_ERROR - CUSTOMER_ENDED_CALL - VOICE_MAIL_REACHED - SILENCE_TIME_OUT - PHONE_CALL_PROVIDER_CONNECTION_ERROR - CUSTOMER_DID_NOT_ANSWER - CUSTOMER_DID_NOT_SPEAK - CUSTOMER_STOPPED_SPEAKING - CUSTOMER_BUSY - DIAL_ERROR - MAX_DURATION_REACHED - UNKNOWN description: High-level call end status, indicating how the call terminated transcript: type: array items: anyOf: - $ref: '#/components/schemas/TranscriptEntryAgent' - $ref: '#/components/schemas/TranscriptEntryCustomer' description: List of transcript entries made during the call toolInvocations: type: array items: type: object properties: name: type: string description: Name of the tool that was invoked description: type: string description: Description of when the tool should be invoked parameters: type: object additionalProperties: anyOf: - type: object properties: description: type: string type: type: string enum: - string - number - boolean value: path: /v1/integrations/livekit-sdk/chunk-upload-url - path: /v1/integrations/livekit-sdk/chunk-upload-url description: Parameters provided to the tool during invocation result: anyOf: - type: string - type: object additionalProperties: path: /v1/integrations/livekit-sdk/chunk-upload-url description: >- Result returned by the tool after execution. Can be a string or a JSON object startOffsetMs: type: integer minimum: 0 maximum: 2147483647 description: >- Offset in milliseconds from the start of the call when the tool was invoked endOffsetMs: type: integer minimum: 0 maximum: 2147483647 description: >- Offset in milliseconds from the start of the call when the tool execution completed. Used to calculate duration of the tool execution agent: type: object properties: roarkId: type: string format: uuid description: The Roark ID of the agent customId: type: string description: The custom ID set on the agent description: >- Metadata about the agent that invoked this tool - used to match which agent from the agents array this tool invocation belongs to required: - name - parameters - result - startOffsetMs description: List of tool invocations made during the call properties: type: object additionalProperties: path: /v1/integrations/livekit-sdk/chunk-upload-url description: >- Custom properties to include with the call. These can be used for filtering and will show in the call details page vapiCallId: type: string format: uuid description: >- The Vapi call ID (UUID) to link this call with OpenTelemetry trace data from Vapi. Used for matching calls with OTEL traces. livekitRoomId: type: string maxLength: 255 description: >- The LiveKit Cloud room ID to link this call with OpenTelemetry trace data from LiveKit. Used for matching calls with OTEL traces. externalId: type: string maxLength: 255 description: >- A stable identifier from your own system (e.g. session ID, conversation ID) used to correlate this call with OpenTelemetry traces. Set the same value as a `roark.external_id` span or resource attribute on your traces and the matching trace will be linked automatically. Must be unique within a project. agent: allOf: - anyOf: - $ref: '#/components/schemas/AgentIdentificationByRoarkId' - $ref: '#/components/schemas/AgentIdentificationByName' - $ref: '#/components/schemas/AgentIdentificationByCustomId' - type: object properties: endpoint: anyOf: - $ref: '#/components/schemas/AgentEndpointById' - $ref: '#/components/schemas/AgentEndpointByValue' description: Endpoint configuration for this agent (optional) prompt: type: object properties: resolvedPrompt: type: string description: The agent's system prompt used during this call required: - resolvedPrompt description: Agent's prompt configuration (optional) description: >- Single agent participating in the call. Use this for simpler API when you have only one agent. agents: type: array items: allOf: - anyOf: - $ref: '#/components/schemas/AgentIdentificationByRoarkId' - $ref: '#/components/schemas/AgentIdentificationByName' - $ref: '#/components/schemas/AgentIdentificationByCustomId' - type: object properties: endpoint: anyOf: - $ref: '#/components/schemas/AgentEndpointById' - $ref: '#/components/schemas/AgentEndpointByValue' description: Endpoint configuration for this agent (optional) prompt: type: object properties: resolvedPrompt: type: string description: The agent's system prompt used during this call required: - resolvedPrompt description: Agent's prompt configuration (optional) description: Agent participating in the call with their endpoint and prompt description: >- Agents participating in the call. Each agent requires identification and prompt information. customer: type: object properties: label: type: - string - 'null' description: >- Label to identify this customer in the transcript (e.g., "speaker-01", "speaker-02") phoneNumberE164: type: - string - 'null' description: Customer phone number in E.164 format (e.g., +14155551234) required: - phoneNumberE164 description: >- Single customer participating in the call. Use this for simpler API when you have only one customer. customers: type: array items: type: object properties: label: type: - string - 'null' description: >- Label to identify this customer in the transcript (e.g., "speaker-01", "speaker-02") phoneNumberE164: type: - string - 'null' description: Customer phone number in E.164 format (e.g., +14155551234) required: - phoneNumberE164 description: Customer participating in the call description: Customers participating in the call. required: - recordingUrl - startedAt - interfaceType - callDirection description: >- Call creation payload. Supports singular (agent/customer) or plural (agents/customers) formats. ErrorResponse: type: object properties: type: type: string enum: - validation - authentication - forbidden - not_found - conflict - 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 TranscriptEntryAgent: type: object properties: startOffsetMs: type: integer minimum: 0 maximum: 2147483647 endOffsetMs: type: integer minimum: 0 maximum: 2147483647 text: type: string languageCode: type: string payload: type: - object - 'null' additionalProperties: path: /v1/integrations/livekit-sdk/chunk-upload-url role: type: string const: AGENT agent: type: object properties: roarkId: type: string format: uuid description: The Roark ID of the agent customId: type: string description: The custom ID set on the agent description: >- Metadata about the agent that spoke this turn - used to match which agent from the `agents` array this transcript entry belongs to required: - startOffsetMs - endOffsetMs - text - role TranscriptEntryCustomer: type: object properties: startOffsetMs: type: integer minimum: 0 maximum: 2147483647 endOffsetMs: type: integer minimum: 0 maximum: 2147483647 text: type: string languageCode: type: string payload: type: - object - 'null' additionalProperties: path: /v1/integrations/livekit-sdk/chunk-upload-url role: type: string const: CUSTOMER customer: type: object properties: phoneNumberE164: type: string description: >- The phone number of the customer in E.164 format, matching the `phoneNumberE164` field on the `customers` array when creating the call label: type: string description: >- Label matching the `label` field on the `customers` array when creating the call description: >- Metadata about the customer that spoke this turn - used to match which customer from the `customers` array this transcript entry belongs to required: - startOffsetMs - endOffsetMs - text - role AgentIdentificationByRoarkId: type: object properties: roarkId: type: string format: uuid description: Existing Roark agent ID required: - roarkId AgentIdentificationByName: type: object properties: name: type: string description: Agent name description: type: string description: Agent description customId: type: string description: Agent custom ID required: - name description: >- Find existing by customId if provided, otherwise reuse exact project name match before creating AgentIdentificationByCustomId: type: object properties: customId: type: string description: Existing custom ID for a Roark agent required: - customId AgentEndpointById: type: object properties: id: type: string format: uuid description: Existing Roark endpoint ID required: - id AgentEndpointByValue: type: object properties: value: type: string description: Endpoint value (phone number in E.164 format or websocket URL) type: type: string description: Type of endpoint (phone or websocket) direction: type: string description: Call direction for this endpoint required: - value - type description: Lookup or create endpoint if one with these values does not exist securitySchemes: Bearer: type: http scheme: bearer bearerFormat: JWT ````