---
title: "Create a chat"
method: POST
path: "/v1/chat"
tags: ["Chat"]
---

# Create a chat

`POST /v1/chat`

Create a new chat with segments (messages and tool invocations)

## Request body

- ChatCreate — Chat creation payload. Supports singular (agent/customer) or plural (agents/customers) formats.
  - `startTimestamp` string, required — When the chat started (ISO 8601 format)
  - `endTimestamp` string, required — When the chat ended (ISO 8601 format)
  - `messages` union[], required — Ordered list of messages exchanged during the chat
    - union
      - ChatMessageAgent
        - `role` 'AGENT', required — The agent sent this message
        - `text` string, required — Message content
        - `languageCode` string — ISO language code (e.g., "en")
        - `startTimestamp` string, required — When the message was sent (ISO 8601). Must fall within the chat time range.
        - `endTimestamp` string — When the message finished sending (ISO 8601). For instant messages, can equal startTimestamp.
        - `agent` object — Metadata about the agent that sent this message - used to match which agent from the agents array this message belongs to
          - `roarkId` string, uuid
          - `customId` string
      - ChatMessageCustomer
        - `role` 'CUSTOMER', required — The customer sent this message
        - `text` string, required — Message content
        - `languageCode` string — ISO language code (e.g., "en")
        - `startTimestamp` string, required — When the message was sent (ISO 8601). Must fall within the chat time range.
        - `endTimestamp` string — When the message finished sending (ISO 8601). For instant messages, can equal startTimestamp.
        - `customer` object — Metadata about the customer that sent this message - used to match which customer from the customers array this message belongs to
          - `phoneNumberE164` string — Customer phone number in E.164 format
          - `label` string — Customer label
  - `toolInvocations` object[] — List of tool invocations made during the chat
    - `name` string, required — Name of the tool that was invoked
    - `description` string — Description of when the tool should be invoked
    - `parameters` object, required — Parameters provided to the tool during invocation
    - `result` union, required — Result returned by the tool after execution. Can be a string or a JSON object
      - string
      - object
    - `startTimestamp` string, required — When the tool was invoked (ISO 8601). Must fall within the chat time range.
    - `endTimestamp` string — When the tool execution completed (ISO 8601). Used to calculate duration of the tool execution.
    - `agent` object — Metadata about the agent that invoked this tool - used to match which agent from the agents array this tool invocation belongs to
      - `roarkId` string, uuid
      - `customId` string
  - `properties` object — Custom properties to include with the chat. These can be used for filtering and will show in the chat details page
  - `traceId` string, nullable — Optional OpenTelemetry trace ID for the chat. Surfaces the chat in the tracing tab.
  - `agent` union
    - object — Single agent participating in the chat. Use this for the simpler API when you have only one agent.
      - `roarkId` string, uuid, required — Existing Roark agent ID
      - `prompt` object — Agent's prompt configuration (optional)
        - `resolvedPrompt` string, required — The agent's system prompt used during this chat
    - object — Single agent participating in the chat. Use this for the simpler API when you have only one agent.
      - `name` string, required — Agent name
      - `description` string — Agent description
      - `customId` string — Agent custom ID
      - `prompt` object — Agent's prompt configuration (optional)
        - `resolvedPrompt` string, required — The agent's system prompt used during this chat
    - object — Single agent participating in the chat. Use this for the simpler API when you have only one agent.
      - `customId` string, required — Existing custom ID for a Roark agent
      - `prompt` object — Agent's prompt configuration (optional)
        - `resolvedPrompt` string, required — The agent's system prompt used during this chat
  - `agents` union[] — Agents participating in the chat. Each agent requires identification and prompt information.
    - union
      - object — Agent participating in the chat with their identification and prompt
        - `roarkId` string, uuid, required — Existing Roark agent ID
        - `prompt` object — Agent's prompt configuration (optional)
          - `resolvedPrompt` string, required — The agent's system prompt used during this chat
      - object — Agent participating in the chat with their identification and prompt
        - `name` string, required — Agent name
        - `description` string — Agent description
        - `customId` string — Agent custom ID
        - `prompt` object — Agent's prompt configuration (optional)
          - `resolvedPrompt` string, required — The agent's system prompt used during this chat
      - object — Agent participating in the chat with their identification and prompt
        - `customId` string, required — Existing custom ID for a Roark agent
        - `prompt` object — Agent's prompt configuration (optional)
          - `resolvedPrompt` string, required — The agent's system prompt used during this chat
  - `customer` object — Single customer participating in the chat. Use this for the simpler API when you have only one customer.
    - `label` string, nullable — Label to identify this customer in the chat (e.g., "user-01", "anonymous-visitor")
    - `phoneNumberE164` string, nullable, required — Customer phone number in E.164 format (e.g., +14155551234), optional for chat customers
  - `customers` object[] — Customers participating in the chat.
    - `label` string, nullable — Label to identify this customer in the chat (e.g., "user-01", "anonymous-visitor")
    - `phoneNumberE164` string, nullable, required — Customer phone number in E.164 format (e.g., +14155551234), optional for chat customers

## Response `200`

Chat created successfully

- object
  - `data` object, required — Response containing the created chat information
    - `id` string, uuid, required — Unique identifier for the chat
    - `projectId` string, uuid, required — ID of the project this chat belongs to
    - `organizationId` string, uuid, required — ID of the organization this chat belongs to
    - `title` string, nullable — Auto-generated title for the chat based on content
    - `summary` string, nullable — Auto-generated summary of the chat conversation
    - `startTimestamp` string, required — Timestamp when the chat started
    - `endTimestamp` string, required — Timestamp when the chat ended
    - `durationMs` number, required — Duration of the chat in milliseconds
    - `createdAt` string, nullable — Timestamp when the chat record was created
    - `updatedAt` string, nullable — Timestamp when the chat record was last updated

## Other responses

- `400` — Bad request - validation error
- `401` — Unauthorized
- `403` — Forbidden
- `429` — Too Many Requests
- `500` — Internal Server Error

---

[API](https://skmtc.net/roarkhq/apis/roark-analytics-api.md) · [All operations](https://skmtc.net/roarkhq/apis/roark-analytics-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/roarkhq/roark-analytics-api/revisions/83528d3618ef/schema)