Conversations¶

Blaick can store conversation history server-side so you don't have to resend the entire message list on every turn. Attach a completion to a conversation and Blaick remembers the exchange.

Two ways to manage history¶

Stateless — send the full messages array every time. Simple, and you control everything. Good for one-off requests.
Stateful — pass a conversation_id. Blaick stores each turn and threads them together. You only send the newest user message.

Letting Blaick create the conversation¶

If you call chat completions without a conversation_id, Blaick creates one automatically and returns its id:

{
  "content": "...",
  "conversation_id": "11111111-2222-4333-8444-555555555555"
}

Reuse that conversation_id on the next request and just send the new message:

{
  "model_id": "claude-sonnet-4-20250514",
  "conversation_id": "11111111-2222-4333-8444-555555555555",
  "messages": [{"role": "user", "content": "And what about Italy?"}]
}

Creating a conversation explicitly¶

curl https://api.blaick.ai/api/v1/chat/conversations \
  -H "Authorization: Bearer $BLAICK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title": "Travel planning", "model_id": "claude-sonnet-4-20250514"}'

Listing conversations¶

curl "https://api.blaick.ai/api/v1/chat/conversations?page=1&per_page=20" \
  -H "Authorization: Bearer $BLAICK_API_KEY"

Query param	Default	Description
`page`	`1`	Page number.
`per_page`	`20`	Items per page.
`search`	—	Filter by title text.

{
  "conversations": [
    {
      "id": "11111111-2222-4333-8444-555555555555",
      "title": "Travel planning",
      "model_name": "Claude Sonnet 4",
      "message_count": 6,
      "created_at": "2026-08-04T10:00:00Z",
      "updated_at": "2026-08-04T10:05:00Z"
    }
  ],
  "total": 42,
  "page": 1,
  "per_page": 20
}

Fetching a conversation with its messages¶

curl https://api.blaick.ai/api/v1/chat/conversations/{id} \
  -H "Authorization: Bearer $BLAICK_API_KEY"

Returns the conversation metadata along with the full ordered list of messages. For long threads, page through messages with:

curl "https://api.blaick.ai/api/v1/chat/conversations/{id}/messages?page=1&per_page=50" \
  -H "Authorization: Bearer $BLAICK_API_KEY"

Deleting a conversation¶

curl -X DELETE https://api.blaick.ai/api/v1/chat/conversations/{id} \
  -H "Authorization: Bearer $BLAICK_API_KEY"

Deletion is permanent and removes the stored messages.

When to use which

Use stateful conversations for chat UIs and multi-turn assistants — less data on the wire and history you can list and revisit. Use stateless requests for stateless jobs like classification or extraction, where each request stands alone.