Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/karpathy/llm-council/llms.txt

Use this file to discover all available pages before exploring further.

Conversations are the top-level resource in LLM Council. Every exchange between a user and the council lives inside a conversation, which persists to disk as a JSON file in the backend’s data directory. Before sending any messages you must first create a conversation to obtain a conversation_id. The three endpoints below cover the full lifecycle: creating a session, browsing all sessions, and loading a specific session with its complete message history.

​
List Conversations

curl http://localhost:8001/api/conversations
GET /api/conversations returns metadata for every stored conversation, sorted newest first. No request body or query parameters are accepted.

​
Response

An array of conversation metadata objects. Full message content is omitted from this endpoint — use GET /api/conversations/{conversation_id} to load messages.
​
id
string
required
UUID that uniquely identifies the conversation. Use this value as conversation_id in all subsequent requests.
​
created_at
string
required
ISO 8601 datetime string (UTC) recording when the conversation was created, e.g. "2024-01-15T10:30:00".
​
title
string
required
Human-readable title. Defaults to "New Conversation" and is replaced with an auto-generated title after the first message is sent.
​
message_count
integer
required
Total number of messages in the conversation (both user and assistant turns).
Example response: 
[
  {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "created_at": "2024-01-15T10:30:00",
    "title": "Black holes explained",
    "message_count": 4
  },
  {
    "id": "b2c3d4e5-f6a7-8901-bcde-f01234567891",
    "created_at": "2024-01-14T09:15:00",
    "title": "New Conversation",
    "message_count": 0
  }
]

​
Create a Conversation

curl -X POST http://localhost:8001/api/conversations \
  -H 'Content-Type: application/json' \
  -d '{}'
POST /api/conversations creates a new, empty conversation and returns the full conversation object. The request body must be a valid JSON object — an empty object {} is sufficient.

​
Request Body

​
(empty object)
object
No fields are required. Send an empty JSON object {}.

​
Response

​
id
string
required
UUID assigned to the new conversation. Store this value — it is required for all message endpoints.
​
created_at
string
required
ISO 8601 UTC datetime string recording the moment the conversation was created.
​
title
string
required
Always "New Conversation" at creation time. Updated automatically after the first message.
​
messages
array
required
Empty array [] — no messages have been sent yet.
Example response: 
{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "created_at": "2024-01-15T10:30:00",
  "title": "New Conversation",
  "messages": []
}

​
Get a Conversation

curl http://localhost:8001/api/conversations/a1b2c3d4-e5f6-7890-abcd-ef1234567890
GET /api/conversations/{conversation_id} loads a single conversation with its complete message history, including all stage data from every council run.

​
Path Parameters

​
conversation_id
string
required
The UUID of the conversation to retrieve, as returned by POST /api/conversations or GET /api/conversations.

​
Response

​
id
string
required
The conversation UUID.
​
created_at
string
required
ISO 8601 UTC datetime string.
​
title
string
required
Current conversation title. Updated from "New Conversation" after the first message is processed.
​
messages
array
required
Full list of messages. User messages contain role and content. Assistant messages contain role, stage1, stage2, and stage3.

​
Errors

StatusDescription
404No conversation with the given conversation_id exists on disk.
The label_to_model mapping and aggregate_rankings list are not stored in the conversation file — they are ephemeral values computed at request time and returned only by the message endpoints. To see them, call POST /api/conversations/{id}/message or inspect the stage2_complete SSE event from the streaming endpoint.

Build docs developers (and LLMs) love

Get started for freeTalk to us