Conversations - LibreChat

Overview

The Conversations API allows you to manage chat conversations, including creating, retrieving, updating, archiving, and deleting conversations. All conversation endpoints are prefixed with /api/convos.

List Conversations

Retrieve a paginated list of conversations:

GET /api/convos
Authorization: Bearer <token>

Query Parameters

limit

number

default:"25"

Number of conversations to return (max 100)

cursor

string

Cursor for pagination from previous response

isArchived

boolean

Filter by archive status (true for archived, false for active)

Response

conversations

TConversation[]

Array of conversation objects

pageNumber

number

Current page number

pageSize

number

Number of items per page

pages

number

Total number of pages

{
  "conversations": [
    {
      "conversationId": "abc123",
      "title": "Machine Learning Discussion",
      "createdAt": "2024-01-15T10:00:00Z",
      "updatedAt": "2024-01-15T14:30:00Z",
      "endpoint": "openAI",
      "model": "gpt-4",
      "isArchived": false,
      "tags": ["ai", "technical"]
    }
  ],
  "pageNumber": 1,
  "pageSize": 25,
  "pages": 3
}

Get Conversation

Retrieve a specific conversation by ID:

GET /api/convos/:conversationId
Authorization: Bearer <token>

Path Parameters

conversationId

string

required

Unique identifier for the conversation

Response

conversationId

string

Unique conversation identifier

title

string

Conversation title

endpoint

string

AI endpoint used (e.g., openAI, anthropic, google)

model

string

Model identifier (e.g., gpt-4, claude-3-opus)

createdAt

string

ISO 8601 timestamp of creation

updatedAt

string

ISO 8601 timestamp of last update

isArchived

boolean

Whether the conversation is archived

Update Conversation Title

Update the title of a conversation:

POST /api/convos/update
Authorization: Bearer <token>
Content-Type: application/json

{
  "arg": {
    "conversationId": "abc123",
    "title": "New Title"
  }
}

Request Body

arg.conversationId

string

required

ID of the conversation to update

arg.title

string

required

New title (max 1024 characters, will be trimmed)

Response

Returns the updated conversation object.

{
  "conversationId": "abc123",
  "title": "New Title",
  "updatedAt": "2024-01-15T15:00:00Z"
}

Archive/Unarchive Conversation

Archive or unarchive a conversation:

POST /api/convos/archive
Authorization: Bearer <token>
Content-Type: application/json

{
  "arg": {
    "conversationId": "abc123",
    "isArchived": true
  }
}

Request Body

arg.conversationId

string

required

ID of the conversation to archive/unarchive

arg.isArchived

boolean

required

true to archive, false to unarchive

Response

Returns the updated conversation object.

Delete Conversation

Delete a specific conversation:

DELETE /api/convos
Authorization: Bearer <token>
Content-Type: application/json

{
  "arg": {
    "conversationId": "abc123",
    "source": "button"
  }
}

Request Body

arg.conversationId

string

required

ID of the conversation to delete

arg.source

string

Source of the deletion request (e.g., button)

arg.thread_id

string

OpenAI thread ID (for assistant endpoints)

arg.endpoint

string

Endpoint type (e.g., assistants, azureAssistants)

Response

{
  "acknowledged": true,
  "deletedCount": 1,
  "messages": {
    "deletedCount": 15
  }
}

Delete All Conversations

Delete all conversations for the authenticated user:

DELETE /api/convos/all
Authorization: Bearer <token>

Response

{
  "acknowledged": true,
  "deletedCount": 42,
  "messages": {
    "deletedCount": 523
  }
}

Generate Title

Generate or retrieve an AI-generated title for a conversation:

GET /api/convos/gen_title/:conversationId
Authorization: Bearer <token>

Path Parameters

conversationId

string

required

Conversation ID to generate title for

Response

title

string

AI-generated title for the conversation

{
  "title": "Machine Learning Best Practices"
}

This endpoint uses exponential backoff to wait for title generation (500ms, 1s, 2s, 4s, 8s - max ~15.5s). If no title is generated within this time, returns 404.

Fork Conversation

Create a new conversation branch from a specific message:

POST /api/convos/fork
Authorization: Bearer <token>
Content-Type: application/json

