> ## 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 chat > Create a new chat with segments (messages and tool invocations) ## OpenAPI ````yaml /api-reference/openapi.documented.json post /v1/chat 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/chat: post: tags: - Chat summary: Create a chat description: Create a new chat with segments (messages and tool invocations) operationId: postV1Chat requestBody: content: application/json: schema: $ref: '#/components/schemas/ChatCreate' responses: '200': content: application/json: schema: type: object properties: data: type: object properties: id: type: string format: uuid description: Unique identifier for the chat example: 550e8400-e29b-41d4-a716-446655440000 projectId: type: string format: uuid description: ID of the project this chat belongs to example: 660e8400-e29b-41d4-a716-446655440001 organizationId: type: string format: uuid description: ID of the organization this chat belongs to example: 770e8400-e29b-41d4-a716-446655440002 title: type: - string - 'null' description: Auto-generated title for the chat based on content example: Account assistance request summary: type: - string - 'null' description: Auto-generated summary of the chat conversation example: >- Customer inquired about account balance and recent transactions startTimestamp: type: string description: Timestamp when the chat started example: '2024-01-15T10:00:00Z' endTimestamp: type: string description: Timestamp when the chat ended example: '2024-01-15T10:30:00Z' durationMs: type: number description: Duration of the chat in milliseconds example: 1800000 createdAt: type: - string - 'null' description: Timestamp when the chat record was created example: '2024-01-15T10:31:00Z' updatedAt: type: - string - 'null' description: Timestamp when the chat record was last updated example: '2024-01-15T10:31:00Z' simulationJobId: type: - string - 'null' format: uuid description: >- ID of the simulation job if this chat was generated by a simulation example: 880e8400-e29b-41d4-a716-446655440003 simulationRunPlanJobId: type: - string - 'null' format: uuid description: >- ID of the simulation run plan job that this chat belongs to (if applicable) example: 990e8400-e29b-41d4-a716-446655440004 agents: type: - array - 'null' items: type: object properties: id: type: string format: uuid required: - id description: Agent information example: - id: 550e8400-e29b-41d4-a716-446655440000 customers: type: - array - 'null' items: type: object properties: phoneNumberE164: type: - string - 'null' label: type: - string - 'null' description: Customer information example: - phoneNumberE164: null label: web-visitor-abc123 properties: type: - object - 'null' additionalProperties: path: /v1/integrations/livekit-sdk/chunk-upload-url description: Custom properties associated with the chat example: source: web region: US policyIds: type: - array - 'null' items: type: string format: uuid description: >- IDs of metric policies that have been applied to this chat example: - 550e8400-e29b-41d4-a716-446655440000 externalId: type: - string - 'null' description: >- Caller-supplied correlation ID echoed back from the create request, if any was provided example: session-abc-123 required: - id - projectId - organizationId - startTimestamp - endTimestamp - durationMs title: ChatResponse description: Response containing the chat information required: - data description: Chat 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 - validation error '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 components: schemas: ChatCreate: type: object properties: startTimestamp: type: string description: When the chat started (ISO 8601 format) endTimestamp: type: string description: When the chat ended (ISO 8601 format) messages: type: array items: anyOf: - $ref: '#/components/schemas/ChatMessageAgent' - $ref: '#/components/schemas/ChatMessageCustomer' description: Ordered list of messages exchanged during the chat 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 startTimestamp: type: string description: >- When the tool was invoked (ISO 8601). Must fall within the chat time range. endTimestamp: type: string description: >- When the tool execution completed (ISO 8601). 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 - startTimestamp description: List of tool invocations made during the chat properties: type: object additionalProperties: path: /v1/integrations/livekit-sdk/chunk-upload-url description: >- Custom properties to include with the chat. These can be used for filtering and will show in the chat details page example: source: web region: US sessionId: abc123 traceId: type: - string - 'null' description: >- Optional OpenTelemetry trace ID for the chat. Surfaces the chat in the tracing tab. example: 4bf92f3577b34da6a3ce929d0e0e4736 externalId: type: string maxLength: 255 description: >- A stable identifier from your own system (e.g. session ID, conversation ID) used to correlate this chat 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/ChatAgentIdentificationByRoarkId' - $ref: '#/components/schemas/ChatAgentIdentificationByName' - $ref: '#/components/schemas/ChatAgentIdentificationByCustomId' - type: object properties: prompt: type: object properties: resolvedPrompt: type: string description: The agent's system prompt used during this chat required: - resolvedPrompt description: Agent's prompt configuration (optional) description: >- Single agent participating in the chat. Use this for the simpler API when you have only one agent. agents: type: array items: allOf: - anyOf: - $ref: '#/components/schemas/ChatAgentIdentificationByRoarkId' - $ref: '#/components/schemas/ChatAgentIdentificationByName' - $ref: '#/components/schemas/ChatAgentIdentificationByCustomId' - type: object properties: prompt: type: object properties: resolvedPrompt: type: string description: The agent's system prompt used during this chat required: - resolvedPrompt description: Agent's prompt configuration (optional) description: >- Agent participating in the chat with their identification and prompt description: >- Agents participating in the chat. Each agent requires identification and prompt information. customer: type: object properties: label: type: - string - 'null' description: >- Label to identify this customer in the chat (e.g., "user-01", "anonymous-visitor") phoneNumberE164: type: - string - 'null' description: >- Customer phone number in E.164 format (e.g., +14155551234), optional for chat customers required: - phoneNumberE164 description: >- Single customer participating in the chat. Use this for the 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 chat (e.g., "user-01", "anonymous-visitor") phoneNumberE164: type: - string - 'null' description: >- Customer phone number in E.164 format (e.g., +14155551234), optional for chat customers required: - phoneNumberE164 description: Customer participating in the chat description: Customers participating in the chat. required: - startTimestamp - endTimestamp - messages description: >- Chat 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 ChatMessageAgent: type: object properties: role: type: string const: AGENT description: The agent sent this message text: type: string minLength: 1 description: Message content languageCode: type: string description: ISO language code (e.g., "en") startTimestamp: type: string description: >- When the message was sent (ISO 8601). Must fall within the chat time range. endTimestamp: type: string description: >- When the message finished sending (ISO 8601). For instant messages, can equal startTimestamp. 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 sent this message - used to match which agent from the agents array this message belongs to required: - role - text - startTimestamp ChatMessageCustomer: type: object properties: role: type: string const: CUSTOMER description: The customer sent this message text: type: string minLength: 1 description: Message content languageCode: type: string description: ISO language code (e.g., "en") startTimestamp: type: string description: >- When the message was sent (ISO 8601). Must fall within the chat time range. endTimestamp: type: string description: >- When the message finished sending (ISO 8601). For instant messages, can equal startTimestamp. customer: type: object properties: phoneNumberE164: type: string description: Customer phone number in E.164 format label: type: string description: Customer label description: >- Metadata about the customer that sent this message - used to match which customer from the customers array this message belongs to required: - role - text - startTimestamp ChatAgentIdentificationByRoarkId: type: object properties: roarkId: type: string format: uuid description: Existing Roark agent ID required: - roarkId ChatAgentIdentificationByName: 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 ChatAgentIdentificationByCustomId: type: object properties: customId: type: string description: Existing custom ID for a Roark agent required: - customId securitySchemes: Bearer: type: http scheme: bearer bearerFormat: JWT ````