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

# Quickstart

> Register a customer, start a conversation, and read it back in five minutes.

## Before you start

You need an API key with the `customers:write`, `conversations:write` and `conversations:read` scopes. See [Authentication](/authentication.md).

Set it as an environment variable so it never ends up in your code:

```bash
export CERIUM_API_KEY="your-api-key"
```

**1. Create the customer**

Send the customer once, with your own id for them as `externalId`.

```bash cURL
curl https://api.usecerium.com/v1/customers \
  -H "Authorization: Bearer $CERIUM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "externalId": "user_8271",
    "name": "Ada Obi",
    "email": "ada@example.com"
  }'
```

```javascript Node.js
const res = await fetch("https://api.usecerium.com/v1/customers", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.CERIUM_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    externalId: "user_8271",
    name: "Ada Obi",
    email: "ada@example.com",
  }),
});
const { data: customer } = await res.json();
```

```python Python
import os, requests

res = requests.post(
    "https://api.usecerium.com/v1/customers",
    headers={"Authorization": f"Bearer {os.environ['CERIUM_API_KEY']}"},
    json={"externalId": "user_8271", "name": "Ada Obi", "email": "ada@example.com"},
)
customer = res.json()["data"]
```

The response includes the customer's Cerium `id` (starts with `prt_`). Keep it: you need it to start a conversation.

```json
{
  "message": "Customer created successfully.",
  "status": "success",
  "data": {
    "id": "prt_8271",
    "externalId": "user_8271",
    "name": "Ada Obi",
    "email": "ada@example.com",
    "phone": null,
    "tags": [],
    "attributes": {},
    "createdAt": "2026-11-20T09:14:03.000Z",
    "created": true
  }
}
```

**2. Start a conversation**

Send the customer's first message. The `idempotencyKey` makes a retry safe: see [Idempotency](/guides/idempotency.md).

```bash cURL
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"
  }'
```

```javascript Node.js
const res = await fetch("https://api.usecerium.com/v1/conversations", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.CERIUM_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    customerId: customer.id,
    body: "Hi, I was charged twice for order 1042.",
    idempotencyKey: "order-1042-first-message",
  }),
});
const { data: message } = await res.json();
const conversationId = message.conversationId;
```

```python Python
res = requests.post(
    "https://api.usecerium.com/v1/conversations",
    headers={"Authorization": f"Bearer {os.environ['CERIUM_API_KEY']}"},
    json={
        "customerId": customer["id"],
        "body": "Hi, I was charged twice for order 1042.",
        "idempotencyKey": "order-1042-first-message",
    },
)
conversation_id = res.json()["data"]["conversationId"]
```

The response is the first **message**. Its `conversationId` identifies the conversation.

**3. Read the replies**

List the conversation's messages to pick up replies from your team or your AI agent.

```bash
curl "https://api.usecerium.com/v1/conversations/$CONVERSATION_ID/messages?order=asc" \
  -H "Authorization: Bearer $CERIUM_API_KEY"
```

Each message says who wrote it in `senderType`: `customer`, `agent`, `ai` or `system`.

**4. Keep the conversation going**

Add the customer's next message:

```bash
curl https://api.usecerium.com/v1/conversations/$CONVERSATION_ID/messages \
  -H "Authorization: Bearer $CERIUM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "body": "Here is the receipt.", "idempotencyKey": "order-1042-msg-2" }'
```

## Next steps

> [card] [Handle errors](/guides/errors.md)
>
> What each status means and what to do about it.

> [card] [Retry safely](/guides/idempotency.md)
>
> Make sure a retry never sends a message twice.

> [card] [Going live](/guides/going-live.md)
>
> A checklist before you ship.
