Skip to main content
Conversations group a series of chat messages within a project. The Flutter client creates a conversation before sending the first chat message and uses the conversation ID when streaming subsequent messages. Conversations and messages are persisted in SQLite.

​
POST /api/v1/conversations/

Create a new conversation for a project.

​
Request body

​
project_id
string (UUID)
required
The project this conversation belongs to.
​
title
string
Optional human-readable title for the conversation. Maximum 255 characters.

​
Response

Returns 201 Created with a ConversationResponse object. 
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "project_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "title": "Architecture planning session",
  "messages": [],
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T10:30:00Z"
}
​
id
string (UUID)
Unique conversation identifier. Use this as conversation_id in chat requests.
​
project_id
string (UUID)
The project this conversation belongs to.
​
title
string | null
The conversation title, or null if not set.
​
messages
array
List of messages in this conversation. Empty on creation.
​
created_at
string (ISO 8601)
Timestamp when the conversation was created.
​
updated_at
string (ISO 8601)
Timestamp of the last update to the conversation.

​
Example

curl -X POST http://localhost:8000/api/v1/conversations/ \
  -H "Content-Type: application/json" \
  -d '{
    "project_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "title": "Architecture planning session"
  }'

​
GET /api/v1/conversations/

Retrieve a single conversation by its UUID, including all messages.

​
Path parameters

​
conversation_id
string (UUID)
required
The conversation UUID.

​
Response

Returns 200 OK with a ConversationResponse object (same shape as the create response above).

​
Errors

StatusCondition
404 Not FoundNo conversation with the given ID exists

​
Example

curl http://localhost:8000/api/v1/conversations/550e8400-e29b-41d4-a716-446655440000

​
GET /api/v1/conversations/

List conversations with optional filtering by project and pagination.

​
Query parameters

​
project_id
string (UUID)
Filter conversations to a specific project. When omitted, all conversations are returned.
​
skip
integer
default:"0"
Number of records to skip (offset-based pagination).
​
limit
integer
default:"100"
Maximum number of conversations to return.

​
Response

{
  "conversations": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "project_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "title": "Architecture planning session",
      "messages": [],
      "created_at": "2024-01-15T10:30:00Z",
      "updated_at": "2024-01-15T10:30:00Z"
    }
  ],
  "total": 1,
  "skip": 0,
  "limit": 100
}
​
conversations
array
List of ConversationResponse objects. See the create endpoint for the full object shape.
​
total
integer
Total number of conversations returned in this response. Note: this reflects the count of the current page, not the total across all pages.
​
skip
integer
The skip value used for this request.
​
limit
integer
The limit value used for this request.

​
Example

curl "http://localhost:8000/api/v1/conversations/?project_id=7c9e6679-7425-40de-944b-e07fc1f90ae7&skip=0&limit=20"

Build docs developers (and LLMs) love

Get started for freeTalk to us