API Reference - Animam Documentation

The Animam API allows you to manage your chatbot programmatically.

Base URL

https://api.animam.ai

Authentication

The API supports 3 authentication methods:

Method	Header	Usage
Bearer Token	`Authorization: Bearer ak_...`	Recommended for API
Session Cookie	`animam_session`	Dashboard only
Legacy API Key	`X-API-Key: ...`	Backward compatibility

Create your API tokens in Dashboard > API Tokens.

Scopes

Each token has specific permissions:

Scope	Description
`segments:read`	Read segments
`segments:write`	Modify segments
`corpus:read`	Read corpus
`corpus:write`	Modify corpus
`tools:read`	Read tools
`tools:write`	Modify tools
`visitors:read`	Read visitors
`visitors:write`	Modify visitors
`conversations:read`	View conversations
`conversations:write`	Modify conversations
`settings:read`	Read settings
`settings:write`	Modify settings
`billing:read`	Read billing
`stats:read`	Read analytics
`*`	Full access

Response format

All responses are in JSON.

{
  "corpus": [...],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 42
  }
}

Errors

Code	Description
`400`	Invalid request
`401`	Not authenticated
`403`	Access denied (missing scope)
`404`	Resource not found
`429`	Rate limit exceeded
`500`	Server error

{
  "error": "Missing required scope: corpus:write"
}

Rate Limits

Rate limiting is per client IP:

API endpoints: 60 requests/minute
Chat: 20 requests/minute and 200 requests/hour
Auth: 5 requests/minute

Exceeding a limit returns 429 with a Retry-After header.

Endpoints

Tenant

Tenant info and settings

Corpus

Manage the knowledge base

Conversations

Conversation history

Chat

Send messages