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

# Segments

> Endpoints to manage segments — system prompt, welcome message, and conversation starters

Segments let you configure different personalities and behaviors for the same tenant. Every tenant has a default segment. The **system prompt** lives on the segment, not the tenant.

## GET /tenants/{slug}/segments

List all segments.

**Required scope:** `segments:read`

### Request

```bash theme={null}
curl https://api.animam.ai/tenants/my-company/segments \
  -H "Authorization: Bearer ak_your_token"
```

### Response

```json theme={null}
[
  {
    "id": "cls_abc123",
    "slug": "general",
    "name": "General",
    "welcomeMessage": "Hello! How can I help you?",
    "conversationStarters": [
      { "text": "What do you offer?", "emoji": "" },
      { "text": "How does pricing work?", "emoji": "" }
    ],
    "isDefault": true,
    "isActive": true,
    "createdAt": "2024-01-15T10:30:00Z"
  }
]
```

<Note>
  The `systemPrompt` field is excluded from the list response. Use `GET /tenants/{slug}/segments/{id}` to read it.
</Note>

## GET /tenants/{slug}/segments/{id}

Get a single segment with its full system prompt.

**Required scope:** `segments:read`

### Request

```bash theme={null}
curl https://api.animam.ai/tenants/my-company/segments/cls_abc123 \
  -H "Authorization: Bearer ak_your_token"
```

### Response

```json theme={null}
{
  "id": "cls_abc123",
  "slug": "general",
  "name": "General",
  "systemPrompt": "You are a helpful customer assistant...",
  "welcomeMessage": "Hello! How can I help you?",
  "conversationStarters": [
    { "text": "What do you offer?", "emoji": "" }
  ],
  "isDefault": true,
  "isActive": true,
  "createdAt": "2024-01-15T10:30:00Z",
  "updatedAt": "2024-02-01T14:00:00Z"
}
```

## POST /tenants/{slug}/segments

Create a new segment.

**Required scope:** `segments:write`

### Request

```bash theme={null}
curl -X POST https://api.animam.ai/tenants/my-company/segments \
  -H "Authorization: Bearer ak_your_token" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Support",
    "systemPrompt": "You are a support agent. Help users resolve technical issues.",
    "welcomeMessage": "Need help? Describe your issue.",
    "conversationStarters": [
      { "text": "I have a bug to report", "emoji": "" },
      { "text": "My account is locked", "emoji": "" }
    ]
  }'
```

### Response

Returns the created segment object with generated `id` and `slug`.

## PUT /tenants/{slug}/segments/{id}

Update an existing segment. Send only the fields you want to change.

**Required scope:** `segments:write`

### Request

```bash theme={null}
curl -X PUT https://api.animam.ai/tenants/my-company/segments/cls_abc123 \
  -H "Authorization: Bearer ak_your_token" \
  -H "Content-Type: application/json" \
  -d '{
    "systemPrompt": "You are Max, the community assistant...",
    "welcomeMessage": "Bonjour ! Comment puis-je vous aider ?"
  }'
```

## DELETE /tenants/{slug}/segments/{id}

Delete a segment. The default segment cannot be deleted.

**Required scope:** `segments:write`

```bash theme={null}
curl -X DELETE https://api.animam.ai/tenants/my-company/segments/cls_support \
  -H "Authorization: Bearer ak_your_token"
```

## Segment fields

| Field                  | Type    | Description                                                               |
| ---------------------- | ------- | ------------------------------------------------------------------------- |
| `name`                 | string  | Segment name (required on create)                                         |
| `systemPrompt`         | string  | Full system prompt for the AI (required on create)                        |
| `welcomeMessage`       | string  | First message shown to visitors                                           |
| `conversationStarters` | array   | Up to 4 suggested questions: `[{ text, emoji }]`. Each text max 50 chars. |
| `isActive`             | boolean | Enable or disable the segment                                             |

## Targeting a segment from the widget

Use the `data-segment` attribute:

```html theme={null}
<script
  src="https://cdn.animam.ai/widget.js?v=1.1"
  data-tenant="my-company"
  data-segment="support"
></script>
```

Or via the Chat API with the `segment` query parameter:

```bash theme={null}
curl -X POST "https://api.animam.ai/chat/my-company?segment=support" \
  -H "Content-Type: application/json" \
  -d '{ "message": "Help!", "sessionId": "abc" }'
```