Conversations API

Manage conversation sessions for memory isolation.

Overview

Conversations provide memory isolation within a user context. Each conversation has its own episodic memory, allowing you to keep different chat sessions separate. This is useful for agents that handle multiple topics or projects for the same user.

Endpoints

POST/api/v1/conversations

Create a new conversation

conversations:write

GET/api/v1/conversations

List conversations for a user

conversations:read

GET/api/v1/conversations/:id

Get conversation details

conversations:read

PATCH/api/v1/conversations/:id

Update conversation metadata

conversations:write

Create Conversation

Start a new conversation for a user.

Request

POST /api/v1/conversationsbash

curl -X POST http://localhost:3000/api/v1/conversations \
  -H "Authorization: Bearer rk_live_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "usr_abc123",
    "title": "Project Planning Session",
    "metadata": {
      "project": "website-redesign",
      "priority": "high"
    }
  }'

Parameters

Field	Type	Required	Description
`user_id`	string	Yes	The user this conversation belongs to
`title`	string	No	Human-readable conversation title
`metadata`	object	No	Custom metadata

Response

Response (201 Created)json

{
  "conversation_id": "conv_xyz789abc",
  "tenant_id": "ten_xxxxxxxx",
  "user_id": "usr_abc123",
  "title": "Project Planning Session",
  "metadata": {
    "project": "website-redesign",
    "priority": "high"
  },
  "message_count": 0,
  "created_at": "2024-01-15T10:35:00Z",
  "updated_at": "2024-01-15T10:35:00Z"
}

List Conversations

Retrieve all conversations for a user.

GET /api/v1/conversationsbash

curl -X GET "http://localhost:3000/api/v1/conversations?user_id=usr_abc123&limit=10" \
  -H "Authorization: Bearer rk_live_xxxxxxxxxxxx"

Query Parameters

Parameter	Type	Required	Description
`user_id`	string	Yes	Filter by user
`limit`	number	No	Max results (default: 20)
`offset`	number	No	Pagination offset

Response (200 OK)json

{
  "conversations": [
    {
      "conversation_id": "conv_xyz789abc",
      "user_id": "usr_abc123",
      "title": "Project Planning Session",
      "message_count": 15,
      "created_at": "2024-01-15T10:35:00Z",
      "updated_at": "2024-01-15T14:20:00Z"
    },
    {
      "conversation_id": "conv_def456uvw",
      "user_id": "usr_abc123",
      "title": "Code Review Discussion",
      "message_count": 8,
      "created_at": "2024-01-14T09:00:00Z",
      "updated_at": "2024-01-14T11:30:00Z"
    }
  ],
  "total": 5,
  "limit": 10,
  "offset": 0
}

Get Conversation

Retrieve details for a specific conversation.

GET /api/v1/conversations/:idbash

curl -X GET http://localhost:3000/api/v1/conversations/conv_xyz789abc \
  -H "Authorization: Bearer rk_live_xxxxxxxxxxxx"

Response (200 OK)json

{
  "conversation_id": "conv_xyz789abc",
  "tenant_id": "ten_xxxxxxxx",
  "user_id": "usr_abc123",
  "title": "Project Planning Session",
  "metadata": {
    "project": "website-redesign",
    "priority": "high"
  },
  "message_count": 15,
  "last_message_at": "2024-01-15T14:20:00Z",
  "created_at": "2024-01-15T10:35:00Z",
  "updated_at": "2024-01-15T14:20:00Z"
}

Update Conversation

Update conversation title or metadata.

PATCH /api/v1/conversations/:idbash

curl -X PATCH http://localhost:3000/api/v1/conversations/conv_xyz789abc \
  -H "Authorization: Bearer rk_live_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Website Redesign - Planning",
    "metadata": {
      "project": "website-redesign",
      "priority": "high",
      "status": "in-progress"
    }
  }'

Response (200 OK)json

{
  "conversation_id": "conv_xyz789abc",
  "tenant_id": "ten_xxxxxxxx",
  "user_id": "usr_abc123",
  "title": "Website Redesign - Planning",
  "metadata": {
    "project": "website-redesign",
    "priority": "high",
    "status": "in-progress"
  },
  "message_count": 15,
  "created_at": "2024-01-15T10:35:00Z",
  "updated_at": "2024-01-16T09:00:00Z"
}

Conversation Object

Conversation Schematypescript

interface Conversation {
  conversation_id: string;   // 'conv_xxx' - Unique ID
  tenant_id: string;         // Parent tenant
  user_id: string;           // Owner user
  title?: string;            // Display title
  metadata?: Record<string, unknown>;  // Custom data
  message_count: number;     // Total interactions
  last_message_at?: string;  // Last activity timestamp
  created_at: string;        // ISO 8601 timestamp
  updated_at: string;        // Last update timestamp
}

Best Practices

Create new conversations for distinct topics or sessions

Use meaningful titles for easy identification

Leverage metadata for your application's context (project, tags, etc.)

Consider archiving old conversations based on your retention policy

Related Endpoints

→Memory API →Users API →Agent Integration Guide →Memory Tiers