Skip to content
NimbleBrain NimbleBrain NimbleBrain

Conversations API

The Conversations API provides access to conversation history and metadata. You can list conversations with pagination, view message history, rename, fork, and delete conversations.

GET /v1/conversations

Section titled “GET /v1/conversations”

List conversations with optional pagination, search, and sorting.

Query parameters:

ParameterTypeDefaultDescription
limitnumber20Maximum number of conversations to return. Must be a positive integer.
cursorstring—Cursor for pagination. Use the nextCursor value from a previous response.
searchstring—Filter conversations by text search on title and content.
sortBystring—Sort field: "createdAt" or "updatedAt".

Response:

{
  "conversations": [
    {
      "id": "conv_a1b2c3d4",
      "createdAt": "2025-10-15T10:30:00.000Z",
      "updatedAt": "2025-10-15T11:45:00.000Z",
      "title": "Weather analysis for Q4",
      "messageCount": 12,
      "preview": "Can you analyze the weather patterns for...",
      "totalInputTokens": 15420,
      "totalOutputTokens": 3200,
      "totalCostUsd": 0.058
    },
    {
      "id": "conv_e5f6g7h8",
      "createdAt": "2025-10-14T09:15:00.000Z",
      "updatedAt": "2025-10-14T09:20:00.000Z",
      "title": null,
      "messageCount": 2,
      "preview": "What is 2 + 2?",
      "totalInputTokens": 640,
      "totalOutputTokens": 24,
      "totalCostUsd": 0.002
    }
  ],
  "nextCursor": "conv_e5f6g7h8",
  "totalCount": 47
}

Response fields:

FieldTypeDescription
conversationsarrayList of conversation summaries
nextCursorstring | nullCursor for the next page, or null if no more results
totalCountnumberTotal number of conversations matching the query

Conversation summary fields:

FieldTypeDescription
idstringConversation ID
createdAtstringISO 8601 creation timestamp
updatedAtstringISO 8601 last update timestamp
titlestring | nullUser-assigned title, or null
messageCountnumberTotal messages in the conversation
previewstringTruncated first user message
totalInputTokensnumberCumulative input tokens
totalOutputTokensnumberCumulative output tokens
totalCostUsdnumberCumulative estimated cost in USD

Error responses:

StatusCondition
400limit is not a positive integer
400sortBy is not "createdAt" or "updatedAt"

Example:

Terminal window
curl "http://localhost:27247/v1/conversations?limit=10&sortBy=updatedAt" \
  -H "Authorization: Bearer your-secret-key"

GET /v1/conversations/:id/history

Section titled “GET /v1/conversations/:id/history”

Retrieve the full message history for a conversation.

Path parameters:

ParameterDescription
:idConversation ID

Response:

{
  "conversationId": "conv_a1b2c3d4",
  "messages": [
    {
      "role": "user",
      "content": "What is the weather in San Francisco?",
      "timestamp": "2025-10-15T10:30:00.000Z"
    },
    {
      "role": "assistant",
      "content": "The current weather in San Francisco is 62°F with partly cloudy skies.",
      "timestamp": "2025-10-15T10:30:05.000Z",
      "metadata": {
        "skill": null,
        "toolCalls": [
          {
            "id": "tc_x7y8z9",
            "name": "weather__get_forecast",
            "input": { "city": "San Francisco" },
            "output": "{\"temp\":62,\"condition\":\"partly cloudy\"}",
            "ok": true,
            "ms": 340
          }
        ],
        "inputTokens": 1250,
        "outputTokens": 45,
        "model": "claude-sonnet-4-5-20250929"
      }
    }
  ]
}

Error responses:

StatusCondition
404Conversation not found

Example:

Terminal window
curl http://localhost:27247/v1/conversations/conv_a1b2c3d4/history \
  -H "Authorization: Bearer your-secret-key"

PATCH /v1/conversations/:id

Section titled “PATCH /v1/conversations/:id”

Update conversation metadata. Currently supports updating the title.

Path parameters:

ParameterDescription
:idConversation ID

Request body:

FieldTypeRequiredDescription
titlestringYesNew title for the conversation

Response:

Returns the updated conversation object.

{
  "id": "conv_a1b2c3d4",
  "createdAt": "2025-10-15T10:30:00.000Z",
  "updatedAt": "2025-10-15T12:00:00.000Z",
  "title": "Weather Analysis",
  "totalInputTokens": 15420,
  "totalOutputTokens": 3200,
  "totalCostUsd": 0.058,
  "lastModel": "claude-sonnet-4-5-20250929"
}

Error responses:

StatusCondition
400title field is missing or not a string
404Conversation not found

Example:

Terminal window
curl -X PATCH http://localhost:27247/v1/conversations/conv_a1b2c3d4 \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-secret-key" \
  -d '{"title": "Weather Analysis"}'

POST /v1/conversations/:id/fork

Section titled “POST /v1/conversations/:id/fork”

Create a copy of a conversation. You can optionally truncate the fork at a specific message index to create a branch point.

Path parameters:

ParameterDescription
:idConversation ID to fork from

Request body:

FieldTypeRequiredDescription
atMessagenumberNoMessage index to fork at (0-based). Omit to copy all messages.

Response:

Returns the newly created conversation.

{
  "id": "conv_f9g0h1i2",
  "createdAt": "2025-10-15T12:05:00.000Z",
  "updatedAt": "2025-10-15T12:05:00.000Z",
  "title": null,
  "totalInputTokens": 1250,
  "totalOutputTokens": 45,
  "totalCostUsd": 0.004,
  "lastModel": "claude-sonnet-4-5-20250929"
}

Error responses:

StatusCondition
400atMessage is not a non-negative integer
404Source conversation not found

Example:

Terminal window
curl -X POST http://localhost:27247/v1/conversations/conv_a1b2c3d4/fork \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-secret-key" \
  -d '{}'

DELETE /v1/conversations/:id

Section titled “DELETE /v1/conversations/:id”

Permanently delete a conversation and its message history.

Path parameters:

ParameterDescription
:idConversation ID

Response:

{
  "id": "conv_a1b2c3d4",
  "deleted": true
}

Error responses:

StatusCondition
404Conversation not found

Example:

Terminal window
curl -X DELETE http://localhost:27247/v1/conversations/conv_a1b2c3d4 \
  -H "Authorization: Bearer your-secret-key"