> ## Documentation Index
> Fetch the complete documentation index at: /llms.txt
> Use this file to discover all available pages before exploring further.

# Conversations

> Start, list, read, close and reopen conversations.

## Start a conversation

[`POST /conversations`](/api-reference/conversations/start-a-conversation) creates a conversation with the customer's first message. `customerId` is only needed here: every later call uses the conversation id.

```bash
curl https://api.usecerium.com/v1/conversations \
  -H "Authorization: Bearer $CERIUM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "customerId": "prt_8271",
    "body": "Hi, I was charged twice for order 1042.",
    "idempotencyKey": "order-1042-first-message"
  }'
```

The response is the **first message**. Read `data.conversationId` from it and store it next to your own record (an order, a ticket, a user).

> [!TIP]
>
> Always send an `idempotencyKey`. If the request times out you cannot tell whether the conversation was created; with a key you can retry without risk. See [Idempotency](/guides/idempotency.md).

## List conversations

```bash
# All open conversations
curl "https://api.usecerium.com/v1/conversations?status=open" \
  -H "Authorization: Bearer $CERIUM_API_KEY"

# One customer's conversations
curl "https://api.usecerium.com/v1/conversations?customerId=prt_8271" \
  -H "Authorization: Bearer $CERIUM_API_KEY"
```

Results are newest first and paged: see [Pagination](/guides/pagination.md). Each item carries `customerId`, `status`, `lastMessageAt` and `createdAt`.

## Get a conversation

[`GET /conversations/{conversationId}`](/api-reference/conversations/get-a-conversation) returns the conversation with its `customer` and whether a team member is handling it (`assignmentStatus`, `agentName`).

## Close and reopen

```bash
curl -X PATCH https://api.usecerium.com/v1/conversations/thr_01k9z3m4q8 \
  -H "Authorization: Bearer $CERIUM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "status": "closed" }'
```

* Asking for the status it already has changes nothing and succeeds.
* A customer message in a closed conversation **reopens it automatically**.

## Following replies

Replies from your team and AI agent appear as new messages in the conversation. To show them in your app, [list the messages](/guides/messages-and-attachments.md#read-messages) for the conversation, and use `lastMessageAt` on the conversation to tell whether anything new has arrived.
