The Conversations API allows you to create and manage AI conversations. You can create general or persona conversations, continue existing conversations, and manage conversation metadata.
Available Endpoints
Creating Conversations
Create a new general conversation with a specified AI system and model.
Basic Request Format:
{
"system": "string",
"model": "string",
"externalUserId": "string"
}
Create a new conversation with a specific persona, which has predefined characteristics and behavior.
POST /conversations/persona
Basic Request Format:
{
"personaId": "string",
"externalUserId": "string"
}
When creating a conversation, store the conversationId
from the response.
You’ll need this ID for continuing the conversation and managing its metadata
in subsequent API calls.
Continuing Conversations
Continue an existing conversation and get the complete response in a single API call.
POST /conversations/{conversationId}/continue
Continue an existing conversation and stream the response using HTTP/2 protocol.
POST /conversations/{conversationId}/continue-stream
Basic Request Format:
Continue an existing conversation and stream the response using Server-Sent Events (SSE) protocol.
POST /conversations/{conversationId}/continue-sse
Basic Request Format:
Retrieving Conversations
Retrieve all conversations for the organization.
Retrieve all conversations for the current user.
GET /conversations/user/{externalUserId}
Retrieve all conversations with a specific persona.
GET /conversations/persona/{personaId}
Retrieve a specific conversation by ID.
GET /conversations/{conversationId}
Managing Conversations
Mark a conversation as active.
PATCH /conversations/{conversationId}/set-active
Update the metadata for a conversation.
PATCH /conversations/{conversationId}/set-metadata
Update the name of a conversation.
PATCH /conversations/{conversationId}/set-conversation-name
Update the status of a conversation.
PATCH /conversations/{conversationId}/set-conversation-status
// Creating Conversations
POST / conversations;
POST / conversations / persona;
// Continuing Conversations
PATCH / conversations / { conversationId } / chat;
PATCH / conversations / { conversationId } / chat - http2;
PATCH / conversations / { conversationId } / chat - sse;
// Retrieving Conversations
GET / conversations;
GET / conversations / user / { externalUserId };
GET / conversations / persona / { personaId };
GET / conversations / { conversationId };
// Managing Conversations
PATCH / conversations / { conversationId } / set - active;
PATCH / conversations / { conversationId } / set - metadata;
PATCH / conversations / { conversationId } / set - conversation - name;
PATCH / conversations / { conversationId } / set - conversation - status;