Introduction - My AI Chatbot

A small JSON-over-HTTPS API, no SDK. It covers three things: messages into your bot’s conversations, files to attach to them, and hosted Pages your bot or backend publishes.

Base URL

https://app.my-aichatbot.com

Every endpoint lives under /api/v1. HTTPS only.

Keys

Two ways to prove who you are, depending on the endpoint.

Token in the path

/api/v1/responses/{token} carries its own key. Send no Authorization header. It expires after 45 minutes.

Bearer key

Everything else takes Authorization: Bearer mac_live_…. One key per chatbot, and it never expires. Writing Pages also needs Pages write turned on for the key.

See Authentication for how to get each one.

Endpoints

Messages

Method	Path	Key
`POST`	`/api/v1/responses/{token}`	Token
`POST`	`/api/v1/conversations/{conversation_id}/messages`	Key
`GET`	`/api/v1/conversations/{conversation_id}/messages`	Key
`PATCH`	`/api/v1/messages/{message_id}`	Key

Files

Method	Path	Key
`POST`	`/api/v1/responses/{token}/files`	Token
`POST`	`/api/v1/bots/{chatbot_id}/files`	Key

Pages

Method	Path	Key
`POST`	`/api/v1/pages`	Key + Pages write
`GET`	`/api/v1/pages`	Key
`GET`	`/api/v1/pages/{page_id}`	Key
`PATCH`	`/api/v1/pages/{page_id}`	Key + Pages write
`DELETE`	`/api/v1/pages/{page_id}`	Key + Pages write
`PUT`	`/api/v1/pages/{page_id}/content`	Key + Pages write
`GET`	`/api/v1/pages/{page_id}/versions`	Key
`GET`	`/api/v1/pages/{page_id}/versions/{version}`	Key
`POST`	`/api/v1/pages/{page_id}/rollback`	Key + Pages write
`GET`	`/api/v1/pages/by-slug/{slug}`	Key
`PUT`	`/api/v1/pages/by-slug/{slug}`	Key + Pages write

Reads see every Page in the workspace. Writes only touch Pages owned by the key’s own bot.

Rules

JSON in, JSON out. Send Content-Type: application/json, except on the file upload endpoints, which take multipart/form-data.
snake_case everywhere.
Times are ISO 8601 in UTC (2026-07-17T03:15:12.398Z).
Ids are plain strings. Do not try to read meaning into them.
Success includes "ok": true. Failure includes "ok": false and an error object. The GET history endpoint is the one exception: it returns the data directly.
Error codes on the Pages endpoints are always UPPER_SNAKE (INVALID_API_KEY, RATE_LIMITED). The messages and files endpoints mix cases (invalid_api_key, PAYLOAD_TOO_LARGE). Match on the exact string.

Errors

One shape everywhere:

{
  "ok": false,
  "error": {
    "code": "conversation_taken_over",
    "message": "An operator has taken over this conversation."
  }
}

Block Kit failures add an issues list that points at each problem:

{
  "ok": false,
  "error": {
    "code": "BLOCK_VALIDATION_FAILED",
    "message": "1 issue(s) found in your Block Kit payload.",
    "issues": [
      {
        "code": "INSECURE_URL",
        "path": "/messages/0/blocks/2/url",
        "message": "URLs must use https:// (got http://).",
        "severity": "error"
      }
    ]
  }
}

Full list: Limits and errors.

Rate limits

Scope	Limit
Response URL token	30 requests / minute
API key, writes (messages and Pages)	120 / minute
API key, reads (messages and Pages)	300 / minute
File uploads	20 / minute

A 429 tells you how long to wait: retry_after on the messages and files endpoints, retry_after_seconds on the Pages endpoints.

{
  "ok": false,
  "error": { "code": "rate_limited", "message": "Too many requests.", "retry_after": 12 }
}

Sizes

Thing	Limit
Request body (messages)	256 KB
Messages per call	10
Blocks per message	25
Image upload	10 MB
File upload	25 MB
Page HTML per version	512 KB on Free, up to 5 MB by plan

Safe retries

Give a message a mid, and sending it again updates instead of duplicating. Build the mid from the event’s event_id, and your whole integration becomes safe to retry. That matters, because Make, n8n, and Zapier all retry. See Updating messages. Pages are retry-safe by design: PUT /pages/by-slug/{slug} creates on the first call and updates after that, and content identical to the current version is skipped rather than stored twice.

​Base URL

​Keys

Token in the path

Bearer key

​Endpoints

​Messages

​Files

​Pages

​Rules

​Errors

​Rate limits

​Sizes

​Safe retries