Conversations API

API endpoints for managing conversations in LibreChat

The Conversations API allows you to manage chat conversations, including listing, retrieving, updating, deleting, archiving, and advanced operations like forking and duplicating conversations.

Authentication

All endpoints require JWT authentication via the Authorization header:

Authorization: Bearer <your_jwt_token>

---

List Conversations

GET /api/convos

curl -X GET "https://your-domain.com/api/convos?limit=25&cursor=<cursor>&sortBy=updatedAt&sortDirection=desc" \
  -H "Authorization: Bearer <token>"

Retrieve a paginated list of conversations for the authenticated user.

Query Parameters

limit · integer · default: "25"

Number of conversations to return per page (max 100)

cursor · string

Pagination cursor from previous response’s nextCursor

isArchived · boolean

Filter by archived status (true/false)

sortBy · string · default: "updatedAt"

Sort field: updatedAt, createdAt, or title

sortDirection · string · default: "desc"

Sort direction: asc or desc

tags · string[]

Filter by conversation tags (can be multiple)

search · string

Search query to filter conversations by title or content

Response

conversations · array

Array of conversation objects

Show Conversation object

conversationId · string

Unique conversation identifier

title · string

Conversation title

endpoint · string

Model endpoint used (e.g., “openAI”, “anthropic”, “agents”)

createdAt · string

ISO 8601 timestamp

updatedAt · string

ISO 8601 timestamp

isArchived · boolean

Archive status

tags · string[]

Associated tags

nextCursor · string | null

Cursor for next page, null if no more results

---

Get Conversation

GET /api/convos/:conversationId

curl -X GET "https://your-domain.com/api/convos/<conversation_id>" \
  -H "Authorization: Bearer <token>"

Retrieve a specific conversation by ID.

Path Parameters

conversationId · string · required

The conversation ID to retrieve

Response

Returns a complete conversation object with all settings and metadata.

conversationId · string

Unique conversation identifier

title · string

Conversation title

endpoint · string

Model endpoint (e.g., “openAI”, “anthropic”, “agents”)

model · string

Model name used in the conversation

temperature · number

Model temperature parameter

createdAt · string

ISO 8601 timestamp

updatedAt · string

ISO 8601 timestamp

Error Responses

• 404 Not Found: Conversation does not exist or user lacks access

---

Get Generated Title

GET /api/convos/gen_title/:conversationId

curl -X GET "https://your-domain.com/api/convos/gen_title/<conversation_id>" \
  -H "Authorization: Bearer <token>"

Retrieve the auto-generated title for a conversation. This endpoint uses exponential backoff polling (up to ~15 seconds) to wait for title generation.

Path Parameters

conversationId · string · required

The conversation ID

Response

title · string

The generated conversation title

Error Responses

• 404 Not Found: Title generation not available or method not implemented for the conversation’s endpoint

---

Update Conversation Title

POST /api/convos/update

curl -X POST "https://your-domain.com/api/convos/update" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "arg": {
      "conversationId": "<conversation_id>",
      "title": "New conversation title"
    }
  }'

Update the title of a conversation.

Request Body

arg.conversationId · string · required

The conversation ID to update

arg.title · string · required

New title (max 1024 characters, will be trimmed and sanitized)

Response

Returns the updated conversation object.

Error Responses

• 400 Bad Request: Missing or invalid parameters
• 403 Forbidden: User lacks access to the conversation
• 500 Internal Server Error: Update failed

---

Archive/Unarchive Conversation

POST /api/convos/archive

curl -X POST "https://your-domain.com/api/convos/archive" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "arg": {
      "conversationId": "<conversation_id>",
      "isArchived": true
    }
  }'

Archive or unarchive a conversation.

Request Body

arg.conversationId · string · required

The conversation ID

arg.isArchived · boolean · required

Set to true to archive, false to unarchive

Response

Returns the updated conversation object.

Error Responses

• 400 Bad Request: Missing or invalid parameters
• 403 Forbidden: User lacks access to the conversation
• 500 Internal Server Error: Operation failed

---

Delete Conversation

DELETE /api/convos

curl -X DELETE "https://your-domain.com/api/convos" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "arg": {
      "conversationId": "<conversation_id>"
    }
  }'

Delete a specific conversation and associated data (messages, tool calls, shared links).

Request Body

arg.conversationId · string

The conversation ID to delete

arg.thread_id · string

Thread ID for Assistants API conversations (optional)

arg.endpoint · string

Endpoint type (required if deleting Assistant thread)

arg.source · string

Source of deletion request (e.g., “button”)

Response

Returns deletion confirmation with the number of deleted documents.

Error Responses

• 400 Bad Request: No parameters provided
• 500 Internal Server Error: Deletion failed

---

Delete All Conversations

DELETE /api/convos/all

curl -X DELETE "https://your-domain.com/api/convos/all" \
  -H "Authorization: Bearer <token>"

Delete all conversations for the authenticated user, including messages, tool calls, and shared links.

Response

Returns deletion confirmation with the number of deleted documents.

Error Responses

• 500 Internal Server Error: Deletion failed

---

Fork Conversation

POST /api/convos/fork

curl -X POST "https://your-domain.com/api/convos/fork" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "conversationId": "<conversation_id>",
    "messageId": "<message_id>",
    "option": "branch",
    "splitAtTarget": true,
    "latestMessageId": "<latest_message_id>"
  }'

Create a new conversation by forking from a specific message in an existing conversation. Rate limited.

Request Body

conversationId · string · required

Source conversation ID

messageId · string · required

Target message ID to fork from

option · string

Fork option: “branch” or “direct”

splitAtTarget · boolean

Whether to split at the target message

latestMessageId · string

Latest message ID in the conversation

Response

conversation · object

The newly created forked conversation

messages · array

Messages copied to the forked conversation

Error Responses

• 429 Too Many Requests: Rate limit exceeded
• 500 Internal Server Error: Fork operation failed

---

Duplicate Conversation

POST /api/convos/duplicate

curl -X POST "https://your-domain.com/api/convos/duplicate" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "conversationId": "<conversation_id>",
    "title": "Copy of conversation"
  }'

Create a complete duplicate of a conversation with all messages.

Request Body

conversationId · string · required

The conversation ID to duplicate

title · string

Optional title for the duplicated conversation

Response

Returns the newly created conversation object with duplicated messages.

Error Responses

• 500 Internal Server Error: Duplication failed

---

Import Conversations

POST /api/convos/import

curl -X POST "https://your-domain.com/api/convos/import" \
  -H "Authorization: Bearer <token>" \
  -F "file=@conversations.json"

Import conversations from a JSON file. Rate limited.

Request

Multipart form data with a single file field.

file · file · required

JSON file containing conversation data

Response

message · string

Success message: “Conversation(s) imported successfully”

Error Responses

• 429 Too Many Requests: Rate limit exceeded
• 500 Internal Server Error: Import failed

---

Common Error Codes

Status Code	Description
400	Bad Request - Invalid parameters or missing required fields
401	Unauthorized - Invalid or missing JWT token
403	Forbidden - User lacks permission to access the conversation
404	Not Found - Conversation does not exist
429	Too Many Requests - Rate limit exceeded
500	Internal Server Error - Server-side error occurred