Skip to main content

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 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//segments

List all segments. Required scope: segments:read

​
Request

curl https://api.animam.ai/tenants/my-company/segments \
  -H "Authorization: Bearer ak_your_token"

​
Response

[
  {
    "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"
  }
]
The systemPrompt field is excluded from the list response. Use GET /tenants/{slug}/segments/{id} to read it.

​
GET /tenants//segments/

Get a single segment with its full system prompt. Required scope: segments:read

​
Request

curl https://api.animam.ai/tenants/my-company/segments/cls_abc123 \
  -H "Authorization: Bearer ak_your_token"

​
Response

{
  "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//segments

Create a new segment. Required scope: segments:write

​
Request

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//segments/

Update an existing segment. Send only the fields you want to change. Required scope: segments:write

​
Request

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//segments/

Delete a segment. The default segment cannot be deleted. Required scope: segments:write 
curl -X DELETE https://api.animam.ai/tenants/my-company/segments/cls_support \
  -H "Authorization: Bearer ak_your_token"

​
Segment fields

FieldTypeDescription
namestringSegment name (required on create)
systemPromptstringFull system prompt for the AI (required on create)
welcomeMessagestringFirst message shown to visitors
conversationStartersarrayUp to 4 suggested questions: [{ text, emoji }]. Each text max 50 chars.
isActivebooleanEnable or disable the segment

​
Targeting a segment from the widget

Use the data-segment attribute: 
<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: 
curl -X POST "https://api.animam.ai/chat/my-company?segment=support" \
  -H "Content-Type: application/json" \
  -d '{ "message": "Help!", "sessionId": "abc" }'