Conversations API - 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

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

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

Get Conversation

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

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

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

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

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

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

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

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

curl -X POST "https://your-domain.com/api/convos/import" \
  -H "Authorization: Bearer <token>" \
  -F "[email protected]"

Import conversations from a JSON file. Rate limited.

Request

Multipart form data with a single file field.

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

Overview

Endpoints

​Authentication

​List Conversations

​Query Parameters

​Response

​Get Conversation

​Path Parameters

​Response

​Error Responses

​Get Generated Title

​Path Parameters

​Response

​Error Responses

​Update Conversation Title

​Request Body

​Response

​Error Responses

​Archive/Unarchive Conversation

​Request Body

​Response

​Error Responses

​Delete Conversation

​Request Body

​Response

​Error Responses

​Delete All Conversations

​Response

​Error Responses

​Fork Conversation

​Request Body

​Response

​Error Responses

​Duplicate Conversation

​Request Body

​Response

​Error Responses

​Import Conversations

​Request

​Response

​Error Responses

​Common Error Codes

Build docs developers (and LLMs) love

Authentication

List Conversations

Query Parameters

Response

Get Conversation

Path Parameters

Response

Error Responses

Get Generated Title

Path Parameters

Response

Error Responses

Update Conversation Title

Request Body

Response

Error Responses

Archive/Unarchive Conversation

Request Body

Response

Error Responses

Delete Conversation

Request Body

Response

Error Responses

Delete All Conversations

Response

Error Responses

Fork Conversation

Request Body

Response

Error Responses

Duplicate Conversation

Request Body

Response

Error Responses

Import Conversations

Request

Response

Error Responses

Common Error Codes