API docs

External bots, conversations, and messages API

This API reference explains the read-only bot, conversation, and message endpoints available through the AskAnyDocs external team API, including request examples, response shapes, and integration use cases.

Last updated: 2026-05-31

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

The AskAnyDocs external API lets teams retrieve account, bot, conversation, and message data using bearer API keys. Start here to understand the base path, endpoint categories, authentication model, status codes, and current read-only scope.

API authentication

AskAnyDocs external API requests require a bearer API key in the Authorization header. Learn how tokens are generated, how team scoping works, how to test a request, and how to keep API keys secure.

Knowledge sources API

Knowledge-source management is not part of the public external API today. This guide explains the current boundary, what integrations can read, and how to manage website pages, sitemaps, URL lists, and files through the dashboard.