---
id: "faq-10112"
type: "faq"
lang: "en"
title: "Binom AI Public API Documentation | Developer Guide"
url: "https://binomai.com/faq/binom-ai-public-api/"
translation_group: "faq-10112"
translations: []
published: "2026-08-21T15:06:18Z"
updated: "2026-10-19T09:49:50Z"
---

# Binom AI Public API Documentation | Developer Guide

*Updated: 19.10.2026, 09:49 UTC*


---

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