Conversations API

Log and retrieve conversations.

Create Conversation

POST /api/v1/conversations

Request Body

{
  "promptId": "prompt_123",
  "content": "User: Hello, I need help\nAssistant: Hi! How can I help you today?",
  "status": "completed",
  "llmModel": "gpt-4o"
}

Required Fields

Field	Type	Description
promptId	string	Associated prompt ID
content	string	Conversation transcript (see Content Format)

Optional Fields

Field	Type	Description
status	string	completed, abandoned, in_progress
llmModel	string	Model used
companyName	string	Customer company name
idempotencyKey	string	Unique key to prevent duplicate submissions (see Idempotency)

Response

{
  "id": "conv_456",
  "promptId": "prompt_123",
  "status": "completed",
  "createdAt": "2025-01-20T14:30:00Z"
}

Status: 201 Created

List Conversations

GET /api/v1/conversations

Query Parameters

Parameter	Type	Description
promptId	string	Filter by prompt
status	string	Filter by status
hasInsights	boolean	Filter to conversations with insights
limit	number	Max results (default: 20)
offset	number	Pagination offset

Response

{
  "data": [
    {
      "id": "conv_456",
      "promptId": "prompt_123",
      "status": "completed",
      "hasInsights": true,
      "createdAt": "2025-01-20T14:30:00Z"
    }
  ],
  "pagination": {
    "total": 150,
    "limit": 20,
    "offset": 0
  }
}

Get Conversation

GET /api/v1/conversations/:id

Query Parameters

Parameter	Type	Description
includeInsights	boolean	Include insights (default: true)

Response

{
  "id": "conv_456",
  "promptId": "prompt_123",
  "content": "User: Hello...\nAssistant: Hi!...",
  "status": "completed",
  "llmModel": "gpt-4o",
  "insights": {
    "sentiment": "positive",
    "taskCompleted": true,
    "topics": ["greeting", "product inquiry"],
    "summary": "User asked about product availability..."
  },
  "createdAt": "2025-01-20T14:30:00Z"
}

Get Conversation Insights

GET /api/v1/conversations/:id/insights

Response

{
  "conversationId": "conv_456",
  "sentiment": "positive",
  "sentimentScore": 0.82,
  "taskCompleted": true,
  "topics": ["greeting", "product inquiry", "availability"],
  "summary": "User inquired about product availability. Agent provided accurate information and the user was satisfied.",
  "issues": [],
  "createdAt": "2025-01-20T14:35:00Z"
}

Content Format

The content field accepts two formats:

Structured Format (Recommended)

JSON string containing a messages array. This format provides the richest data for insights.

{
  "content": "{\"messages\":[{\"role\":\"user\",\"content\":\"Hello\"},{\"role\":\"assistant\",\"content\":\"Hi! How can I help?\"}]}"
}

Full schema:

interface StructuredContent {
  messages: Array<{
    role: 'user' | 'assistant' | 'system';
    content: string;
    timestamp?: string;    // ISO 8601
    model?: string;        // Model used for this response
    tokens?: number;       // Token count
  }>;
  metadata?: {
    userId?: string;       // Your user ID
    sessionId?: string;    // Session identifier
    channel?: string;      // web, mobile, api, etc.
    language?: string;     // ISO language code
    [key: string]: any;    // Custom fields
  };
}

Text Format

Plain text with role labels:

{
  "content": "User: Hello\nAssistant: Hi! How can I help?"
}

Accepted role labels: User/Assistant, Human/AI, Customer/Agent

Content Limits

Limit	Value	Description
Max content size	512 KB	Maximum size of the content field
Max messages	500	Maximum messages in structured format
Max message length	100 KB	Maximum size per individual message

Exceeding these limits returns a 413 Payload Too Large error.

See the Logging Guide for detailed examples.

---

Idempotency

Prevent duplicate conversation submissions using the idempotencyKey field.

{
  "promptId": "prompt_123",
  "content": "User: Hello\nAssistant: Hi!",
  "idempotencyKey": "session_abc123_1705764600"
}

Behavior:

• If a conversation with the same idempotencyKey already exists, the existing conversation is returned (no duplicate created)
• Keys are scoped to your account
• Keys expire after 24 hours

Recommended key formats:

• {sessionId}_{timestamp} - For session-based logging
• {externalId} - If you have your own conversation IDs
• {hash of content} - For content-based deduplication

---

Error Responses

Not Found

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Conversation not found"
  }
}

Validation Error

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid request body",
    "details": {
      "promptId": "Required field"
    }
  }
}