API docs

External bots, conversations, and messages API

Use the external team API to list bots and retrieve conversation or message history for a team.

Last updated: 2026-03-21

The current external team API is read-only. It does not create or update bots. It gives you access to existing bot data inside the team connected to the API key.

Base path

/api/external

Account stats

Request

GET /api/external/account/stats
Authorization: Bearer YOUR_API_TOKEN

Example

curl -X GET "https://app.askanydocs.com/api/external/account/stats" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/json"

Response

{
  "team": {
    "id": 12,
    "name": "AskAnyDocs's team"
  },
  "stats": {
    "bots": 3,
    "resources": 24,
    "chunks": 643,
    "messages": 25,
    "conversations": 15,
    "team_members": 2
  }
}

Current plan

Request

GET /api/external/account/plan
Authorization: Bearer YOUR_API_TOKEN

Example

curl -X GET "https://app.askanydocs.com/api/external/account/plan" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/json"

Response shape

{
  "team": {
    "id": 12,
    "name": "AskAnyDocs's team"
  },
  "subscription": {
    "plan_code": "pro",
    "billing_interval": "monthly",
    "status": "active",
    "started_at": "2026-03-01T00:00:00+00:00",
    "current_period_start_at": "2026-03-01T00:00:00+00:00",
    "current_period_end_at": "2026-04-01T00:00:00+00:00",
    "expires_at": null,
    "canceled_at": null
  },
  "plan": {
    "code": "pro",
    "name": "Pro",
    "description": "For growing products that need analytics and integrations.",
    "currency": "$",
    "monthly_price": 9900,
    "yearly_price": 99000,
    "is_free": false,
    "is_highlighted": true,
    "duration_days": null,
    "status": "active",
    "is_public": true,
    "available_for_new_subscriptions": true
  },
  "usage": {
    "bots": 3,
    "chunks": 643,
    "messages": 25,
    "team_members": 2
  },
  "limits": [
    {
      "key": "bots",
      "label": "Bots",
      "used": 3,
      "limit": 5,
      "remaining": 2,
      "is_unlimited": false
    }
  ],
  "features": [
    {
      "key": "api_access",
      "label": "API access",
      "enabled": true
    }
  ]
}

Notes

  • monthly_price and yearly_price are returned in minor currency units
  • limits include both the raw limit and the current usage snapshot
  • features show which plan capabilities are enabled for the current subscription

List bots

Request

GET /api/external/bots
Authorization: Bearer YOUR_API_TOKEN

Example

curl -X GET "https://app.askanydocs.com/api/external/bots" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/json"

Response

[
  {
    "id": "018f3f20-f3d8-7af1-9d2b-2f3de1f7f8ab",
    "name": "AskAnyDocs Support",
    "language": "en",
    "active": true,
    "widget": {
      "color": "#2563eb",
      "avatar_icon": "data:image/png;base64,...",
      "button_icon": "comments",
      "button_text": "Ask us",
      "button_position": "right",
      "initial_message": "How can I help today?",
      "fallback_link": "https://example.com/contact",
      "show_source_links": false,
      "allowed_domains": [
        "askanydocs.com"
      ]
    }
  }
]

Notes

  • only bots from the token's team are returned
  • widget settings are nested under widget
  • inactive bots can still appear in this endpoint, with active: false

Bot stats

Request

GET /api/external/bots/{id}/stats
Authorization: Bearer YOUR_API_TOKEN

Response

{
  "bot": {
    "id": "018f3f20-f3d8-7af1-9d2b-2f3de1f7f8ab",
    "name": "AskAnyDocs Support",
    "language": "en",
    "active": true
  },
  "stats": {
    "resources": 12,
    "chunks": 643,
    "conversations": 15,
    "messages": 25
  }
}

List conversations for a bot

Request

GET /api/external/bots/{id}/conversations?limit=100&last_id=...
Authorization: Bearer YOUR_API_TOKEN

Query parameters

Parameter Type Description
limit integer Max number of items returned. The backend clamps it between 1 and 200. Default is 100.
last_id string Optional cursor-like value used to request older items after a known conversation id.

