Binom AI Public API Documentation | Developer Guide

Question

Accepted Answer

This page documents the BINOM AI public API: how to authenticate, create chats, exchange messages with your synthetic employee, collect feedback, and work with the knowledge base and price lists.

For a plain-language overview of what the API does and why you'd use it, see the BINOMAI.com API FAQ. This page is the full technical reference.

Overview

Base URL: https://prod-api.binomai.com
Format: JSON request/response bodies (form-encoded also accepted for the examples shown here)
Auth: HTTP Basic Auth, API key as username
Typical flow: create a chat → send a message → get the synthetic employee's reply in the same response → optionally rate the reply

Quick start

# 1. Create a chat
curl https://prod-api.binomai.com/api/public/chats \
  -u YOUR_API_KEY: \
  -d chat_id="order_12345"

# 2. Send a message - the reply comes back immediately, in this same response
curl https://prod-api.binomai.com/api/public/chats/order_12345/messages \
  -u YOUR_API_KEY: \
  -d content="Hello, could you tell me the delivery price?"

# 3. (optional) Retrieve the full conversation
curl https://prod-api.binomai.com/api/public/chats/order_12345/messages \
  -u YOUR_API_KEY:

Authentication with BINOM AI public API

All public endpoints use HTTP Basic Auth:

username – your API key
password – not used, leave empty

curl https://prod-api.binomai.com/api/public/chats -u YOUR_API_KEY:

Getting a key: Dashboard → Organization Integrations → type API. The key is shown as api_key. Revoking a key: delete the corresponding integration. Reissuing a key: create a new API-type integration; the previous key stops working once its integration is deleted.

Authentication errors

An invalid or missing key returns 401 with this body:

{ "status": "error", "message": "Authentication failed" }

All other error responses across the API use a different shape (full list of codes further down this page):

{ "error": "error text" }

or, when multiple issues apply:

{ "error": ["error one", "error two"] }

Endpoint Reference

`POST /api/public/chats` – Create a chat

Request body:

Field	Type	Required	Description
`chat_id`	string	no	Your own external ID for this conversation (e.g. an order ID). This is the field to use – chats are the only supported mode; the legacy "threads" mode is no longer used.

curl https://prod-api.binomai.com/api/public/chats \
  -u YOUR_API_KEY: \
  -d chat_id="order_12345"

Response (201):

{
  "id": "8f14e2b1-2c3d-4e5f-9a0b-1c2d3e4f5a6b",
  "form": "api",
  "state": "unreviewed",
  "ai_state": "ai_active",
  "contacts": {},
  "data": {},
  "integration_chat_id": "order_12345",
  "created_at": "2026-08-20T10:00:00Z",
  "updated_at": "2026-08-20T10:00:00Z"
}

Field	Description
`id`	Internal UUID generated by BINOMAI.com. Not used in public API paths.
`form`	Channel/source of the chat: `public_chat`, `widget`, `helpcrunch`, `api`, `youtube`, `call`, `lawyer`, `person`, `tutor`, `realtime`, `interview`, `telegram`, `examination`, `instagram`
`state`	Review status: `unreviewed`, `reviewed`, `awaiting_operator`
`ai_state`	`ai_active` – the synthetic employee is responding automatically. `ai_blocked` – a human operator has taken over (via dashboard, widget, or a connected helpdesk); user messages are still saved, but there is no automatic reply. Cannot be toggled through the public API.
`contacts`	Object with the interlocutor's contact details (name, phone, email), if collected during the conversation. Usually empty right after chat creation.
`data`	Internal chat metadata (widget labels, context, etc.). Safe to ignore for integrations.
`integration_chat_id`	This is the ID you use as `{chat_id}` in every subsequent request – it's the same value you passed as `chat_id` above.
`created_at` / `updated_at`	Timestamps

A note on the two IDs: the field you send is called chat_id; the same value comes back in the response under the name integration_chat_id. The response also includes an unrelated internal id (a UUID) that is not used in any public API path. Always use integration_chat_id (i.e., your original chat_id) as {chat_id} in later requests.

Errors: 401

`GET /api/public/chats` – List chats

Query parameters:

