Conversations API

REST APIPro

Create and manage persistent chat conversation threads. Requires a Pro or Team plan.

GET/api/conversations

List all conversations for the authenticated user, ordered by most recently updated.

Request Example

Request

curl -H "Authorization: Bearer <token>" \
  "http://localhost:3000/api/conversations"

Response Example

Response

[
  {
    "id": "uuid",
    "title": "LLM Transformer Research",
    "userId": "user-uuid",
    "createdAt": "2024-04-01T10:00:00.000Z",
    "updatedAt": "2024-04-01T11:30:00.000Z"
  }
]

POST/api/conversations

Create a new conversation thread. The title is optional and defaults to 'New Conversation'.

Parameters

Name	Type	Description
`title`	string	Optional display title for the conversation.

Request Example

Request

curl -X POST "http://localhost:3000/api/conversations" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"title":"LLM Research"}'

Response Example

Response

{
  "id": "new-uuid",
  "title": "LLM Research",
  "userId": "user-uuid",
  "createdAt": "2024-04-01T12:00:00.000Z",
  "updatedAt": "2024-04-01T12:00:00.000Z"
}

GET/api/conversations/:id

Retrieve a single conversation and its full message history.

Request Example

Request

curl -H "Authorization: Bearer <token>" \
  "http://localhost:3000/api/conversations/uuid"

Response Example

Response

{
  "id": "uuid",
  "title": "LLM Research",
  "messages": [
    { "role": "user", "content": "What do my saved links say about transformers?" },
    { "role": "assistant", "content": "Based on your archive...", "sources": [...] }
  ]
}

POST/api/conversations/:id/messages

Persist messages to a conversation after a chat or synthesis stream completes. The dashboard calls this automatically — use it if you're building on top of the API.

Parameters

Name	Type	Description
`messages`required	Message[]	Array of message objects with role ('user' \| 'assistant'), content, and optional sources array.

Request Example

Request

curl -X POST "http://localhost:3000/api/conversations/uuid/messages" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"messages":[{"role":"user","content":"What is RAG?"},{"role":"assistant","content":"RAG stands for...","sources":[]}]}'

Response Example

Response

{ "success": true }

DELETE/api/conversations/:id

Permanently delete a conversation and all its messages.

Request Example

Request

curl -X DELETE "http://localhost:3000/api/conversations/uuid" \
  -H "Authorization: Bearer <token>"

Response Example

Response

{ "success": true }