Example

curl -X GET "https://app.askanydocs.com/api/external/bots/BOT_ID/conversations?limit=50" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/json"

Response

{
  "items": [
    {
      "id": "0195b4d0-b1a6-7a80-9157-3d459e4f3b44",
      "visitor_id": "2u1f7anp8g1b1m0c8df4b7u1g7",
      "started_at": "2026-03-21 09:18:22",
      "first_question": "What are your pricing plans?",
      "messages_count": 4,
      "country_code": "US"
    }
  ]
}

Conversation details

Request

GET /api/external/bots/{id}/conversations/{conversationId}
Authorization: Bearer YOUR_API_TOKEN

Response shape

{
  "conversation_id": "0195b4d0-b1a6-7a80-9157-3d459e4f3b44",
  "metadata": {
    "page_url": "https://askanydocs.com/pricing"
  },
  "messages": [
    {
      "id": "0195b4d0-b1a6-7a80-9157-3d459e4f3b44",
      "role": "user",
      "content": "What are your pricing plans?",
      "created_at": "2026-03-21 09:18:22",
      "page_url": "https://askanydocs.com/pricing",
      "escalation": null
    }
  ],
  "user": {
    "name": null,
    "email": null
  }
}

List messages for a bot

Request

GET /api/external/bots/{id}/messages?limit=100&last_id=...
Authorization: Bearer YOUR_API_TOKEN

Query parameters

Parameter Type Description
limit integer Max number of items returned. The backend clamps it between 1 and 200. Default is 100.
last_id string Optional cursor-like value used to continue pagination from a known message id.

Example

curl -X GET "https://app.askanydocs.com/api/external/bots/BOT_ID/messages?limit=25" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/json"

Response shape

The response shape is:

{
  "items": [
    {
      "question_id": "0195b4d0-b1a6-7a80-9157-3d459e4f3b44",
      "asked_at": "2026-03-21 09:18:22",
      "question": "What are your pricing plans?",
      "answer": "We offer Free, Basic, Pro, and Business plans.",
      "has_escalation": false,
      "escalation_reason": null
    }
  ]
}

Message item fields

Field Type Description
question_id string Unique message identifier.
asked_at string Message creation timestamp as returned by the backend.
question string Original user question.
answer string or null Assistant answer if one was stored.
has_escalation boolean Indicates whether the message triggered human escalation metadata.
escalation_reason string or null Escalation reason when available.

Notes

  • messages are ordered by newest first
  • last_id acts as a cursor-like filter for older items
  • message details such as rewritten question, chunk matches, page URL, and referrer are available in internal dashboard views, but are not currently part of the external list endpoint

Message details

Request

GET /api/external/bots/{id}/messages/{questionId}
Authorization: Bearer YOUR_API_TOKEN

Response shape

{
  "question_id": "0195b4d0-b1a6-7a80-9157-3d459e4f3b44",
  "conversation_id": "0195b4d0-b1a6-7a80-9157-3d459e4f3b44",
  "asked_at": "2026-03-21 09:18:22",
  "question": "What are your pricing plans?",
  "rewritten_question": null,
  "answer": "We offer Free, Basic, Pro, and Business plans.",
  "page_url": "https://askanydocs.com/pricing",
  "referrer": null,
  "chunks": [
    {
      "id": "chunk_123",
      "score": 0.92,
      "text": "Pricing details...",
      "source_location": "https://askanydocs.com/pricing",
      "source_page_number": null,
      "knowledge_source_id": "source_123"
    }
  ],
  "escalation": null
}

Error cases

If the bot does not belong to the current team or does not exist, the API returns:

{
  "message": "Bot not found"
}

with HTTP status 404.

Previous

API authentication
Next

Knowledge sources API

Related articles

API overview

Start here to understand the external AskAnyDocs API surface before using specific endpoints.

API authentication

Use bearer API keys to authenticate requests to the external AskAnyDocs team API.

Knowledge sources API

Learn what the external API exposes today and why knowledge-source management is not part of the public API reference yet.