Param	Type	Default	Max	Description
`per`	integer	10	500	Items per page
`page`	integer	1	–	Page number

curl "https://prod-api.binomai.com/api/public/chats?per=20&page=1" -u YOUR_API_KEY:

Response:

{
  "data": [ /* array of chat objects, same shape as in Create a chat */ ],
  "meta": { "total": 42, "page": 1, "per": 20, "pages": 3 }
}

Errors: 401 (also returned if the subscription is inactive)

`POST /api/public/chats/{chat_id}/messages` – Send a message

{chat_id} = the integration_chat_id from chat creation (your own external ID).

Request body:

Field	Type	Required	Description
`content`	string	yes	Message text. Use the literal value `[AUDIO]` when the message is a voice message.
`integration_message_id`	string	no	Your own message ID, for matching against your system.
`file_urls`	array of string	no	Public URLs of files to attach – the server downloads them itself.
`files`	array of string	no	IDs of files already uploaded directly (direct upload).

file_urls and files are not mutually exclusive – use either or both.

curl https://prod-api.binomai.com/api/public/chats/order_12345/messages \
  -u YOUR_API_KEY: \
  -d content="Hello, could you tell me the delivery price?" \
  -d integration_message_id="msg_001"

The synthetic employee's reply is returned immediately, in this same response – there is no separate polling step and no run_in_progress mechanism to wait on.

Response (201):

{
  "id": "a2b3c4d5-...",
  "integration_message_id": "msg_001",
  "content": "Delivery costs $8, takes 1-2 days",
  "role": "assistant",
  "files": [],
  "message_feedback": null,
  "created_at": "2026-08-20T10:00:05Z",
  "chat_id": "order_12345",
  "custom_icon_label": null
}

Field	Description
`id`	Message ID
`integration_message_id`	Your message ID, echoed back if you sent one
`content`	Message text – in the response, this is the assistant's reply
`role`	`user`, `assistant`, `system`, or `operator`
`files`	Attached files – field structure listed further down
`message_feedback`	Populated if feedback has been left on this message
`created_at`	Timestamp
`chat_id`	Your external chat ID
`custom_icon_label`	Widget icon label; usually empty for API-created messages

Note: contacts is not part of the message response – it only appears on the chat object.

Attached File Fields

Field	Required	Description
`id`	yes	File ID
`name`	no	File name
`signed_id`	yes	Signed ID
`content_type`	yes	MIME type
`url`	yes	File URL
`thumb`	no	Thumbnail URL
`transcription`	no	Transcription text (e.g. for audio)

Errors: 401, 402 (AI request balance not positive), 403 (subscription inactive), 429 (rate limit – thresholds listed later in this page)

`GET /api/public/chats/{chat_id}/messages` – Retrieve conversation history

Returns the entire conversation – there is no pagination on this endpoint; per/page have no effect.

curl https://prod-api.binomai.com/api/public/chats/order_12345/messages -u YOUR_API_KEY:

Response:

{
  "data": [
    { "id": "...", "role": "user", "content": "Hello" },
    { "id": "...", "role": "assistant", "content": "Good afternoon!" }
  ],
  "meta": { "total": 2 }
}

meta only contains total. A run_in_progress field exists in older client code paths but is obsolete – replies are synchronous now (see above), so there's nothing to poll for.

Errors: 401, 403, 429

`POST /api/public/chats/{chat_id}/messages/{id}/feedback` – Rate a reply

{id} = the message ID (from the send-message response or the history list).

Request body:

Field	Type	Required	Description
`state`	string	yes	`like`, `dislike`, or `remove` (clears a previous rating)
`comment`	string	required for `like`/`dislike`, not required for `remove`	Feedback comment

curl https://prod-api.binomai.com/api/public/chats/order_12345/messages/{id}/feedback \
  -u YOUR_API_KEY: \
  -d state="like" \
  -d comment="Helpful answer"

Response (201) – the feedback object:

{
  "id": "message_feedback_id",
  "state": "like",
  "comment": "Helpful answer",
  "created_at": "2026-08-20T10:05:00Z"
}

Note: in the response schema, state here can only be like or dislike (a removed rating simply leaves no feedback object).

Errors: 401, 403, 404 (message not found), 429

