Introduction

A small JSON-over-HTTPS API. Six endpoints, no SDK.

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.

See Authentication for how to get each one.

Endpoints

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

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.

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	120 / minute
API key — reads	300 / minute
File uploads	20 / minute

A 429 includes retry_after in seconds:

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

Sizes

Thing	Limit
Request body	256 KB
Messages per call	10
Blocks per message	25
Image upload	10 MB
File upload	25 MB

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 — which matters, because Make, n8n, and Zapier all retry. See Updating messages.

Overview

Messages

Files

Base URL

Keys

Token in the path

Bearer key

Endpoints

Rules

Errors

Rate limits

Sizes

Safe retries

​Base URL

​Keys

Token in the path

Bearer key

​Endpoints

​Rules

​Errors

​Rate limits

​Sizes

​Safe retries

Base URL

Keys

Endpoints

Rules

Errors

Rate limits

Sizes

Safe retries