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.

Endpoints to view conversation history.

​
GET /tenants//conversations

List conversations. Required scope: conversations:read

​
Request

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

​
Query Parameters

ParamTypeDescription
pagenumberPage (default: 1)
limitnumberConversations per page (default: 20, max 100)
fromstringStart date (ISO 8601)
tostringEnd date (ISO 8601)
channelstringFilter by channel (web, agent, voice, …)
segmentstringFilter by segment slug
visitorIdstringFilter by visitor profile id
toolTypestringOnly conversations that used this tool type

​
Response

{
  "conversations": [
    {
      "id": "conv_abc123",
      "sessionId": "sess_xyz789",
      "createdAt": "2024-01-25T10:30:00Z",
      "messageCount": 8,
      "pageUrl": "/pricing",
      "channel": "web",
      "status": "BOT",
      "visitorType": "human",
      "segment": { "slug": "pricing", "name": "Pricing" },
      "intent": "What are your prices?",
      "firstUserMessage": "What are your prices?",
      "preview": "What are your prices?",
      "toolCallsCount": 2,
      "feedback": { "positive": 1, "negative": 0 },
      "toolHistory": [
        { "toolName": "submit_form", "toolType": "SUBMIT_FORM", "input": {}, "result": {}, "timestamp": "2024-01-25T10:44:00Z" }
      ]
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 156,
    "pages": 8
  }
}
intent / firstUserMessage expose the visitor’s first message directly, and toolCallsCount is computed server-side (from the persisted tool_history, MCP tool calls included) — no need to fetch the full transcript to know what was asked or whether a tool fired.

​
GET /tenants//conversations/

Retrieve a complete conversation with all messages. Required scope: conversations:read

​
Request

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

​
Response

{
  "id": "conv_abc123",
  "sessionId": "sess_xyz789",
  "segment": "pricing",
  "startedAt": "2024-01-25T10:30:00Z",
  "lastMessageAt": "2024-01-25T10:45:00Z",
  "messages": [
    {
      "id": "msg_001",
      "role": "user",
      "content": "Hello, what are your prices?",
      "timestamp": "2024-01-25T10:30:00Z"
    },
    {
      "id": "msg_002",
      "role": "assistant",
      "content": "Hello! We offer 3 plans...",
      "timestamp": "2024-01-25T10:30:02Z"
    },
    {
      "id": "msg_003",
      "role": "user",
      "content": "And for the Pro plan?",
      "timestamp": "2024-01-25T10:31:00Z"
    }
  ],
  "metadata": {
    "userAgent": "Mozilla/5.0...",
    "referrer": "https://google.com",
    "page": "/pricing"
  }
}

​
GET /tenants//conversations/stats

Aggregated conversation analytics over a time window — the REST equivalent of the MCP get_bot_stats overview, reachable with a plain tenant key (no MCP client needed). Read-only and idempotent: ideal for a cron, dashboard or Grafana scrape. Required scope: stats:read (the legacy ak_… tenant key carries it).

​
Request

curl "https://api.animam.ai/tenants/my-company/conversations/stats?from=2024-01-19" \
  -H "Authorization: Bearer ak_your_token"
Authenticate ak_… API tokens with Authorization: Bearer. The X-API-Key header is reserved for a tenant’s legacy plain API key and returns 401 for an ak_… token.

​
Query Parameters

ParamTypeDescription
from, tostringISO date window (default: last 30 days; capped to 1 year)
granularitystringTimeline bucket: day (default), week, month
segmentstringFilter by segment slug
channelstringFilter by channel (web, agent, …)
windowstringall → also include all-time totals (allTime)

​
Response

{
  "window": { "from": "2024-01-19T00:00:00Z", "to": "2024-02-18T00:00:00Z", "granularity": "day" },
  "totals": {
    "conversations": 4,
    "messages": 30,
    "escalated": 0,
    "avgMessagesPerConversation": 7.5,
    "withToolCalls": 3,
    "toolCallsTotal": 5
  },
  "satisfaction": { "positive": 0, "negative": 0, "rate": null },
  "timeline": [
    { "date": "2024-01-30", "conversations": 2, "messages": 10 },
    { "date": "2024-01-31", "conversations": 1, "messages": 4 }
  ],
  "byChannel": { "web": 4 },
  "bySegment": { "default": 4 },
  "byStatus": { "BOT": 4 },
  "byVisitorType": { "human": 3, "agent": 1 },
  "topTools": [ { "name": "search_near_location", "calls": 3 } ],
  "byPage": [
    { "page": "/", "conversations": 2 },
    { "page": "/pages/associations-sante", "conversations": 1 }
  ],
  "topIntents": [
    { "question": "associations sportives près de Lyon", "count": 2 }
  ]
}
byPage (where engagement starts) and topIntents (what visitors actually ask) are the highest-signal fields. toolCallsTotal / topTools are computed from the persisted tool_history, MCP calls included — not a client-side heuristic.

​
GET /tenants//conversations/export

Export the conversation list (one row per conversation) as CSV (default) or NDJSON, for reporting. Required scope: conversations:read 
curl "https://api.animam.ai/tenants/my-company/conversations/export?from=2024-01-19&format=csv" \
  -H "Authorization: Bearer ak_your_token" -o conversations.csv

​
Query Parameters

ParamTypeDescription
from, tostringISO window (default last 30 days, capped to 1 year)
channelstringFilter by channel
segmentstringFilter by segment slug
formatstringcsv (default) or ndjson
limitnumberMax rows (default 1000, max 5000)

​
Response (CSV)

id,created_at,updated_at,channel,status,visitor_type,segment,page_url,message_count,tool_calls_count,intent
conv_abc123,2024-01-25T10:30:00Z,2024-01-25T10:45:00Z,web,BOT,human,default,/pricing,8,2,"What are your prices?"

​
GET /tenants//conversations/stats/export

Export one aggregated dataset as CSV (default) or NDJSON. Required scope: stats:read 
curl "https://api.animam.ai/tenants/my-company/conversations/stats/export?dataset=topIntents&format=csv" \
  -H "Authorization: Bearer ak_your_token" -o intents.csv

​
Query Parameters

ParamTypeDescription
from, tostringISO window (default last 30 days, capped to 1 year)
granularitystringday (default), week, month (for the timeline dataset)
segment, channelstringSame filters as /conversations/stats
datasetstringtimeline (default), byPage, topIntents, topTools
formatstringcsv (default) or ndjson

​
Response (CSV, dataset=topIntents)

question,count
"associations sportives près de Lyon",2
"comment faire un don déductible",1