`GET /api/public/cards` – List knowledge-base cards

A card is a saved question/answer pair in the knowledge base, generated from customer conversations.

Query parameters: per (default 10, max 500), page.

curl https://prod-api.binomai.com/api/public/cards -u YOUR_API_KEY:

Card object fields:

Field	Description
`id`	Card ID
`organization_id`	Organization ID
`assistant_message_id`	ID of the message this card was generated from
`assistant_thread_id`	ID of the chat this card was generated from
`category`	Category
`question` / `answer`	The Q&A pair
`quality`	Quality score (integer)
`state`	See table below
`files`	Attached files – same field structure as above
`created_at` / `updated_at`	Timestamps

Card lifecycle (state):

Status	Meaning
`waiting`	Created, no answer yet
`in_progress`	Being processed
`answered`	An answer has been given
`submitted`	Accepted for processing
`consumed`	Ready for use in the knowledge base
`failed`	Processing failed

Errors: 401

`GET /api/public/price_lists` – List price lists

Query parameters: per (default 10, max 500), page.

curl https://prod-api.binomai.com/api/public/price_lists -u YOUR_API_KEY:

Response:

{
  "data": [ /* array of price list objects, see below */ ],
  "meta": { "total": 5, "page": 1, "per": 10, "pages": 1, "parse_in_progress": false }
}

meta.parse_in_progress (boolean) reflects whether price list parsing is currently in progress across the listed items.

Errors: 401

`GET /api/public/price_lists/{id}` – Get a single price list

Path parameter only – this endpoint does not accept per/page (unlike the list endpoint above).

curl https://prod-api.binomai.com/api/public/price_lists/{id} -u YOUR_API_KEY:

Response – includes the parsed items directly:

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "organization_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "state": "waiting",
  "form": "csv",
  "url": "https://example.com/feed.csv",
  "price_items_count": 128,
  "price_items": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "organization_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "ext_id": "SKU-001",
      "title": "Example Product",
      "brand": "ExampleBrand",
      "category": "Electronics",
      "description": "Product description",
      "price": "199.99",
      "url": "https://example.com/products/sku-001",
      "image_url": "https://example.com/images/sku-001.jpg",
      "key_params": {},
      "data": {},
      "qr_code_url": "https://example.com/qr/sku-001.png",
      "qr_link": "https://example.com/products/sku-001",
      "created_at": "2026-08-21T11:12:03.287Z",
      "updated_at": "2026-08-21T11:12:03.287Z"
    }
  ],
  "file_name": "products.csv",
  "file_url": "https://example.com/uploads/products.csv",
  "processed_at": "2026-08-21T11:12:03.287Z",
  "created_at": "2026-08-21T11:12:03.287Z",
  "updated_at": "2026-08-21T11:12:03.287Z"
}

Price list fields:

Field	Description
`id` / `organization_id`	Price list ID / organization ID
`state`	`waiting`, `in_progress`, `processed`, `failed`
`form`	Source type: `csv`, `rss`, `horoshop`
`url`	Address of the source feed, for `rss`/`horoshop`-type sources. Not used for `csv` uploads – see `file_url` instead.
`price_items_count`	Number of items (count only)
`price_items`	Array of `PriceItem` objects – the actual items (see below)
`file_name` / `file_url`	For file-based (`csv`) uploads
`processed_at` / `created_at` / `updated_at`	Timestamps

PriceItem fields:

Field	Description
`id` / `organization_id`	Item ID / organization ID
`ext_id`	External item ID from the client's source file
`title`, `brand`, `category`, `description`	Standard product fields
`price`	Price (string)
`url`	Link to the product
`image_url`	Link to the product image
`key_params`	Key parameters/keywords automatically extracted from the item during processing, used for more precise search and replies about this item
`data`	Additional data
`qr_code_url` / `qr_link`	QR code image and the URL it resolves to
`created_at` / `updated_at`	Timestamps

Errors: 401, 404

API Rate Limits (BINOMAI.com)

Scope	Limit
Messages per chat	10 per minute, then the chat is blocked for 10 minutes
Whole public API	100 requests per minute

Exceeding either limit returns 429.

API Error Codes (BINOMAI.com)

