Create Conversation

Creates a new conversation session with an AI agent.

Endpoint

POST /v1/conversations

Authentication

Requires a valid API key or user authentication token.

Request Body

{
  "agent_id": "string",
  "title": "string"
}

Request Fields

Field	Type	Required	Description
agent_id	string	Yes	ID of the agent to converse with
title	string	No	Title of the conversation (default: "New Conversation")

Response

Returns the created conversation object with LiveKit connection details.

Response Format

{
  "id": "string",
  "agent_id": "string",
  "title": "string",
  "created_at": "datetime",
  "updated_at": "datetime",
  "created_by": "string",
  "status": "string",
  "room_name": "string",
  "room_url": "string",
  "token": "string"
}

Response Fields

Field	Type	Description
id	string	Unique identifier for the conversation
agent_id	string	ID of the agent participating in the conversation
title	string	Title of the conversation
created_at	datetime	When the conversation was created
updated_at	datetime	When the conversation was last updated
created_by	string	ID of the user who created the conversation
status	string	Current status ("active", "completed")
room_name	string	LiveKit room identifier
room_url	string	WebSocket URL for LiveKit connection
token	string	Authentication token for the room

Example Request

curl -X POST "https://api.krosai.com/v1/conversations" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "title": "Product Support Session"
  }'

Example Response

{
  "id": "conv-b2c3d4e5-f6g7-8901-bcde-fg2345678901",
  "agent_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "title": "Product Support Session",
  "created_at": "2023-07-10T15:30:00Z",
  "updated_at": "2023-07-10T15:30:00Z",
  "created_by": "user-12345",
  "status": "active",
  "room_name": "conv-b2c3d4e5-f6g7-8901-bcde-fg2345678901",
  "room_url": "wss://livekit.krosai.com/room/conv-b2c3d4e5-f6g7-8901-bcde-fg2345678901",
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Error Responses

Status Code	Description
400	Bad Request - Invalid input data
401	Unauthorized - Invalid or missing API key
403	Forbidden - Not authorized to use this agent
404	Not Found - Agent not found
500	Internal Server Error

Notes

• A new room is automatically created for the conversation

• The agent joins the room when the first user connects

• The conversation status starts as "active"

• All messages in the conversation are automatically recorded

• The connection token has a limited validity period