API overview

The Chat Thing REST API lets your own app or backend chat with a bot and manage its manual knowledge. It's part of the API channel, which each bot turns on separately.

What the API covers

To build and configure bots from code or an AI agent (create bots, add websites, set up power-ups), use the MCP server instead. It covers far more than the REST API.

Base URL

All REST endpoints live under:

https://app.chatthing.ai/api/public/channels/{channelId}/{version}

• {channelId} is your bot's API channel ID (see below).
• {version} is 2.0 or 1.0 (see Versions).

Older integrations that call https://chatthing.ai/api/public/... still work: those requests are forwarded to app.chatthing.ai. Use app.chatthing.ai for anything new.

Authentication

Every request needs your bot's API channel Channel ID in the URL and its Secret key in the X-API-Secret-Key header.

The secret key belongs to one bot's API channel. It only works for that bot, and each bot you want to call needs its own API channel and key. There's no account-wide REST API key.

Get your Channel ID and secret key

Who can do this: team owners and admins.

1. Open your bot and go to the Channels tab.
2. Turn on the API channel. Its settings page opens.
   
3. Copy the Channel ID.
4. Under Secret key, click Generate new secret (or Generate secret), and copy the key straight away. You won't see it again once you've saved.
5. Click Save.

To rotate the key, generate a new one and save. The old key stops working as soon as you save.

Send the headers

Content-Type: application/json
X-API-Secret-Key: {secretKey}

Versions

The version is part of the URL. Both 2.0 and 1.0 are served, and every endpoint works on both.

Request bodies, authentication and all non-streaming responses are identical on both versions. Only the format of stream: true responses changes. See Stream replies.

Status codes

Error responses are JSON with a statusCode and a statusMessage describing the problem. Data source endpoints also return "success": false in the body when they fail.

Usage limits

The API uses the same limits as every other channel. When one is reached, the request fails with 429 Too Many Requests.

For Send a message, the 429 response includes a Retry-After header (seconds until the limit resets) and a structured body:

{
  "statusCode": 429,
  "statusMessage": "bot-daily-token-limit-reached",
  "data": {
    "error": {
      "code": "bot_daily_token_limit_reached",
      "message": "This bot has hit its daily token limit. Resets at the start of the next day.",
      "scope": "bot",
      "details": {
        "limit": 600000,
        "used": 603646,
        "resetAt": "2026-05-27T00:00:00.000Z"
      }
    }
  }
}

• code is stable and safe to branch on. message is readable English and may change.
• scope is bot or team. Use it to tell bot limits from team limits rather than parsing code.
• details.resetAt is a UTC ISO 8601 timestamp.

Start a conversation also returns 429 when a token limit is reached, but with a plain statusMessage and no structured data.

For the data sources API, 429 means the data source is already syncing, you've reached your plan's data source limit, or you're out of storage tokens. The statusMessage says which.

Next steps

• Chat API: start conversations, send messages and stream replies.
• Data sources API: keep a bot's knowledge in sync from your own system.
• Webhooks: get notified when things happen.