Code	Meaning
`401`	Invalid or missing API key
`402`	AI request balance is not positive (plan's available requests exhausted)
`403`	Subscription is not active
`404`	Resource not found (chat, message, or price list)
`429`	Rate limit exceeded – thresholds are listed earlier in this page

Error body shapes:

{ "status": "error", "message": "Authentication failed" }

{ "error": "error text" }

{ "error": ["error one", "error two"] }

The status/message shape is used specifically for the 401-on-invalid-key case; every other error uses the error shape.

Chat Lifecycle

A chat that never received a single message from the user is automatically deleted after 3 hours.
A chat that already has message history is never deleted automatically – it persists indefinitely.
For long-idle-but-already-started conversations, creating a fresh chat on your side is a recommendation, not a system requirement – it keeps old context from bleeding into a new conversation, but nothing forces you to do it.

Webhooks

The public API does not use webhooks. The synthetic employee's reply is returned synchronously, in the same response as the message-send request – there's no asynchronous notification step to configure.

(Incoming webhooks for other channels – Telegram, Instagram, etc. – exist as part of configuring those channels directly in the dashboard, but are unrelated to this public REST API.)

Glossary

Chat – a conversation between a customer and the synthetic employee. Identified in API paths by your own chat_id.
Synthetic employee – the AI assistant that generates replies within a chat.
Message – a single message within a chat, from a user, assistant, system, or operator.
Card – a saved question/answer pair added to the knowledge base from a conversation.
Price list / Price item – an uploaded or fed-in product catalog, and an individual product entry within it.

All paths, field names, enum values, and error codes on this page reflect the current BINOMAI.com API specification.specification.

Ready to help: support@binomai.com

Binom AI Public API Documentation | Developer Guide

Overview

Quick start

Authentication with BINOM AI public API

Authentication errors

Endpoint Reference

`POST /api/public/chats` – Create a chat

`GET /api/public/chats` – List chats

`POST /api/public/chats/{chat_id}/messages` – Send a message

Attached File Fields

`GET /api/public/chats/{chat_id}/messages` – Retrieve conversation history

`POST /api/public/chats/{chat_id}/messages/{id}/feedback` – Rate a reply

`GET /api/public/cards` – List knowledge-base cards

`GET /api/public/price_lists` – List price lists

`GET /api/public/price_lists/{id}` – Get a single price list

API Rate Limits (BINOMAI.com)

API Error Codes (BINOMAI.com)

Chat Lifecycle

Webhooks

Glossary

GDPR agreement

Privacy policy

Synthetic seller for online stores

Hire high-level AI employees.
Trained like top professionals.

We are on social media

© Copyright 2026 binomai.com - ALL RIGHTS RESERVED

Binom AI Public API Documentation | Developer Guide

Overview

Quick start

Authentication with BINOM AI public API

Authentication errors

Endpoint Reference

POST /api/public/chats – Create a chat

GET /api/public/chats – List chats

POST /api/public/chats/{chat_id}/messages – Send a message

Attached File Fields

GET /api/public/chats/{chat_id}/messages – Retrieve conversation history

POST /api/public/chats/{chat_id}/messages/{id}/feedback – Rate a reply

GET /api/public/cards – List knowledge-base cards

GET /api/public/price_lists – List price lists

GET /api/public/price_lists/{id} – Get a single price list

API Rate Limits (BINOMAI.com)

API Error Codes (BINOMAI.com)

Chat Lifecycle

Webhooks

Glossary

GDPR agreement

Privacy policy

Synthetic seller for online stores

Hire high-level AI employees.Trained like top professionals.

We are on social media

© Copyright 2026 binomai.com - ALL RIGHTS RESERVED

`POST /api/public/chats` – Create a chat

`GET /api/public/chats` – List chats

`POST /api/public/chats/{chat_id}/messages` – Send a message

`GET /api/public/chats/{chat_id}/messages` – Retrieve conversation history

`POST /api/public/chats/{chat_id}/messages/{id}/feedback` – Rate a reply

`GET /api/public/cards` – List knowledge-base cards

`GET /api/public/price_lists` – List price lists

`GET /api/public/price_lists/{id}` – Get a single price list

Hire high-level AI employees.
Trained like top professionals.