04 / REST API

REST API

The REST API is for putting your bot inside your own product: your mobile app, your backend, or an internal tool. If all you want is a chat bubble on your website, you do not need this page at all, the snippet handles everything for you.

Base URL https://equilai.ai/api/chat. Create an API key in Dashboard → API, send it as an x-api-key header (or in the JSON body as apiKey), and keep it on your server, never in browser code. API access must be enabled on your plan. See Authentication →

Endpoint 1

List your bots

Look up which bot your API key belongs to, with its id and label, so you know exactly which bot you are integrating. Each key maps to one bot.

Request

http

GET https://equilai.ai/api/chat/bots
x-api-key: YOUR_API_KEY

Response

json

{
  "bots": [
    {
      "id": "019ec65b-f266-7e44-849c-d8ed300802e4",
      "name": "Aria",
      "label": "Production support bot"
    }
  ]
}

Endpoint 2

Start a conversation

Create a conversation session. Returns a conversationId to pass with every message. Nothing is stored until the first message is sent, so idle sessions don't count against your monthly limit.

Request

http

POST https://equilai.ai/api/chat/start
Content-Type: application/json

{
  "apiKey": "YOUR_API_KEY"
}

Response

json

{
  "message": "Successfully started a new conversation",
  "conversationId": "5691c459..."
}

Endpoint 3

Send a message

Send a user message and receive the AI reply in response. Pass the same apiKey and the conversationId from the start call. attachmentIds is optional and references files uploaded via the endpoint below (up to 4 per message); a message may also be attachments-only with an empty message.

Request

http

POST https://equilai.ai/api/chat/bot
Content-Type: application/json

{
  "apiKey": "YOUR_API_KEY",
  "conversationId": "5691c459...",
  "message": "What is on this receipt?",
  "attachmentIds": ["0197b1c2-..."]
}

Response

json

{
  "response": "We're open Monday to Friday, 9 am to 6 pm."
}

Endpoint 4

Upload an attachment

Upload an image or PDF (max 10 MB) as multipart/form-data, then pass the returned id in the next message's attachmentIds. The bot reads images directly (its model supports vision) and extracts text from PDFs. Files are removed after 7 days.

Request

http

POST https://equilai.ai/api/chat/upload
Content-Type: multipart/form-data
x-api-key: YOUR_API_KEY

file: (binary, max 10 MB)

Response

json

{
  "attachment": {
    "id": "0197b1c2-...",
    "kind": "image",
    "name": "receipt.png",
    "size": 48213,
    "url": "https://equilai.ai/uploads/chat/0197b1c2-....png",
    "expired": false
  }
}

Quick test

One-line cURL

Copy your key from the dashboard and run:

bash

curl -X POST "https://equilai.ai/api/chat/start" \
     -H "Content-Type: application/json" \
     -d '{"apiKey": "YOUR_API_KEY"}'

Error codes

Code	Meaning
400	Missing or invalid field (apiKey, message, or an attachment reference)
403	API access is not enabled on your plan
404	Bot or conversation not found. Check your API key
413	Attachment larger than the 10 MB limit
429	Rate limit or the bot's monthly conversation limit reached
500	Server error. Contact [email protected]

Just want to add a chat bubble to your site? See Installation →

04 / REST API

REST API

Endpoint 1

List your bots

Look up which bot your API key belongs to, with its id and label, so you know exactly which bot you are integrating. Each key maps to one bot.

Request

http

GET https://equilai.ai/api/chat/bots
x-api-key: YOUR_API_KEY

Response

json

{
  "bots": [
    {
      "id": "019ec65b-f266-7e44-849c-d8ed300802e4",
      "name": "Aria",
      "label": "Production support bot"
    }
  ]
}

Endpoint 2

Start a conversation

Create a conversation session. Returns a conversationId to pass with every message. Nothing is stored until the first message is sent, so idle sessions don't count against your monthly limit.

Request

http

POST https://equilai.ai/api/chat/start
Content-Type: application/json

{
  "apiKey": "YOUR_API_KEY"
}

Response

json

{
  "message": "Successfully started a new conversation",
  "conversationId": "5691c459..."
}

Endpoint 3

Send a message

Request

http

POST https://equilai.ai/api/chat/bot
Content-Type: application/json

{
  "apiKey": "YOUR_API_KEY",
  "conversationId": "5691c459...",
  "message": "What is on this receipt?",
  "attachmentIds": ["0197b1c2-..."]
}

Response

json

{
  "response": "We're open Monday to Friday, 9 am to 6 pm."
}

Endpoint 4

Upload an attachment

Request

http

POST https://equilai.ai/api/chat/upload
Content-Type: multipart/form-data
x-api-key: YOUR_API_KEY

file: (binary, max 10 MB)

Response

json

{
  "attachment": {
    "id": "0197b1c2-...",
    "kind": "image",
    "name": "receipt.png",
    "size": 48213,
    "url": "https://equilai.ai/uploads/chat/0197b1c2-....png",
    "expired": false
  }
}

Quick test

One-line cURL

Copy your key from the dashboard and run:

bash

curl -X POST "https://equilai.ai/api/chat/start" \
     -H "Content-Type: application/json" \
     -d '{"apiKey": "YOUR_API_KEY"}'

Error codes

Code	Meaning
400	Missing or invalid field (apiKey, message, or an attachment reference)
403	API access is not enabled on your plan
404	Bot or conversation not found. Check your API key
413	Attachment larger than the 10 MB limit
429	Rate limit or the bot's monthly conversation limit reached
500	Server error. Contact [email protected]

Just want to add a chat bubble to your site? See Installation →