Skip to main content

​
List Conversations

curl -X GET "https://api.example.com/chat/" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -G \
  -d "limit=20" \
  -d "offset=0"
Retrieves a paginated list of all active (non-archived) conversations for the authenticated user.

​
Method & Path

GET /chat/

​
Authentication

Requires bearer token authentication via the Authorization header.

​
Query Parameters

​
limit
integer
default:20
Maximum number of conversations to return per page
​
offset
integer
default:0
Number of conversations to skip for pagination

​
Response

​
error
boolean
Indicates whether an error occurred
​
chats
array
Array of conversation objects
​
total
integer
Total number of conversations available
​
limit
integer
Limit used for this request
​
offset
integer
Offset used for this request
​
has_more
boolean
Whether more conversations are available beyond the current page

​
Success Response Example

{
  "error": false,
  "chats": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "title": "Database optimization strategies",
      "updated_at": "2026-03-01T10:30:00Z"
    },
    {
      "id": "660e8400-e29b-41d4-a716-446655440001",
      "title": "API authentication methods",
      "updated_at": "2026-02-28T15:45:00Z"
    }
  ],
  "total": 42,
  "limit": 20,
  "offset": 0,
  "has_more": true
}

​
Error Response Example

{
  "error": true,
  "message": "Could not retrieve chats: Database connection failed"
}

​
Error Codes

  • 401 Unauthorized: Missing or invalid authentication token
  • 500 Internal Server Error: Database or server error occurred

​
Rename Conversation

curl -X PUT "https://api.example.com/chat/rename/550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title": "Updated conversation title"}'
Updates the title of an existing conversation.

​
Method & Path

PUT /chat/rename/{chat_id}

​
Authentication

Requires bearer token authentication. Users can only rename their own conversations.

​
Path Parameters

​
chat_id
string
required
Unique identifier of the conversation to rename

​
Request Body

​
title
string
required
New title for the conversation

​
Response

​
error
boolean
Indicates whether an error occurred
​
detail
string
Success or error message
​
new_title
string
The updated conversation title

​
Success Response Example

{
  "error": false,
  "detail": "Chat renamed successfully",
  "new_title": "Updated conversation title"
}

​
Error Codes

  • 401 Unauthorized: Missing or invalid authentication token
  • 404 Not Found: Conversation does not exist or user does not have access
  • 422 Unprocessable Entity: Invalid request body format

​
Archive Conversation

curl -X DELETE "https://api.example.com/chat/archive/550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
Archives a conversation and removes it from active conversation lists. The conversation and its messages are preserved but marked as archived.

​
Method & Path

DELETE /chat/archive/{chat_id}

​
Authentication

Requires bearer token authentication. Users can only archive their own conversations.

​
Path Parameters

​
chat_id
string
required
Unique identifier of the conversation to archive

​
Response

​
error
boolean
Indicates whether an error occurred
​
message
string
Success or error message

​
Success Response Example

{
  "error": false,
  "message": "Chat archived successfully"
}

​
Error Response Example

{
  "error": true,
  "message": "An error occurred while archiving the chat: Database error"
}

​
Error Codes

  • 401 Unauthorized: Missing or invalid authentication token
  • 404 Not Found: Conversation does not exist or user does not have access
  • 500 Internal Server Error: Database or server error occurred
Archived conversations are soft-deleted and can potentially be restored. They will not appear in the conversation list endpoint.

Build docs developers (and LLMs) love

Get started for freeTalk to us