{
  "conversationId": "abc123",
  "messageId": "msg456",
  "option": "target",
  "splitAtTarget": true,
  "latestMessageId": "msg789"
}

Request Body

conversationId

string

required

Original conversation ID

messageId

string

required

Target message ID to fork from

option

string

Fork option: target or branch

splitAtTarget

boolean

Whether to split at the target message

latestMessageId

string

Latest message ID in the conversation

Response

conversation

TConversation

New forked conversation

messages

TMessage[]

Messages in the new conversation

{
  "conversation": {
    "conversationId": "fork_xyz",
    "title": "Machine Learning Discussion (Fork)",
    "endpoint": "openAI",
    "model": "gpt-4"
  },
  "messages": [...]
}

Duplicate Conversation

Create an exact copy of a conversation:

POST /api/convos/duplicate
Authorization: Bearer <token>
Content-Type: application/json

{
  "conversationId": "abc123",
  "title": "Copy of Machine Learning Discussion"
}

Request Body

conversationId

string

required

ID of conversation to duplicate

title

string

Title for the duplicated conversation (optional)

Response

Returns the new duplicated conversation object.

Import Conversations

Import conversations from a JSON file:

POST /api/convos/import
Authorization: Bearer <token>
Content-Type: multipart/form-data

--boundary
Content-Disposition: form-data; name="file"; filename="conversations.json"
Content-Type: application/json

[conversation data]
--boundary--

Request

Multipart form data with a JSON file.

file

File

required

JSON file containing conversation data

Response

{
  "message": "Conversation(s) imported successfully"
}

Rate Limits

Import endpoint has special rate limiting:

IP-based limit
User-based limit

Conversation Tags

Add Tag to Conversation

POST /api/tags/convo/:conversationId
Authorization: Bearer <token>
Content-Type: application/json

{
  "tag": "important"
}

conversationId

string

required

Conversation ID

tag

string

required

Tag name to add

GET /api/tags/list?pageNumber=1&sort=name&order=asc
Authorization: Bearer <token>

pageNumber

string

required

Page number for pagination

sort

string

Sort field (e.g., name, count)

order

string

Sort order: asc or desc

Error Responses

Conversation Not Found

{
  "error": "Conversation not found"
}

HTTP Status: 404

Invalid Parameters

{
  "error": "conversationId is required"
}

HTTP Status: 400

Unauthorized Access

{
  "error": "Unauthorized",
  "message": "You don't have access to this conversation"
}

HTTP Status: 403

TypeScript Types

import type { TConversation } from 'librechat-data-provider';

interface TConversation {
  conversationId: string;
  title: string;
  endpoint: string;
  model: string;
  modelLabel?: string;
  createdAt: string;
  updatedAt: string;
  isArchived?: boolean;
  tags?: string[];
  // ... additional fields
}

Overview

Endpoints

Integration

​Overview

​List Conversations

​Query Parameters

​Response

​Get Conversation

​Path Parameters

​Response

​Update Conversation Title

​Request Body

​Response

​Archive/Unarchive Conversation

​Request Body

​Response

​Delete Conversation

​Request Body

​Response

​Delete All Conversations

​Response

​Generate Title

​Path Parameters

​Response

​Fork Conversation

​Request Body

​Response

​Duplicate Conversation

​Request Body

​Response

​Import Conversations

​Request

​Response

​Rate Limits

​Conversation Tags

​Add Tag to Conversation

​List Tags

​Error Responses

​Conversation Not Found

​Invalid Parameters

​Unauthorized Access

​TypeScript Types

Build docs developers (and LLMs) love

Overview

List Conversations

Query Parameters

Response

Get Conversation

Path Parameters

Response

Update Conversation Title

Request Body

Response

Archive/Unarchive Conversation

Request Body

Response

Delete Conversation

Request Body

Response

Delete All Conversations

Response

Generate Title

Path Parameters

Response

Fork Conversation

Request Body

Response

Duplicate Conversation

Request Body

Response

Import Conversations

Request

Response

Rate Limits

Conversation Tags

Add Tag to Conversation

List Tags

Error Responses

Conversation Not Found

Invalid Parameters

Unauthorized Access

TypeScript Types