API overview

The API reference covers the external team API protected by bearer API keys.

External API groups

Base path:

/api/external

Current endpoints:

• GET /api/external/account/stats
• GET /api/external/account/plan
• GET /api/external/bots
• GET /api/external/bots/{id}/stats
• GET /api/external/bots/{id}/conversations
• GET /api/external/bots/{id}/conversations/{conversationId}
• GET /api/external/bots/{id}/messages
• GET /api/external/bots/{id}/messages/{questionId}

This API is read-only today. It is intended for retrieving bot metadata, conversations, and message history for the team associated with the API key.

Endpoint categories

Account endpoints

Use these endpoints to retrieve workspace-level information for the team connected to the API token:

• current usage and totals
• current plan and subscription state
• plan limits and enabled features

Bot endpoints

Use these endpoints to retrieve:

• bot metadata
• bot-level usage totals
• conversation lists and conversation details
• message lists and message details

Authentication model

The external API uses Authorization: Bearer <api_token>.

Response format

The external JSON APIs return standard JSON objects and arrays. For collection endpoints, the current shape is:

{
  "items": []
}

Common HTTP status codes

Before you build

Start with API authentication, then use the bots endpoint to discover the bot ids you want to work with.

Related articles