Skip to content

For developers

HTTP API

Manage your assistant from code: knowledge base, conversations, bookings, assistants, usage, product catalog, payments.

Quick start

ParameterValue
Base URLhttps://www.botai.ge/api/v1
AuthenticationAuthorization: Bearer <key>. Keys are created in the dashboard: Authentication
FormatJSON, UTF-8; Content-Type: application/json on requests with a body
EnvironmentJavaScript — Node 18+ (fetch); Python — pip install requests
The base URL works only with www. botai.ge (without www) returns a redirect (308), and most HTTP clients do not carry Authorization across a redirect.

1. Keys in environment variables

shell
export CORPORATE_API_KEY="cxk_Jt7q2sN9xVb0Lp4rWc8yZa3mEh6kFd1gTu5nQi2oXvA"
export PRODUCTS_API_KEY="cxk_Hn3v8mRb1zXd6Kt0Pw5jLy9cSe4uGa7fQo2iYr8sZbN"

The keys shown are made up; use your own. Every example reads two variables: CORPORATE_API_KEY for the corporate API, PRODUCTS_API_KEY for products and payments.

2. First request: what your assistant knows

Request
curl
curl https://www.botai.ge/api/v1/knowledge \
  -H "Authorization: Bearer $CORPORATE_API_KEY"
JavaScript
const res = await fetch("https://www.botai.ge/api/v1/knowledge", {
  headers: { Authorization: `Bearer ${process.env.CORPORATE_API_KEY}` },
});
console.log(await res.json());
Python
import os
import requests

res = requests.get(
    "https://www.botai.ge/api/v1/knowledge",
    headers={"Authorization": f"Bearer {os.environ['CORPORATE_API_KEY']}"},
    timeout=30,
)
print(res.json())
Response
{
  "clientId": "salon-vake",
  "description": "Beauty salon in Vake, since 2011.",
  "services": [
    { "name": "Haircut", "price": "40 ₾", "durationMinutes": 45 }
  ],
  "faq": [
    { "question": "Do you have parking?", "answer": "Yes, in the courtyard." }
  ],
  "rules": ["Never make up a price — only from the list"],
  "documents": []
}
  • 401 unauthorized: the key is missing or unknown; most often the variable is empty.
  • 403 plan_required: the key is valid, but the account is not on the Corporate package: Two APIs.
  • Other refusals: Errors and limits.

Endpoints

All endpoints live on https://www.botai.ge. Each link takes you to the endpoint's description.

MethodEndpointScopeAPIWhat it doesSection
Corporate API
GET /api/v1/knowledge knowledge:read Corporate Read the knowledge base 1
POST /api/v1/knowledge knowledge:write Corporate Replace the named sections 1
PATCH /api/v1/knowledge knowledge:write Corporate Merge the named sections; nothing is deleted 1
GET /api/v1/conversations conversations:read Corporate List conversations 2
GET /api/v1/conversations/{channel}/{userId} conversations:read Corporate Transcript of one conversation 2
GET /api/v1/contacts conversations:read Corporate Contact base 2
GET /api/v1/handoffs conversations:read Corporate Operator requests 2
GET /api/v1/bookings bookings:read Corporate List bookings 3
GET /api/v1/bookings/busy bookings:read Corporate Busy times and working hours, without customer details 3
POST /api/v1/bookings bookings:write Corporate New booking 3
POST /api/v1/bookings/{bookingId}/cancel bookings:write Corporate Cancel a booking; safe to repeat 3
GET /api/v1/assistants assistants:read Corporate List the account's assistants 4
POST /api/v1/assistants assistants:write Corporate Create an assistant; it is created switched off 4
PATCH /api/v1/assistants/{clientId} assistants:write Corporate Change an assistant's settings 4
GET /api/v1/usage usage:read Corporate Messages and tokens per assistant 5
Products API
POST /api/v1/products products:write Products Replace the whole catalog; anything you did not send is archived 6
PATCH /api/v1/products products:write Products Partial catalog update; nothing is archived 6
POST /api/v1/payments payments:write Products Order and payment link or QR code 7
POST /api/v1/payments/quickpay/webhook/{clientId} No key Products Called by the bank; you do not call it 7
From us to you; not an API
POST Your URL No key Webhook Booking events; Business package and above Webhook

Contents

Two APIs

Corporate APIProducts API
What it opens Knowledge base, conversations, bookings, assistants, usage Catalog (/products) and payments (/payments)
Package Corporate; Start and Business are refused Any paid package, with the add-on
Add-on Not needed Product sync on the assistant you write to; included in Corporate, sold separately on Start and Business
Key cxk_…, with a list of scopes cxk_…
Where it is created Assistant → Assistant settings → Other → API access Assistant → Products → API key
Base URL https://www.botai.ge/api/v1 for both
Refusal when the condition is not met 403 plan_required 403 addon_required
  • A key issued on the Products screen does not open the corporate endpoints; what a key opens is described in Scopes.
  • The booking webhook is not an API: we send to you, no key is needed, and the package is Business or above. Webhook.

Authentication

Header on every request
Authorization: Bearer cxk_Jt7q2sN9xVb0Lp4rWc8yZa3mEh6kFd1gTu5nQi2oXvA
KeyRule
Formatcxk_…
ShownOnce, when it is created. We store only its SHA-256 hash, so nobody can show it to you again.
AssistantOne key, one assistant. Three branches, three keys.
ScopesFixed when the key is issued: Scopes.
Lost or leakedCreate a new key and revoke the old one. Revocation takes effect from the very next request.
CORSNone, on purpose: the key can write, so it is used only from a server, never from a browser.
Refusal401 unauthorized: the key is missing, unknown, malformed or revoked.
Which keyWhere it is created
Corporate API Assistant → Assistant settings → Other → API access
Products API Assistant → Products → API key

Scopes

Rule. A scope is written on the key by name; there is no hierarchy and no wildcard. A key without scopes (issued on the Products screen) is open on /products and /payments and closed on the corporate endpoints.
ScopeLevelWhat it opens (after /api/v1)Key without a list
knowledge:readAssistant levelGET /knowledgeClosed
knowledge:writeAssistant levelPOST / PATCH /knowledgeClosed
conversations:readAssistant levelGET /conversations, /conversations/{channel}/{userId}, /contacts, /handoffsClosed
bookings:readAssistant levelGET /bookings, GET /bookings/busyClosed
bookings:writeAssistant levelPOST /bookings, POST /bookings/{bookingId}/cancelClosed
products:writeAssistant levelPOST / PATCH /products: Products APIOpen
payments:writeAssistant levelPOST /payments: PaymentsOpen
assistants:readAccount levelGET /assistantsClosed
assistants:writeAccount levelPOST /assistants, PATCH /assistants/{clientId}Closed
usage:readAccount levelGET /usageClosed
  • Scopes are fixed when the key is issued. If you need more, create a new key with the new scopes and revoke the old one.
  • The dashboard grants an account-level scope only to the account that owns this assistant.

Two levels

LevelThe key reachesAssistant in the requestAnother assistant
Assistant level Only the key's own assistant Not specified; a clientId you send is ignored You cannot name another assistant
Account level Every assistant on the account clientId in the path, the body or ?clientId= 404 assistant_not_found, the same response as for one that does not exist
  • An account-level scope is never given to an assistant key: creating a second assistant and reading a neighbor's usage are possible only with this scope.
  • If the assistant has no owning account, the account-level endpoints answer 403 no_account.

Pagination

Every list response has the same three fields:

FieldWhat it says
returnedHow many rows are in this response.
truncatedfalse = that is everything. true = more exists than you received.
limitThe page size actually used, after clamping.

To request the rest, where that is possible, the response has one more field:

FieldWhereWhat to do
nextOffset/conversations, /contactsRepeat with ?offset= set to this number.
nextFrom/bookings, /bookings/busyRepeat with ?from= set to this date. Rows for that date will come again; filter duplicates by id.
nextBefore/handoffsRepeat with ?before= set to this time. That second will come again too; filter duplicates by id.
maxLimit/conversations/{channel}/{userId}The largest ?limit= this endpoint accepts.
LimitValue
?limit=Maximum 500, default 100
Transcript of one conversationUp to 900
totalOnly where it is a fact: /conversations, /assistants. Not elsewhere.
Rely only on truncated: false. Do not infer completeness from returned < limit.

1. Knowledge base

Reading and writing the knowledge base · scopes knowledge:read, knowledge:write · assistant level · package: Corporate.

Every endpoint can also return: 401, 403, 429, 500; see Errors and limits.

Sections

SectionTypeEntry fields and limitsPOSTPATCH
descriptionstring—ReplacedReplaced
servicesarrayAt most 200. name is required; description, price, priceUnit, durationMinutes are not. price is free text (“40 ₾”, “from 50 ₾”); durationMinutes is a positive integer.Replaced in fullMatched by name, ignoring case and leading or trailing whitespace: a match is updated, the rest is added
faqarrayAt most 300. question and answer are both required.Replaced in fullMatched by question, by the same rule
rulesarray of stringAt most 100. An empty string is not allowed.Replaced in fullAdded if not already present; nothing is deleted
documentsarrayAt most 10 per request; an assistant has 10 sources in total, and files uploaded in the dashboard count too. id is required, A-Za-z0-9_.:-, 1–64 characters; label defaults to id; text is a string of at most 8 000 characters.Replaced; a document written via the API but not named is deletedUpdated by id; the rest is left untouched
  • services[].description and services[].price are strings only; a value of any other type is silently skipped and no error is returned.
  • services[].price is never treated as a number: the assistant quotes it verbatim. A product price, in whole tetri, belongs in the Products API.
  • services[].priceUnit is the price unit, from a closed list: visit, procedure, night, month, person, item, hour, from (starting price). We cannot read any other value and return it with invalid_service; we do not choose a unit ourselves, because that would be a statement about your price. If the price is simply the price of that one thing, do not send it; the assistant will then say only the figure.
GET /api/v1/knowledge knowledge:read

The whole knowledge base.

Request
curl
curl https://www.botai.ge/api/v1/knowledge \
  -H "Authorization: Bearer $CORPORATE_API_KEY"
JavaScript
const res = await fetch("https://www.botai.ge/api/v1/knowledge", {
  headers: { Authorization: `Bearer ${process.env.CORPORATE_API_KEY}` },
});
console.log(await res.json());
Python
import os
import requests

res = requests.get(
    "https://www.botai.ge/api/v1/knowledge",
    headers={"Authorization": f"Bearer {os.environ['CORPORATE_API_KEY']}"},
    timeout=30,
)
print(res.json())
Response
{
  "clientId": "demo-salon",
  "description": "Beauty salon in Vake, since 2011.",
  "services": [{"name": "Haircut", "price": "40 ₾", "durationMinutes": 45}],
  "faq": [{"question": "Do you have parking?", "answer": "Yes, in the courtyard."}],
  "rules": ["Never make up a price — only from the list"],
  "documents": [
    {
      "id": "returns-policy",
      "label": "Return policy",
      "text": "Returns are accepted within 14 days of purchase, with a receipt.",
      "charCount": 61,
      "updatedAt": "2026-08-20T11:02:00.000Z"
    }
  ]
}

Response fields

FieldTypeNote
clientIdstringThe key's assistant.
descriptionstringAn empty string if nothing has been written.
servicesarrayname, description, price, priceUnit, durationMinutes: whatever has been written.
faqarrayquestion, answer.
rulesarray of string
documentsarrayOnly those written via the API: id, label, text, charCount, updatedAt (ISO 8601). Files uploaded in the dashboard are not returned.

Errors

StatuserrorWhen
404assistant_not_foundThe key's assistant no longer exists.
POST /api/v1/knowledge knowledge:write

A named section is replaced in full; an unnamed one stays as it was.

Request
curl
curl -X POST https://www.botai.ge/api/v1/knowledge \
  -H "Authorization: Bearer $CORPORATE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
      "description": "Beauty salon in Vake, since 2011.",
      "services": [
        {"name": "Haircut", "price": "40 ₾", "durationMinutes": 45},
        {"name": "Manicure", "price": "30 ₾", "durationMinutes": 60}
      ],
      "documents": [
        {
          "id": "returns-policy",
          "label": "Return policy",
          "text": "Returns are accepted within 14 days of purchase, with a receipt."
        }
      ]
    }'
JavaScript
const res = await fetch("https://www.botai.ge/api/v1/knowledge", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.CORPORATE_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    description: "Beauty salon in Vake, since 2011.",
    services: [
      { name: "Haircut", price: "40 ₾", durationMinutes: 45 },
      { name: "Manicure", price: "30 ₾", durationMinutes: 60 },
    ],
    documents: [
      {
        id: "returns-policy",
        label: "Return policy",
        text: "Returns are accepted within 14 days of purchase, with a receipt.",
      },
    ],
  }),
});
console.log(res.status, await res.json());
Python
import os
import requests

res = requests.post(
    "https://www.botai.ge/api/v1/knowledge",
    headers={"Authorization": f"Bearer {os.environ['CORPORATE_API_KEY']}"},
    json={
        "description": "Beauty salon in Vake, since 2011.",
        "services": [
            {"name": "Haircut", "price": "40 ₾", "durationMinutes": 45},
            {"name": "Manicure", "price": "30 ₾", "durationMinutes": 60},
        ],
        "documents": [
            {
                "id": "returns-policy",
                "label": "Return policy",
                "text": "Returns are accepted within 14 days of purchase, with a receipt.",
            },
        ],
    },
    timeout=30,
)
print(res.status_code, res.json())
Response
{
  "ok": true,
  "mode": "replace",
  "applied": ["description", "services", "documents"],
  "documents": {"written": 1, "removed": 2}
}

Response fields

FieldTypeNote
okbooleantrue: everything was written. On 502: false, or the field is absent.
modestringreplace.
appliedarray of stringWhich sections were written.
documents.writtenintegerThe documents written. The field is present only when the body contained documents.
documents.removedintegerAPI documents deleted: those you did not name in the body. Files uploaded in the dashboard are never touched.

Errors

StatuserrorWhen
400invalid_bodyThe body is not an object, or a section has the wrong type (field).
400nothing_to_writeThe body did not name any section.
400invalid_service, invalid_extra_price, invalid_faq, invalid_rule, invalid_documentOne entry is malformed; index and field say which.
400duplicate_document_idThe same id twice in one request.
404assistant_not_foundThe key's assistant no longer exists.
409write_conflictThe assistant's configuration changed between the read and the write. Nothing was written; try again.
413too_many_services, too_many_extra_prices, too_many_faq, too_many_rules, too_many_documentsAbove a section's limit (200 / 20 / 300 / 100 / 10), or the assistant's knowledge sources would exceed 10 in total.
413document_too_longA document's text is longer than 8 000 characters.
502write_failedPart of the write succeeded and part did not. The response contains applied and failed.
  • Validation runs before the write: after 400 and 413 nothing has changed.
  • An empty body ({}) does not clear the knowledge base: 400 nothing_to_write. An empty array ("rules": []), however, is executed and clears that section.
  • A document longer than 8 000 characters is refused here and is not truncated; split it into parts. The dashboard works differently: a file uploaded there is accepted, its first 8 000 characters are stored, and the source card says how much we read and how much is passed to the assistant. We refuse here because this endpoint is called by a program, which can do the splitting.
  • From all of one assistant's sources together, those written via the API and those uploaded in the dashboard, the assistant receives 14 000 characters in total, newest first. A document beyond this limit is kept but does not take part in answers.
  • 502 write_failed: the configuration is written in one write, documents one by one. Nothing was deleted; the same request can be safely repeated.
  • POST and PATCH share one endpoint: clearing the knowledge base happens only through your choice of method; there is no flag in the body.
PATCH /api/v1/knowledge knowledge:write

A named section is merged into the existing one; nothing is deleted. Body and errors are the same as for POST.

Request
curl
curl -X PATCH https://www.botai.ge/api/v1/knowledge \
  -H "Authorization: Bearer $CORPORATE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
      "faq": [
        {
          "question": "Can I pay by card?",
          "answer": "Yes, by card and in cash."
        }
      ],
      "rules": ["Always address the guest by name"]
    }'
JavaScript
const res = await fetch("https://www.botai.ge/api/v1/knowledge", {
  method: "PATCH",
  headers: {
    Authorization: `Bearer ${process.env.CORPORATE_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    faq: [
      {
        question: "Can I pay by card?",
        answer: "Yes, by card and in cash.",
      },
    ],
    rules: ["Always address the guest by name"],
  }),
});
console.log(res.status, await res.json());
Python
import os
import requests

res = requests.patch(
    "https://www.botai.ge/api/v1/knowledge",
    headers={"Authorization": f"Bearer {os.environ['CORPORATE_API_KEY']}"},
    json={
        "faq": [
            {
                "question": "Can I pay by card?",
                "answer": "Yes, by card and in cash.",
            },
        ],
        "rules": ["Always address the guest by name"],
    },
    timeout=30,
)
print(res.status_code, res.json())
Response
{"ok": true, "mode": "merge", "applied": ["faq", "rules"]}

Response fields

FieldTypeNote
ok, appliedboolean, array of stringSame as for POST.
modestringmerge.
documents.writtenintegerOnly if the body contained documents. removed is not in the PATCH response: PATCH deletes nothing.
  • The rule for merging sections is in the table above.
  • An empty array changes nothing on PATCH. description is replaced in full on PATCH too; "" clears it.

2. Conversations and leads

Conversations, contacts and operator requests · scope conversations:read (on all four endpoints) · assistant level · package: Corporate.

Every endpoint can also return: 401, 403, 429, 500; see Errors and limits.

GET /api/v1/conversations conversations:read

List of conversations: one row per pair (channel, userId), most recent activity first.

Parameters

ParameterTypeRequiredDefault · limitNote
limitintegerNo100 · max 500A malformed value falls back to the default; not an error.
offsetintegerNo0A malformed value returns 0.
Request
curl
curl "https://www.botai.ge/api/v1/conversations?limit=50&offset=0" \
  -H "Authorization: Bearer $CORPORATE_API_KEY"
JavaScript
const params = new URLSearchParams({ limit: 50, offset: 0 });
const res = await fetch(`https://www.botai.ge/api/v1/conversations?${params}`, {
  headers: { Authorization: `Bearer ${process.env.CORPORATE_API_KEY}` },
});
console.log(await res.json());
Python
import os
import requests

res = requests.get(
    "https://www.botai.ge/api/v1/conversations",
    headers={"Authorization": f"Bearer {os.environ['CORPORATE_API_KEY']}"},
    params={"limit": 50, "offset": 0},
    timeout=30,
)
print(res.json())
Response
{
  "conversations": [
    {
      "channel": "website",
      "userId": "w_8fa2c41e",
      "lastMessage": "Thank you!",
      "lastRole": "user",
      "lastTimestamp": "2026-08-22T09:14:02.000Z",
      "messageCount": 11
    }
  ],
  "returned": 1,
  "total": 1,
  "limit": 50,
  "offset": 0,
  "truncated": false,
  "countsComplete": true
}

Response fields

FieldTypeNote
conversations[]arraychannel, userId, lastMessage, lastRole (user or assistant), lastTimestamp (ISO 8601), messageCount.
returned, limit, offsetintegerHow many came back; the page size used; where it started.
totalintegerLength of the list. With countsComplete: false, a lower bound.
truncatedbooleantrue: more exists, or countsComplete: false.
nextOffsetintegerOnly if a next page exists: repeat with ?offset= set to this number.
countsCompletebooleanfalse: the scan stopped at its limit (see below).
  • countsComplete: false is the only limit that offset cannot get past. The list is built by scanning the assistant's stored messages, and the scan stops at 20 000 rows. Beyond that, total and every messageCount are lower bounds, and the oldest conversations are not in the list.
  • If you need the full history, write to us.
GET /api/v1/conversations/{channel}/{userId} conversations:read

Transcript of one conversation, oldest to newest.

Parameters

ParameterTypeRequiredDefault · limitNote
channelstringYes (in the path)—The value of conversations[].channel.
userIdstringYes (in the path)—The value of conversations[].userId; URL-encoded.
limitintegerNo100 · max 900That many of the latest messages are returned.
Request
curl
curl "https://www.botai.ge/api/v1/conversations/website/w_8fa2c41e?limit=100" \
  -H "Authorization: Bearer $CORPORATE_API_KEY"
JavaScript
const params = new URLSearchParams({ limit: 100 });
const res = await fetch(`https://www.botai.ge/api/v1/conversations/website/w_8fa2c41e?${params}`, {
  headers: { Authorization: `Bearer ${process.env.CORPORATE_API_KEY}` },
});
console.log(await res.json());
Python
import os
import requests

res = requests.get(
    "https://www.botai.ge/api/v1/conversations/website/w_8fa2c41e",
    headers={"Authorization": f"Bearer {os.environ['CORPORATE_API_KEY']}"},
    params={"limit": 100},
    timeout=30,
)
print(res.json())
Response
{
  "channel": "website",
  "userId": "w_8fa2c41e",
  "messages": [
    {"role": "user", "text": "When are you open?", "timestamp": "2026-08-22T09:12:41.000Z"},
    {
      "role": "assistant",
      "text": "Every day 10:00-20:00.",
      "timestamp": "2026-08-22T09:12:43.000Z"
    }
  ],
  "returned": 2,
  "limit": 100,
  "truncated": false
}

Response fields

FieldTypeNote
channel, userIdstringAs sent in the path.
messages[]arrayrole (user or assistant), text, timestamp (ISO 8601). Oldest to newest.
returned, limitinteger
truncatedbooleantrue: the conversation is missing its beginning; the last limit messages are returned.
maxLimitintegerOnly with truncated: true: 900.
  • 900 is not a random number: exactly that many messages are stored per conversation, so ?limit=900 always returns the whole conversation.
  • There is no total; truncated: false means returned is the whole conversation.
  • A pair that does not exist: 200 with empty messages, not 404.
GET /api/v1/contacts conversations:read

Contact base: one row per person, with what we know about them from conversations, bookings, operator requests and reviews.

Parameters

ParameterTypeRequiredDefault · limitNote
limitintegerNo100 · max 500A malformed value falls back to the default; not an error.
offsetintegerNo0A malformed value returns 0.
Request
curl
curl "https://www.botai.ge/api/v1/contacts?limit=50&offset=0" \
  -H "Authorization: Bearer $CORPORATE_API_KEY"
JavaScript
const params = new URLSearchParams({ limit: 50, offset: 0 });
const res = await fetch(`https://www.botai.ge/api/v1/contacts?${params}`, {
  headers: { Authorization: `Bearer ${process.env.CORPORATE_API_KEY}` },
});
console.log(await res.json());
Python
import os
import requests

res = requests.get(
    "https://www.botai.ge/api/v1/contacts",
    headers={"Authorization": f"Bearer {os.environ['CORPORATE_API_KEY']}"},
    params={"limit": 50, "offset": 0},
    timeout=30,
)
print(res.json())
Response
{
  "contacts": [
    {
      "channel": "website",
      "userId": "w_8fa2c41e",
      "name": "Nino",
      "phone": "+995000123456",
      "email": null,
      "firstSeen": "2026-08-20T10:02:11.000Z",
      "lastSeen": "2026-08-22T09:14:02.000Z",
      "messageCount": 11,
      "inboundMessageCount": 6,
      "lastMessageAt": "2026-08-22T09:14:02.000Z",
      "bookingCount": 1,
      "cancelledCount": 0,
      "rejectedCount": 0,
      "pendingCount": 1,
      "attendedCount": 0,
      "noShowCount": 0,
      "unknownOutcomeCount": 0,
      "needsAttendanceCount": 0,
      "lastBookingAt": null,
      "nextBookingAt": "2026-09-01T08:00:00.000Z",
      "lastBookingMadeAt": "2026-08-22T09:00:00.000Z",
      "oldestPendingAt": "2026-08-22T09:00:00.000Z",
      "lastAttendedAt": null,
      "handoffCount": 0,
      "lastHandoffAt": null,
      "reviewCount": 0,
      "reviewRating": null,
      "reviewComment": null,
      "lastReviewAt": null,
      "manualStage": null,
      "manualStageSource": null,
      "manualNote": null,
      "manualUpdatedAt": null
    }
  ],
  "returned": 1,
  "offset": 0,
  "limit": 50,
  "truncated": false
}

Response fields

FieldTypeNote
contacts[]arrayOne person; fields below.
returned, offset, limitinteger
truncatedbooleantrue: more exists.
nextOffsetintegerOnly with truncated: true: repeat with ?offset= set to this number.

contacts[] fields

FieldTypeNote
channel, userIdstringThe person's key. The same pair as in /conversations.
name, phone, emailstring | nullThe latest non-empty value from bookings; there is no other source.
firstSeen, lastSeenISO 8601 | nullFirst and last contact: a message, booking, operator request or review.
messageCount, inboundMessageCountintegerAll messages; only those the person wrote.
lastMessageAtISO 8601 | null
bookingCountintegerActive bookings: not cancelled and not declined.
pendingCountintegerThe part of bookingCount awaiting confirmation.
cancelledCount, rejectedCountinteger
attendedCount, noShowCountintegerA person marked “attended” / “did not attend”.
unknownOutcomeCountintegerPast active bookings for which nobody recorded anything. This is not “did not attend”.
needsAttendanceCountintegerThe part of the previous field for which the dashboard is still asking for an answer.
lastBookingAt, nextBookingAtISO 8601 | nullThe most recent past visit and the nearest upcoming one.
lastBookingMadeAt, oldestPendingAt, lastAttendedAtISO 8601 | nullWhen they last requested a booking; the oldest unanswered request; the last attendance.
handoffCount, lastHandoffAtinteger, ISO 8601 | nullOperator requests.
reviewCount, reviewRating, reviewComment, lastReviewAtinteger, number | null, string | null, ISO 8601 | nullReviews; the rating and comment are from the latest review, not the best one.
manualStagestring | nullnew, qualified, booked, won, lost: the CRM stage set by a person or by the system.
manualStageSourcestring | nullmanual: set by a person; system: set automatically because of a booking.
manualNote, manualUpdatedAtstring | null, ISO 8601 | nullThe note and when it was written.

Errors

StatuserrorWhen
500contacts_unreadableWe could not read the contact base. This is deliberately not an empty list: “there are no contacts” and “we could not read them” are different facts. If it persists, write to us.
GET /api/v1/handoffs conversations:read

Where a customer asked for a person. Newest to oldest.

Parameters

ParameterTypeRequiredDefault · limitNote
limitintegerNo100 · max 500A malformed value falls back to the default; not an error.
openstringNo—true: only unanswered ones (acknowledgedAt: null). Any other value: all.
sincestringNo—ISO 8601; inclusive.
beforestringNo—ISO 8601; inclusive. Malformed: 400.
Request
curl
curl "https://www.botai.ge/api/v1/handoffs?limit=100&open=true" \
  -H "Authorization: Bearer $CORPORATE_API_KEY"
JavaScript
const params = new URLSearchParams({ limit: 100, open: "true" });
const res = await fetch(`https://www.botai.ge/api/v1/handoffs?${params}`, {
  headers: { Authorization: `Bearer ${process.env.CORPORATE_API_KEY}` },
});
console.log(await res.json());
Python
import os
import requests

res = requests.get(
    "https://www.botai.ge/api/v1/handoffs",
    headers={"Authorization": f"Bearer {os.environ['CORPORATE_API_KEY']}"},
    params={"limit": 100, "open": "true"},
    timeout=30,
)
print(res.json())
Response
{
  "handoffs": [
    {
      "id": 4471,
      "channel": "whatsapp",
      "userId": "995000123456",
      "reason": "operator",
      "createdAt": "2026-08-22T08:40:00.000Z",
      "acknowledgedAt": null,
      "acknowledgedBy": null
    }
  ],
  "returned": 1,
  "limit": 100,
  "truncated": false
}

Response fields

FieldTypeNote
handoffs[]arrayid, channel, userId, reason, createdAt, acknowledgedAt, acknowledgedBy.
acknowledgedAt, acknowledgedByISO 8601 | null, string | nullnull: the customer is still waiting. “A notification was sent” and “someone took it” are two different facts.
returned, limitinteger
truncatedbooleantrue: the oldest ones did not fit.
nextBeforestringOnly with truncated: true: repeat with ?before= set to this time.

Errors

StatuserrorWhen
400invalid_requestbefore is not ISO 8601.
  • before is inclusive, so the boundary row will come again: filter duplicates by id. Two requests can have the same createdAt down to the millisecond, which is why the bound is inclusive.
  • truncated: true with no nextBefore: the page was filled by a single timestamp, and the cursor cannot move.

3. Bookings

Reading bookings, busy times, new booking and cancellation · scopes bookings:read, bookings:write · assistant level · package: Corporate.

Every endpoint can also return: 401, 403, 429, 500; see Errors and limits.

Dates and times are read in Tbilisi time (Asia/Tbilisi).

GET /api/v1/bookings bookings:read

List of bookings by date and time, in the order of the day.

Parameters

ParameterTypeRequiredDefault · limitNote
fromstringNo—YYYY-MM-DD, inclusive.
tostringNo—YYYY-MM-DD, inclusive.
limitintegerNo100 · max 500A malformed value falls back to the default; not an error.
Request
curl
curl "https://www.botai.ge/api/v1/bookings?from=2026-09-01&to=2026-09-07" \
  -H "Authorization: Bearer $CORPORATE_API_KEY"
JavaScript
const params = new URLSearchParams({ from: "2026-09-01", to: "2026-09-07" });
const res = await fetch(`https://www.botai.ge/api/v1/bookings?${params}`, {
  headers: { Authorization: `Bearer ${process.env.CORPORATE_API_KEY}` },
});
console.log(await res.json());
Python
import os
import requests

res = requests.get(
    "https://www.botai.ge/api/v1/bookings",
    headers={"Authorization": f"Bearer {os.environ['CORPORATE_API_KEY']}"},
    params={"from": "2026-09-01", "to": "2026-09-07"},
    timeout=30,
)
print(res.json())
Response
{
  "bookings": [
    {
      "id": 91,
      "channel": "api",
      "userId": "crm-4471",
      "service": "Haircut",
      "date": "2026-09-01",
      "time": "12:00",
      "customerName": "Nino",
      "customerPhone": "5xx xx xx xx",
      "customerEmail": null,
      "staffName": null,
      "cancelled": false,
      "pendingApproval": true,
      "rejectedReason": null,
      "attended": null,
      "createdAt": "2026-08-22T09:00:00.000Z"
    }
  ],
  "returned": 1,
  "limit": 100,
  "truncated": false
}

Response fields

FieldTypeNote
bookings[]arrayFields below.
returned, limitinteger
truncatedbooleantrue: more exists.
nextFromstringOnly with truncated: true: repeat with ?from= set to this date.

bookings[] fields

FieldTypeNote
idintegerThe only exact handle for a booking; for cancellation it goes in the path.
channelstringapi: your entry; anything else: the customer's channel.
userIdstring
service, date, timestringdate — YYYY-MM-DD, time — HH:MM.
customerName, customerPhone, customerEmail, staffNamestring | null
cancelledbooleantrue: cancelled; it still stays in the list.
pendingApprovalbooleantrue: awaiting the owner's confirmation.
rejectedReasonstring | nullIn the shop's own words; not null means the booking was declined and is also cancelled: true.
attendedboolean | nulltrue: a person marked “attended”; false: “did not attend”; null: nobody recorded anything.
createdAtstringISO 8601.

Errors

StatuserrorWhen
400invalid_requestfrom or to is not YYYY-MM-DD.
  • attended: null is not “did not attend”, and you should not import it as such.
  • Rows for the nextFrom date will come again: filter duplicates by id. truncated: true with no nextFrom: the page was filled by a single day; request a narrower from / to.
GET /api/v1/bookings/busy bookings:read

Busy times, and nothing about who holds them. For a scheduler that asks “when am I free”. The hours block also returns the weekly working hours, so that the two refusals of POST /bookings, closed_day and outside_hours, can be checked in advance.

Parameters

ParameterTypeRequiredDefault · limitNote
fromstringNoToday (Tbilisi time)YYYY-MM-DD, inclusive.
tostringNofromYYYY-MM-DD, inclusive.
Request
curl
curl "https://www.botai.ge/api/v1/bookings/busy?from=2026-09-01&to=2026-09-07" \
  -H "Authorization: Bearer $CORPORATE_API_KEY"
JavaScript
const params = new URLSearchParams({ from: "2026-09-01", to: "2026-09-07" });
const res = await fetch(`https://www.botai.ge/api/v1/bookings/busy?${params}`, {
  headers: { Authorization: `Bearer ${process.env.CORPORATE_API_KEY}` },
});
console.log(await res.json());
Python
import os
import requests

res = requests.get(
    "https://www.botai.ge/api/v1/bookings/busy",
    headers={"Authorization": f"Bearer {os.environ['CORPORATE_API_KEY']}"},
    params={"from": "2026-09-01", "to": "2026-09-07"},
    timeout=30,
)
print(res.json())
Response
{
  "from": "2026-09-01",
  "to": "2026-09-07",
  "busy": [
    {
      "date": "2026-09-01",
      "time": "12:00",
      "service": "Haircut",
      "staffName": null,
      "pendingApproval": true
    }
  ],
  "returned": 1,
  "limit": 500,
  "truncated": false,
  "source": "bookings",
  "hours": {
    "timeZone": "Asia/Tbilisi",
    "mustFinishInside": true,
    "week": {
      "mon": { "state": "open", "opens": "10:00", "closes": "20:00" },
      "tue": { "state": "open", "opens": "10:00", "closes": "20:00" },
      "wed": { "state": "open", "opens": "10:00", "closes": "20:00" },
      "thu": { "state": "open", "opens": "10:00", "closes": "20:00" },
      "fri": { "state": "open", "opens": "10:00", "closes": "20:00" },
      "sat": { "state": "unknown" },
      "sun": { "state": "closed" }
    }
  }
}

Response fields

FieldTypeNote
from, tostringThe window used.
busy[]arraydate, time, service, staffName (string | null), pendingApproval (boolean). Active bookings: not cancelled and not declined; those awaiting confirmation are included.
returned, limitintegerlimit is always 500.
truncatedbooleantrue: the window holds more than 500 bookings.
nextFromstringOnly with truncated: true.
sourcestringbookings: our table only.
hoursobjectThe business's working week: timeZone (always Asia/Tbilisi), mustFinishInside and week. It may be absent altogether; see below.
hours.weekobjectSeven keys: mon…sun. Each has a state: open (then opens and closes, HH:MM), closed, or unknown.
hours.mustFinishInsidebooleanAlways true: a booking must finish within working hours, not just start within them.

Errors

StatuserrorWhen
400invalid_requestfrom or to is not YYYY-MM-DD.
Check truncated first. A cut-off period is busy, not free: booking into it is a double booking.
  • truncated: true: request a narrower window, ?from= = nextFrom. If nextFrom is absent, the page was filled by a single day; request day by day.
  • source: "bookings" means the list reflects only our table. If the assistant has Google Calendar linked, that calendar is the authority, and it may hold an entry we have never seen (for example, one added by hand). Read it as “definitely busy”, never as “definitely free”.
  • If you also connect to the same calendar, see how to recognize our entries: Google Calendar.
  • Hours are a week, not a list of dates. Per-day exceptions (holidays, one-off closures) do not exist in this product, so the seven keys are the complete answer and do not grow with from/to. A date is converted to a weekday in Asia/Tbilisi; opens and closes are wall-clock times in that same zone, not UTC.
  • unknown does not mean “closed”. It means the owner has written nothing intelligible for that day. On such a day we do not refuse a booking because of hours: closed_day and outside_hours are returned only on the basis of what the owner actually typed. The three states are different and do not translate into one another.
  • If hours is absent altogether, we could not read the assistant's settings. This is not “has no hours”: absence means “we did not tell you”, and you cannot conclude anything about the day from it. The diary is still correct; a configuration read error does not break it.
  • The hours come from the same source as the write refusal: one function, one answer. So a write within the hours published here cannot return closed_day or outside_hours; it can return slot_taken, because that is about the time, not the day.
POST /api/v1/bookings bookings:write

New booking. The assistant's own setting “bookings need my confirmation” applies to this request as well.

Body fields

ParameterTypeRequiredDefault · limitNote
userIdstringYes—The customer's identifier in your system; it links the booking to the contact and the conversation.
servicestringYes—
datestringYes—YYYY-MM-DD.
timestringYes—24-hour HH:MM.
customerName, customerPhone, customerEmail, staffNamestringNo—
channelstringNoapiLeave it as api: every count and export in the product is grouped by channel, and website would count the booking in the widget's figures.
Request
curl
curl -X POST https://www.botai.ge/api/v1/bookings \
  -H "Authorization: Bearer $CORPORATE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
      "userId": "crm-4471",
      "service": "Haircut",
      "date": "2026-09-01",
      "time": "12:00",
      "customerName": "Nino",
      "customerPhone": "5xx xx xx xx"
    }'
JavaScript
const res = await fetch("https://www.botai.ge/api/v1/bookings", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.CORPORATE_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    userId: "crm-4471",
    service: "Haircut",
    date: "2026-09-01",
    time: "12:00",
    customerName: "Nino",
    customerPhone: "5xx xx xx xx",
  }),
});
console.log(res.status, await res.json());
Python
import os
import requests

res = requests.post(
    "https://www.botai.ge/api/v1/bookings",
    headers={"Authorization": f"Bearer {os.environ['CORPORATE_API_KEY']}"},
    json={
        "userId": "crm-4471",
        "service": "Haircut",
        "date": "2026-09-01",
        "time": "12:00",
        "customerName": "Nino",
        "customerPhone": "5xx xx xx xx",
    },
    timeout=30,
)
print(res.status_code, res.json())
Response · 201 Created
{
  "ok": true,
  "date": "2026-09-01",
  "time": "12:00",
  "service": "Haircut",
  "pendingApproval": true
}

Response fields

FieldTypeNote
okbooleantrue.
date, time, servicestringAs written.
pendingApprovalbooleantrue: the booking is awaiting the owner's confirmation and is not yet shown in the calendar. The value comes from the assistant's setting (on by default) and cannot be changed by the request.

Errors

StatuserrorWhen
400invalid_bodyThe body is not an object.
400invalid_bookinguserId, service, date or time is missing or malformed; field says which.
404assistant_not_foundThe key's assistant no longer exists.
409slot_takenThe time is already taken, in our diary or in the calendar. Nothing was booked; choose another time.
409closed_dayThe business is closed that day. Retrying the same date returns the same response. Check in advance: in hours.week that day's state is closed.
409outside_hoursThe time falls outside working hours, or the booking does not finish before they end. Retrying the same time returns the same response. Check in advance: opens/closes in hours.week.
  • Availability is checked on every write. Before 2026-09-20 it was checked only when the assistant had Google Calendar linked and pendingApproval was false, so the busiest case, a queue of requests awaiting confirmation, was exactly the one nothing checked. Now our own bookings and Google form one busy set, and a request awaiting confirmation holds its hour too. GET /bookings/busy is still a quick advance check, but it is no longer required.
  • The time is checked against working hours, and the booking must fit entirely: on a closed day you get closed_day, outside hours outside_hours. Both are 409 and both are persistent: requesting the same time again returns the same response. The service is still not checked against the assistant's list of services, and the date is still not checked against the past.
  • Both can be checked in advance since 2026-09-20: GET /bookings/busy returns the hours block together with the diary: seven days of the week, each open / closed / unknown, in Asia/Tbilisi wall-clock time. A closed day is closed_day; a booking outside an open day's bounds, or one that cannot finish within them, is outside_hours. On an unknown day we do not refuse because of hours. Until then this text said that an advance check was impossible, which was true at the time.
  • The response does not contain the booking's id. To cancel, find it in GET /bookings (userId, date, time).
POST /api/v1/bookings/{bookingId}/cancel bookings:write

Cancel a booking when the customer cancelled it in your system: the booking is marked as cancelled, the Google Calendar entry is deleted, the reminder stops, and GET /bookings/busy no longer counts the time.

Parameters

ParameterTypeRequiredDefault · limitNote
bookingIdintegerYes (in the path)—The id returned by GET /bookings. There is no body.
Request
curl
curl -X POST https://www.botai.ge/api/v1/bookings/91/cancel \
  -H "Authorization: Bearer $CORPORATE_API_KEY"
JavaScript
const res = await fetch("https://www.botai.ge/api/v1/bookings/91/cancel", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.CORPORATE_API_KEY}` },
});
console.log(res.status, await res.json());
Python
import os
import requests

res = requests.post(
    "https://www.botai.ge/api/v1/bookings/91/cancel",
    headers={"Authorization": f"Bearer {os.environ['CORPORATE_API_KEY']}"},
    timeout=30,
)
print(res.status_code, res.json())
Response
{
  "ok": true,
  "cancelled": true,
  "alreadyCancelled": false,
  "booking": {
    "id": 91,
    "channel": "api",
    "userId": "crm-4471",
    "service": "Haircut",
    "date": "2026-09-01",
    "time": "12:00",
    "staffName": null
  }
}

Response fields

FieldTypeNote
ok, cancelledbooleanBoth true.
alreadyCancelledbooleantrue: the booking was already cancelled.
bookingobjectid, channel, userId, service, date, time, staffName.

Errors

StatuserrorWhen
400invalid_requestbookingId is not a positive integer.
404booking_not_foundNo such booking belongs to this assistant. Another assistant's id and one that does not exist get the same response.
409ambiguous_bookingThe date, time, service and, where present, phone number describe more than one active booking (for example, two specialists at the same time without a phone number), or there are more than 500 active bookings that day. Nothing was cancelled.
  • Nothing is deleted, which is why this is not a DELETE: the booking stays with cancelled: true, and GET /bookings still returns it; the attendance question and the weekly report read this row.
  • Repeating is safe: for a booking that is already cancelled (by you, by a second copy of the request, or by the owner in the dashboard), the response is 200 with alreadyCancelled: true, not an error.
  • On ambiguous_booking, cancel in the dashboard or write to us. Including a phone number when creating a booking avoids this kind of collision.

4. Assistants (account level)

List the account's assistants, create one, change settings · scopes assistants:read, assistants:write · account level: the key reaches every assistant on the account (two levels) · package: Corporate.

Every endpoint can also return: 401, 403 (including no_account), 429, 500; see Errors and limits.

GET /api/v1/assistants assistants:read

Every assistant this account owns. Not paginated.

Request
curl
curl https://www.botai.ge/api/v1/assistants \
  -H "Authorization: Bearer $CORPORATE_API_KEY"
JavaScript
const res = await fetch("https://www.botai.ge/api/v1/assistants", {
  headers: { Authorization: `Bearer ${process.env.CORPORATE_API_KEY}` },
});
console.log(await res.json());
Python
import os
import requests

res = requests.get(
    "https://www.botai.ge/api/v1/assistants",
    headers={"Authorization": f"Bearer {os.environ['CORPORATE_API_KEY']}"},
    timeout=30,
)
print(res.json())
Response
{
  "assistants": [
    {
      "clientId": "demo-salon",
      "name": "Demo salon",
      "active": true,
      "language": "ka",
      "tone": "friendly, concise",
      "requireBookingApproval": true
    }
  ],
  "returned": 1,
  "total": 1,
  "truncated": false
}

Response fields

FieldTypeNote
assistants[]arrayclientId, name, active (boolean), language, tone, requireBookingApproval (boolean).
returnedintegerHow many assistants were returned.
totalintegerHow many the account record names.
truncatedbooleantrue: returned is less than total.
  • A difference between returned and total means the account names an assistant that no longer exists. Repeating the request does not change this; write to us.
POST /api/v1/assistants assistants:write

Create an assistant. It is created switched off: set it up first (knowledge and channels in the dashboard), then switch it on with PATCH.

Body fields

ParameterTypeRequiredDefault · limitNote
clientIdstringYes—Lowercase Latin letters, digits and single hyphens; uppercase letters are converted to lowercase. Permanent: it cannot be changed later.
namestringYes—The name this branch introduces itself by.
activebooleanNofalseMust be true to create it switched on; any other value means switched off.
templateNamestringNo—The name of the starter template; if omitted, the default template is used. An unknown name returns create_failed.
Request
curl
curl -X POST https://www.botai.ge/api/v1/assistants \
  -H "Authorization: Bearer $CORPORATE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"clientId": "demo-salon-2", "name": "Demo salon 2"}'
JavaScript
const res = await fetch("https://www.botai.ge/api/v1/assistants", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.CORPORATE_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ clientId: "demo-salon-2", name: "Demo salon 2" }),
});
console.log(res.status, await res.json());
Python
import os
import requests

res = requests.post(
    "https://www.botai.ge/api/v1/assistants",
    headers={"Authorization": f"Bearer {os.environ['CORPORATE_API_KEY']}"},
    json={"clientId": "demo-salon-2", "name": "Demo salon 2"},
    timeout=30,
)
print(res.status_code, res.json())
Response · 201 Created
{
  "assistant": {
    "clientId": "demo-salon-2",
    "name": "Demo salon 2",
    "active": false,
    "language": "ka"
  },
  "botLimit": 5,
  "botCount": 4
}

Response fields

FieldTypeNote
assistantobjectclientId, name, active, language.
botLimitinteger | nullThe number of assistants agreed for the account; before an agreement, the package minimum; null means unlimited.
botCountintegerAssistants on the account, including the new one.

Errors

StatuserrorWhen
400invalid_client_idclientId is missing or not in an allowed form.
400invalid_requestname is missing.
400create_failedThe assistant could not be created: the clientId is taken by another account, or no such templateName exists. The response deliberately does not say which.
403bot_limit_reachedAbove the assistant limit. The response contains plan, botLimit, botCount.
409client_id_takenThis account already has an assistant with that clientId.
502attach_failedThe assistant was created but could not be attached to the account. Do not retry: a retry will return create_failed; write to us.
  • The limit belongs to the account and works the same way as in the dashboard.
  • Requests are not atomic with respect to each other: two simultaneous creations will both pass the limit check. Create assistants one at a time.
PATCH /api/v1/assistants/{clientId} assistants:write

Change an assistant's settings. Only the fields listed below are allowed in the body.

Parameters

ParameterTypeRequiredDefault · limitNote
clientIdstringYes (in the path)—An assistant that belongs to this account.
namestringNo—Non-empty.
descriptionstringNo—An empty string clears it.
activebooleanNo—true switches the assistant on.
tone, languagestringNo—Non-empty.
requireBookingApprovalbooleanNo—true: bookings need the owner's confirmation.
Request
curl
curl -X PATCH https://www.botai.ge/api/v1/assistants/demo-salon-2 \
  -H "Authorization: Bearer $CORPORATE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"active": true}'
JavaScript
const res = await fetch("https://www.botai.ge/api/v1/assistants/demo-salon-2", {
  method: "PATCH",
  headers: {
    Authorization: `Bearer ${process.env.CORPORATE_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ active: true }),
});
console.log(res.status, await res.json());
Python
import os
import requests

res = requests.patch(
    "https://www.botai.ge/api/v1/assistants/demo-salon-2",
    headers={"Authorization": f"Bearer {os.environ['CORPORATE_API_KEY']}"},
    json={"active": True},
    timeout=30,
)
print(res.status_code, res.json())
Response
{
  "assistant": {
    "clientId": "demo-salon-2",
    "name": "Demo salon 2",
    "active": true,
    "language": "ka",
    "tone": "friendly, concise",
    "requireBookingApproval": true
  }
}

Response fields

FieldTypeNote
assistantobjectAfter the change: clientId, name, active, language, tone, requireBookingApproval.

Errors

StatuserrorWhen
400unsupported_fieldThe body contains a field this endpoint does not change; fields in the response lists them. Channel credentials (the Telegram bot token, the Meta page token) are deliberately not changeable here; they stay in the dashboard.
400nothing_to_writeThe body did not name any field.
400invalid_requestA field's value has the wrong type or is empty; field says which.
404assistant_not_foundNo such assistant belongs to this account.
409write_conflictThe configuration changed between the read and the write. Nothing was written; read again and retry.

5. Usage attribution (account level)

Messages and tokens per assistant · scope usage:read · account level · package: Corporate.

Every endpoint can also return: 401, 403 (including no_account), 429, 500; see Errors and limits.

GET /api/v1/usage usage:read

Messages and tokens per assistant.

Parameters

ParameterTypeRequiredDefault · limitNote
fromstringNoFirst day of the current monthYYYY-MM-DD, inclusive.
tostringNoTodayYYYY-MM-DD, inclusive. One request covers at most 92 days.
clientIdstringNoEvery assistant on the accountNarrows to one assistant; never widens.
Request
curl
curl "https://www.botai.ge/api/v1/usage?from=2026-08-01&to=2026-08-22" \
  -H "Authorization: Bearer $CORPORATE_API_KEY"
JavaScript
const params = new URLSearchParams({ from: "2026-08-01", to: "2026-08-22" });
const res = await fetch(`https://www.botai.ge/api/v1/usage?${params}`, {
  headers: { Authorization: `Bearer ${process.env.CORPORATE_API_KEY}` },
});
console.log(await res.json());
Python
import os
import requests

res = requests.get(
    "https://www.botai.ge/api/v1/usage",
    headers={"Authorization": f"Bearer {os.environ['CORPORATE_API_KEY']}"},
    params={"from": "2026-08-01", "to": "2026-08-22"},
    timeout=30,
)
print(res.json())
Response
{
  "from": "2026-08-01",
  "to": "2026-08-22",
  "assistants": [
    {
      "clientId": "demo-salon",
      "messages": 4120,
      "calls": 4408,
      "inputTokens": 5203991,
      "outputTokens": 412884,
      "cacheWriteTokens": 74110,
      "cacheReadTokens": 4711002,
      "unmeasuredCalls": 3,
      "byModel": [
        {
          "provider": "anthropic",
          "model": "claude-haiku-4-5",
          "calls": 4408,
          "inputTokens": 5203991,
          "outputTokens": 412884,
          "cacheWriteTokens": 74110,
          "cacheReadTokens": 4711002,
          "unmeasuredCalls": 3
        }
      ]
    }
  ]
}

Response fields

FieldTypeNote
from, tostringThe window used.
assistants[]arrayOne row per assistant on the account (or the one chosen with clientId), including zeros.
messagesintegerMessages written by customers: the unit a package is sold in and the one the limit applies to.
callsintegerTotal model calls, including unmeasured ones.
inputTokens, outputTokens, cacheWriteTokens, cacheReadTokensintegerWhat the replies cost us. The sum over measured calls.
unmeasuredCallsintegerThe part of calls whose tokens we could not measure. These are not free calls.
byModel[]arrayThe same figures per model: provider, model, calls, the four token fields, unmeasuredCalls. Empty if there were no calls.

Errors

StatuserrorWhen
400invalid_requestfrom or to is not YYYY-MM-DD, or from is later than to.
400window_too_longThe window is longer than 92 days. The response contains maxDays.
404assistant_not_foundclientId does not belong to this account.
413window_too_largeThe window contains more calls than one request can read (up to 40 000). Request a shorter window; we do not return a total that would silently stop counting in the middle of the month.
  • messages and tokens are never mixed: one is the invoice unit, the other is our cost. An assistant with a long knowledge base spends several times more tokens per message than a bot with a one-line FAQ.
  • There is no money field (cost) in any currency: we do not publish a token price anywhere.

6. Products API

Writing the catalog: product, variant, price, stock · scope products:write · assistant level · the “Product sync” add-on (403 addon_required without it).

Every endpoint can also return: 401, 403 (addon_required, scope_required), 429, 500; see Errors and limits.

ConditionValue
Base URLhttps://www.botai.ge/api/v1/products
Add-on“Product sync” on the assistant you write to. Without it, every request returns 403 addon_required. Included in Corporate; sold separately on Start and Business.
Scopeproducts:write. If the name is not in the scope list, you get 403 scope_required and nothing in the catalog is deleted. A key issued without a scope list (on the Products screen) can still write. The add-on and the scope are two separate checks: both must pass.
BodyJSON, at most 1 000 000 bytes (413 body_too_large).
LimitsProducts per request: 500; variants per product: 100, per request: 5 000.
Rate60 requests per minute per assistant; 120 per IP address.
MoneyWhole tetri: 18999 = 189.99 ₾.

Body fields

ParameterTypeRequiredDefault · limitNote
productsarrayYes1–500Products. An empty array returns 400 empty_catalogue.
sourceIdintegerNo—The assistant's catalog source. If omitted, this assistant's own “catalog from API” source is used (created on the first request). It is returned in the response. Someone else's source returns 404 source_not_found.

products[] fields

FieldTypeRequiredLimitNote
idstring | integerYes—The product id in your system: we use it to recognize the product on the next write and update it; no second copy is created. Synonym: externalId.
namestringYes500 charactersRequired on PATCH as well.
descriptionstringNo20 000 characters
categorystringNo500 characters
imageUrlstringNo2 000 charactersSynonym: image.
statusstringNo—active (default), hidden, archived. A product's status is derived from its variants: one active variant keeps the product active.
variantsarrayNo100If the product has a single form, omit this: sku, price, stock and attributes are written on the product itself.

products[].variants[] fields

FieldTypeRequiredLimitNote
idstring | integerConditional—The variant id; if absent, sku. A single-variant product can use the product's id; a multi-variant one cannot: id or sku is required. Synonym: externalId.
skustringNo200 characters
priceTetriinteger | string | nullNo2 147 483 647Price; rules below. Synonym: price.
salePriceTetriinteger | string | nullNo2 147 483 647Sale price; counted only together with the regular price. Synonym: salePrice.
stockinteger | string | nullNo2 147 483 647Stock; rules below.
statusstringNo—Same as on the product.
attributesobjectNo20 keysValue: a string or a number: {"Size": "42", "Color": "Black"}.

Price and stock

ValueHow it is read
Price, JSON number18999 = 18999 tetri. A fraction (189.99) returns 400 invalid_product, and the error says 18999. A negative value returns 400.
Price, JSON stringRead the same way as a feed's price column: "189.99", "189,99", "1 899,00 GEL", "1,899.00".
Price in another currency"45 USD": the product stays, the price is dropped, and foreign_currency appears in warnings in the response. Nothing converts the currency.
stock: null or the field is absent“We do not count this by units”: the assistant treats the product as available.
stock: 0“We counted, none left”: the assistant says it is out of stock.
stock, string"in stock", "out of stock" or a number as a string.
POST /api/v1/products products:write

Full replacement: the body is this source's entire catalog. Anything you did not name is archived, not deleted. Suited to a nightly or hourly full export.

Request
curl
curl -X POST https://www.botai.ge/api/v1/products \
  -H "Authorization: Bearer $PRODUCTS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
      "products": [
        {
          "id": "SKU-1041",
          "name": "Leather boot",
          "category": "Footwear",
          "variants": [
            {
              "id": "1041-42",
              "sku": "1041-42",
              "attributes": {"Size": "42", "Color": "Black"},
              "priceTetri": 18999,
              "stock": 3
            },
            {
              "id": "1041-43",
              "sku": "1041-43",
              "attributes": {"Size": "43", "Color": "Black"},
              "priceTetri": 18999,
              "stock": 0
            }
          ]
        },
        {
          "id": "SKU-2007",
          "name": "Leather belt",
          "category": "Accessory",
          "priceTetri": 4500,
          "stock": null
        }
      ]
    }'
JavaScript
const res = await fetch("https://www.botai.ge/api/v1/products", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.PRODUCTS_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    products: [
      {
        id: "SKU-1041",
        name: "Leather boot",
        category: "Footwear",
        variants: [
          {
            id: "1041-42",
            sku: "1041-42",
            attributes: { "Size": "42", "Color": "Black" },
            priceTetri: 18999,
            stock: 3,
          },
          {
            id: "1041-43",
            sku: "1041-43",
            attributes: { "Size": "43", "Color": "Black" },
            priceTetri: 18999,
            stock: 0,
          },
        ],
      },
      {
        id: "SKU-2007",
        name: "Leather belt",
        category: "Accessory",
        priceTetri: 4500,
        stock: null,
      },
    ],
  }),
});
console.log(res.status, await res.json());
Python
import os
import requests

res = requests.post(
    "https://www.botai.ge/api/v1/products",
    headers={"Authorization": f"Bearer {os.environ['PRODUCTS_API_KEY']}"},
    json={
        "products": [
            {
                "id": "SKU-1041",
                "name": "Leather boot",
                "category": "Footwear",
                "variants": [
                    {
                        "id": "1041-42",
                        "sku": "1041-42",
                        "attributes": {"Size": "42", "Color": "Black"},
                        "priceTetri": 18999,
                        "stock": 3,
                    },
                    {
                        "id": "1041-43",
                        "sku": "1041-43",
                        "attributes": {"Size": "43", "Color": "Black"},
                        "priceTetri": 18999,
                        "stock": 0,
                    },
                ],
            },
            {
                "id": "SKU-2007",
                "name": "Leather belt",
                "category": "Accessory",
                "priceTetri": 4500,
                "stock": None,
            },
        ],
    },
    timeout=30,
)
print(res.status_code, res.json())
Response
{
  "ok": true,
  "mode": "replace",
  "sourceId": 7,
  "created": 2,
  "updated": 0,
  "archived": 5,
  "variants": 3,
  "warnings": []
}

Response fields

FieldTypeNote
okbooleantrue. On 502 write_failed: false.
modestringreplace.
sourceIdintegerThe source that was written to.
created, updatedintegerNew and updated products.
archivedintegerArchived products: those that were in this source and were not named in the request.
variantsintegerVariants written.
warnings[]arraycode, message (in Georgian), index (the product's position, if applicable).

Errors

StatuserrorWhen
400invalid_bodyThe body is not an object; products is not an array; sourceId is not a positive integer (field).
400empty_catalogueproducts is empty.
400invalid_productA product or variant is malformed. index is the product's position in the array (starting from 0), field is the field path, e.g. variants[0].priceTetri.
400duplicate_product_id, duplicate_variant_idThe same id twice in one request (within one product, a variant's).
400too_many_variantsMore than 100 variants on one product.
404source_not_foundNo such source belongs to this assistant.
413too_many_productsMore than 500 products in one request.
413too_many_variantsMore than 5 000 variants in one request.
413body_too_largeThe body is larger than 1 000 000 bytes; the response contains maxBytes.
502write_failedPart was written and part was not. The response shows what was written (created, updated, variants); nothing was archived.
  • An empty POST does not clear the catalog (empty_catalogue): this is almost always an error in your export. To take a product off sale, send it with "status": "archived".
  • For a catalog larger than 500: send pages with PATCH, and the products to take off sale last, with PATCH and "status": "archived". A POST on the last page would archive everything except that page.
  • 502 write_failed: the same request can be safely repeated; products are updated by id.
PATCH /api/v1/products products:write

Partial update: only the named products are updated or added; nothing is archived. Body and errors are the same as for POST.

Request
curl
curl -X PATCH https://www.botai.ge/api/v1/products \
  -H "Authorization: Bearer $PRODUCTS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
      "products": [
        {
          "id": "SKU-1041",
          "name": "Leather boot",
          "variants": [{"id": "1041-42", "priceTetri": 16999, "stock": 2}]
        }
      ]
    }'
JavaScript
const res = await fetch("https://www.botai.ge/api/v1/products", {
  method: "PATCH",
  headers: {
    Authorization: `Bearer ${process.env.PRODUCTS_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    products: [
      {
        id: "SKU-1041",
        name: "Leather boot",
        variants: [{ id: "1041-42", priceTetri: 16999, stock: 2 }],
      },
    ],
  }),
});
console.log(res.status, await res.json());
Python
import os
import requests

res = requests.patch(
    "https://www.botai.ge/api/v1/products",
    headers={"Authorization": f"Bearer {os.environ['PRODUCTS_API_KEY']}"},
    json={
        "products": [
            {
                "id": "SKU-1041",
                "name": "Leather boot",
                "variants": [{"id": "1041-42", "priceTetri": 16999, "stock": 2}],
            },
        ],
    },
    timeout=30,
)
print(res.status_code, res.json())
Response
{
  "ok": true,
  "mode": "upsert",
  "sourceId": 7,
  "created": 0,
  "updated": 1,
  "variants": 1,
  "warnings": []
}

Response fields

FieldTypeNote
modestringupsert.
archived—The field is not in the PATCH response: PATCH archives nothing.
Everything elseSame as for POST.

7. Payments

One request opens an order and returns a payment link or its QR code · scope payments:write · assistant level · the access condition is the same as for the Products API: the “Product sync” add-on.

Every endpoint can also return: 401, 403 (addon_required, scope_required), 429, 500; see Errors and limits.

ConditionValue
EndpointPOST https://www.botai.ge/api/v1/payments
Add-on“Product sync” on the assistant you sell through, the same as for the Products API; there is no new condition here. Without it: 403 addon_required.
Scopepayments:write. If the name is not in the scope list, you get 403 scope_required, no order is opened and no payment link is created. A key issued without a scope list can sell. Scopes are fixed when the key is issued.
MoneyWhole tetri: 18999 = 189.99 ₾.
CurrencyWhatever is in the catalog. Card payments are available in GEL, USD, EUR, GBP; nothing is converted anywhere.
Rate30 sales per minute per assistant; 120 requests per minute per IP address.

Body fields

FieldTypeRequiredLimitNote
variantIdstring | integerYes128 charactersThe variant id in the catalog: the Products API's id (or sku).
productIdstring | integerNo128 charactersOnly narrows: needed when one variantId is on two products in this shop.
quantityintegerNo1–1000 · default 1
methodstringNoonline (default), codcod: cash on delivery.
orderRefstringNoA-Za-z0-9_-, 4–64 charactersOrder number and idempotency key. If you omit it, we will assign one.
customerobjectNoname 120, phone 40, email 160The buyer. Long values are truncated.
descriptionstringNo200 charactersSent to Quickpay for card payments. Long values are truncated.
notestringNo500 charactersStored on the order. Long values are truncated.
amountTetriintegerNo—For checking only: must match the catalog total.
currencystringNo—For checking only: must match the catalog currency.
POST /api/v1/payments payments:write

Opens an order and creates a payment on the shop's own Quickpay account. With online, the payment link and its QR code are returned.

Request
curl
curl -X POST https://www.botai.ge/api/v1/payments \
  -H "Authorization: Bearer $PRODUCTS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
      "variantId": "1041-42",
      "quantity": 1,
      "method": "online",
      "orderRef": "ORD-10482",
      "customer": {"name": "Nino", "phone": "+995555100200"}
    }'
JavaScript
const res = await fetch("https://www.botai.ge/api/v1/payments", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.PRODUCTS_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    variantId: "1041-42",
    quantity: 1,
    method: "online",
    orderRef: "ORD-10482",
    customer: { name: "Nino", phone: "+995555100200" },
  }),
});
console.log(res.status, await res.json());
Python
import os
import requests

res = requests.post(
    "https://www.botai.ge/api/v1/payments",
    headers={"Authorization": f"Bearer {os.environ['PRODUCTS_API_KEY']}"},
    json={
        "variantId": "1041-42",
        "quantity": 1,
        "method": "online",
        "orderRef": "ORD-10482",
        "customer": {"name": "Nino", "phone": "+995555100200"},
    },
    timeout=30,
)
print(res.status_code, res.json())
Response · 201 Created
{
  "ok": true,
  "orderId": 812,
  "orderRef": "ORD-10482",
  "method": "online",
  "outcome": "pending",
  "amountTetri": 18999,
  "amountLabel": "189.99 ₾",
  "currency": "GEL",
  "message": "გადახდის ბმული მზადაა — გახსენით და გადაიხადეთ.",
  "checkoutUrl": "https://pay.example.com/checkout/3b1f9c1e",
  "qrSvg": "<svg …>",
  "paymentUuid": "3b1f9c1e-7a52-4d0e-9a41-5f6a2c8d0b17",
  "variantId": "1041-42",
  "quantity": 1,
  "unitAmountTetri": 18999,
  "replayed": false
}
Response · method: cod · 201 Created
{
  "ok": true,
  "orderId": 813,
  "orderRef": "ORD-10483",
  "method": "cod",
  "outcome": "awaiting_offline",
  "amountTetri": 18999,
  "amountLabel": "189.99 ₾",
  "currency": "GEL",
  "message": "შეკვეთა მიღებულია — თანხას მიტანისას გადაიხდით.",
  "variantId": "1041-42",
  "quantity": 1,
  "unitAmountTetri": 18999
}

Response fields

FieldTypeNote
okbooleantrue.
orderId, orderRefinteger, stringThe order on our side and its number.
methodstringonline or cod.
outcomestringpending when an online order is opened; awaiting_offline for cod. On 200 (a repeat): the order's current state, e.g. paid.
amountTetri, amountLabel, currencyinteger, string, stringThe total from the catalog: price × quantity.
messagestringIn Georgian; ready-made text for the buyer.
checkoutUrl, qrSvg, paymentUuidstringOnly with online. qrSvg is the QR code of the same link; null if it could not be drawn.
testKeyNoticestringOnly if the shop has a Quickpay test key: no money is charged.
variantId, quantity, unitAmountTetristring, integer, integerWhat was priced, and at what price.
replayedbooleantrue: Quickpay returned a payment already opened for the same orderRef. The field is absent on a cod 201.

Errors

StatuserrorWhen
400bad_requestThe body is not an object.
400variant_requiredvariantId was not sent or cannot be read.
400bad_method, bad_quantity, bad_amount, bad_currency, bad_order_ref, bad_product_idOne field is malformed; field says which. amountTetri is whole tetri; 149.99 is an error here.
403addon_requiredThe assistant does not have the products add-on.
403scope_requiredThe key does not have payments:write; scope names it.
404variant_not_foundNo such variant is in this assistant's catalog. Another assistant's variant gets the same response.
409variant_ambiguousTwo variants with the same id were found in this shop. Specify productId.
409variant_not_for_sale, variant_unpricedThe variant has been taken off sale, or it has no price.
409amount_mismatch, currency_mismatchThe body named an amount or a currency that did not match the catalog. Nothing was created.
409amount_not_chargeableThe total (price × quantity) is zero or exceeds 2 147 483 647 tetri.
409currency_not_chargeableA card payment cannot be created in this currency. chargeableIn lists the ones it can be created in.
409cod_disabledThe shop does not accept cash on delivery. methods lists what remains: ["online"], or [] when card payment is not set up either (then the shop confirms the payment method itself).
409payment_account_missing, payment_key_unreadableQuickpay has not been connected yet, or the stored key can no longer be read. The owner needs to fix this.
409order_ref_takenA different sale is already open under this number. Choose a new number.
400, 404, 409, 429, 502payment_providerQuickpay refused or is not responding. failure names the reason, message is in Georgian; currency appears if the refusal concerns the currency.
502order_not_savedThe payment was created, but we could not record it on our side. Retry with the same orderRef.
  • 201: the order has just been created. 200: the same sale is already open for the same orderRef: you get the same link and no second payment is created. The same orderRef for a different sale returns 409 order_ref_taken.
  • cod does not create a link: the order is opened with awaiting_offline, and the shop's courier collects the amount. This method is available only when the owner has enabled it in the dashboard; otherwise you get 409 cod_disabled.
  • The amount is set by the variant's price, not by your request: no other price exists anywhere. An empty amountTetri is the intended way to use this endpoint.
  • 502 order_not_saved: orderRef is the idempotency key, so a retry returns the same payment and does not create a second one. If you did not send an orderRef, it is in the response: retry with it.
  • On this endpoint message is in Georgian (in the rest of the API, in English).
POST /api/v1/payments/quickpay/webhook/{clientId}
This endpoint belongs to the bank: Quickpay calls us; you never do. No key or add-on is checked here; the only door is the signature. There is nothing for you to build.

We give Quickpay this URL ourselves when the payment is created. The payment result appears in the dashboard, on the Orders screen.

Only one request is ever sent from us to you: the booking webhook.

Errors and limits

error is a stable code; message is in English (in Georgian for payments); field, index appear where the problem is in a specific entry. See also: 7. Payments, Error handling.

StatuserrorWhat happened
400invalid_bodyThe body is not an object, or a section has the wrong type.
400nothing_to_writeThe body did not name any section.
400invalid_service / invalid_extra_price / invalid_faq / invalid_rule / invalid_documentOne entry is malformed. index and field say which. In extraPrices a row needs both label and price; we do not drop a half-filled row, we refuse the whole request.
400duplicate_document_idThe same id came twice in one request.
400invalid_bookingA required booking field is missing or malformed.
400invalid_requestA parameter, path segment or required field is malformed: a booking id that is not a positive integer; a name missing from POST /assistants.
400invalid_productProducts API: a product or variant is malformed. index and field say which.
400empty_catalogueProducts API: products is empty. An empty POST does not clear the catalog; this is almost always an error in your export. Send what you want to take off sale with "status": "archived".
400duplicate_product_id / duplicate_variant_idProducts API: the same id twice in one request.
400invalid_client_idclientId is not in an allowed form.
400create_failedThe assistant could not be created: the clientId is taken by another account, or no such templateName exists. The response does not say which.
400unsupported_fieldPATCH /assistants was sent a field it does not change.
400window_too_longThe usage window is longer than 92 days.
401unauthorizedThe key is missing, unknown, malformed or revoked.
403plan_requiredThe account is not on the Corporate package.
403scope_requiredThe key does not have the scope this endpoint requires. scope names it.
403addon_requiredThe assistant does not have the products add-on.
403no_accountThe key's assistant has no owning account, so the account-level endpoints are unavailable to it.
403bot_limit_reachedAbove the account's assistant limit.
404assistant_not_foundNo such assistant belongs to this account.
404booking_not_foundNo such booking belongs to this assistant.
404source_not_foundNo such catalog source belongs to this assistant.
409write_conflictPOST / PATCH /knowledge and PATCH /assistants/{clientId}: the assistant's configuration changed between the read and the write. Nothing was written, neither the configuration nor the documents. Read the current state and send again.
409client_id_takenPOST /assistants: this account already has an assistant with that clientId.
409slot_takenSomeone else took the time between the check and the write. Nothing was booked.
409closed_dayThe business is closed that day. This is not a race, and retrying will not fix it. You can see it in advance in the hours block of GET /bookings/busy.
409outside_hoursThe time falls outside working hours. This is not a race, and retrying will not fix it. You can see it in advance in the hours block of GET /bookings/busy.
409ambiguous_bookingThe cancellation would affect more than one booking. Nothing was cancelled.
413body_too_largeThe body exceeds the limit.
413too_many_services / too_many_extra_prices / too_many_faq / too_many_rules / too_many_documentsAbove a section's limit (200 / 20 / 300 / 100 / 10).
413document_too_longA knowledge document is longer than 8 000 characters.
413too_many_productsProducts API: more than 500 products in one request.
400 / 413too_many_variantsProducts API: above the variant limit per product or per request.
413window_too_largeThe window contains more calls than one request can read.
429rate_limitedToo many requests per minute for this assistant. retryAfterMs says how long to wait.
429too_many_attemptsToo many requests per minute from this IP address, counted before we look at the key.
500internal_errorOur fault. Try again.
500contacts_unreadableGET /contacts: we could not read the contact base. This is deliberately not an empty list: “there are no contacts” and “we could not read them” are different facts. If it persists, write to us.
502write_failedPart of the write succeeded and part did not; nothing was deleted. The response says what was written: applied and failed (knowledge base), created and updated (catalog). The same request can be safely repeated.
502attach_failedThe assistant was created, but we could not attach it to the account. Do not retry this; write to us. A retry will only return create_failed.
A refused body writes nothing. Validation runs before the first write: after 400 everything is as it was, and even the valid sections of the same request have not been written.
LimitCorporate APIProducts API
Body512 000 bytes1 000 000 bytes
Requests per minute, per assistant12060
Requests per minute, per IP address120120
List page500 rows500 products

Two 429s, two separate counters: too_many_attempts per address (before the key is checked), rate_limited per assistant. Exhausting one does not use up the other.

Error handling

Whether to retry depends on the code, not the status: the same 502 is sometimes retried and sometimes not.

Status and errorRetry?Action
429 rate_limited, too_many_attempts Yes Wait the retryAfterMs milliseconds from the response body and repeat the same request.
500 internal_error Yes Retry with exponential backoff (0,5 s, 1, 2, 4…), a limited number of times. Always send orderRef with POST /payments: the same orderRef returns the same payment and does not create a second one.
500 contacts_unreadable Later A fault on our side. Do not treat the response as an empty list. If it persists, write to us.
502 write_failed Yes, unchanged The write partly succeeded; nothing was deleted. The response says what was written; the request is idempotent.
502 order_not_saved Yes, with the same orderRef The payment was created but could not be recorded on our side. Retrying with the same orderRef returns the same payment. If you did not send an orderRef, it is in the response: retry with it.
502 attach_failed No The assistant was created and could not be attached to the account. A retry will return create_failed. Write to us.
409 write_conflict After a read Nothing was written. Call GET /knowledge or GET /assistants and send again.
409 slot_taken No, not as is Nothing was booked. Choose another time.
409 closed_day No, not as is Nothing was booked. Choose another day; trying the same date will always return the same response. The hours of GET /bookings/busy says which days are closed.
409 outside_hours No, not as is Nothing was booked. Choose a time within working hours; trying the same time will always return the same response. The hours are in hours of GET /bookings/busy.
409 ambiguous_booking No Nothing was cancelled. Cancel in the dashboard or write to us.
400, 401, 403, 404, 413 and the remaining 409 No, not as is The request, key, package or scope needs fixing; message, field, index say what. 401: the key. 403 plan_required, addon_required, scope_required: a package, an add-on, or a new key with the required scope. 413 window_too_large: a narrower window.

A function that implements the rule above: only the codes marked “Yes” in the table are retried; for the rest, the error is returned immediately.

Retry function
JavaScript
// Repeated: 429 (after retryAfterMs), 500 internal_error, 502 write_failed
// and order_not_saved. Everything else is thrown at once, attach_failed included.
const RETRY = new Set(["rate_limited", "too_many_attempts", "internal_error", "write_failed", "order_not_saved"]);

async function callApi(url, init = {}, maxAttempts = 5) {
  for (let attempt = 1; ; attempt++) {
    const res = await fetch(url, init);
    const body = await res.json().catch(() => ({}));
    if (res.ok) return body;

    if (attempt >= maxAttempts || !RETRY.has(body.error)) {
      throw Object.assign(new Error(`${res.status} ${body.error}: ${body.message}`), { status: res.status, body });
    }
    const pause = body.retryAfterMs ?? Math.min(30_000, 500 * 2 ** (attempt - 1));
    await new Promise((resolve) => setTimeout(resolve, pause));
  }
}

// const usage = await callApi("https://www.botai.ge/api/v1/usage", {
//   headers: { Authorization: `Bearer ${process.env.CORPORATE_API_KEY}` },
// });
Python
import os
import time

import requests

# Repeated: 429 (after retryAfterMs), 500 internal_error, 502 write_failed
# and order_not_saved. Everything else raises at once, attach_failed included.
RETRY = {"rate_limited", "too_many_attempts", "internal_error", "write_failed", "order_not_saved"}


def call_api(method, url, max_attempts=5, **kwargs):
    for attempt in range(1, max_attempts + 1):
        res = requests.request(method, url, timeout=30, **kwargs)
        try:
            body = res.json()
        except ValueError:
            body = {}
        if res.ok:
            return body

        if attempt == max_attempts or body.get("error") not in RETRY:
            raise RuntimeError(f"{res.status_code} {body.get('error')}: {body.get('message')}")
        pause_ms = body.get("retryAfterMs")
        time.sleep(pause_ms / 1000 if pause_ms is not None else min(30, 0.5 * 2 ** (attempt - 1)))


# usage = call_api(
#     "GET",
#     "https://www.botai.ge/api/v1/usage",
#     headers={"Authorization": f"Bearer {os.environ['CORPORATE_API_KEY']}"},
# )

Versions and changes

The version is in the base path: /api/v1.

In v1 we add new endpoints and optional fields. We avoid changing what already exists. If we ever need a breaking change, we will notify you in advance.

On your side: ignore unknown fields in a response; handle an unknown error code by its HTTP status.

DateChange
2026-09-19v1: the current contract

Google Calendar: the assistant's entry

Recognizing our entry and busy time in the owner's Google Calendar · package: Business and above · no API key is used.

Entry fields

FieldTypeNote
summarystring<service> — <customer name>. Without a name: უცნობი მომხმარებელი (“unknown customer”).
descriptionstringLines: ტელეფონი: … (phone; - if there is no phone), არხი: … (channel), მოთხოვნილი დრო: YYYY-MM-DD HH:MM (requested time); when a specialist was requested, also მოთხოვნილი სპეციალისტი: … (requested specialist).
start, endobjectdateTime is in UTC (Z), timeZone is Asia/Tbilisi. end = start + the service duration; without a duration, 60 minutes.
transparencystringAlways opaque. A transparent entry does not appear in the freebusy response at all, neither as busy nor as free.
extendedProperties.privateobjectFour keys; see below.

extendedProperties.private

KeyValuePurpose
botaiSourcebotai.ge/bookingA constant marker. Write your filter on this.
botaiClientIdThe assistant's identifier, e.g. demo-salonSeveral assistants can write to one calendar; this is how you tell them apart.
botaiChanneltelegram, website, whatsapp, …The same as the channel line of description.
botaiRequestedThe time the customer requested, as text, e.g. 2026-09-14 14:30The same as the requested-time line of description, in machine-readable form.
Request · Google Calendar API
GET /calendar/v3/calendars/{calendarId}/events
  ?privateExtendedProperty=botaiSource%3Dbotai.ge%2Fbooking
Calendar entry
{
  "summary": "Haircut — Nino",
  "description": "ტელეფონი: +995555000000\nარხი: telegram\nმოთხოვნილი დრო: 2026-09-14 14:30",
  "transparency": "opaque",
  "start": {"dateTime": "2026-09-14T10:30:00.000Z", "timeZone": "Asia/Tbilisi"},
  "end": {"dateTime": "2026-09-14T11:15:00.000Z", "timeZone": "Asia/Tbilisi"},
  "extendedProperties": {
    "private": {
      "botaiSource": "botai.ge/booking",
      "botaiClientId": "demo-salon",
      "botaiChannel": "telegram",
      "botaiRequested": "2026-09-14 14:30"
    }
  }
}
  • Do not base your filter on summary or description: a hand-typed “service — name” looks identical.
  • private means “for this copy of the calendar”, not “hidden”: everyone who can read the calendar sees these fields too. They contain nothing that is not already in summary and description.
  • The booking record's number is not in the entry: the calendar entry is created before the booking is written to our database. The link goes the other way: we store the Google entry's id, and in the webhook it is booking.calendarEventId.
  • The four keys together do not form a unique key.
  • A calendar set to another time zone shows the same moment in its own zone's time. That is a calendar setting, not part of this API.
Do not write a filter on the all-day [დასადასტურებელი დრო] (“time to confirm”) entry. New bookings are no longer created in this form; it can still appear when an old request is confirmed.

Booking webhook: we send to you

When a booking is created, confirmed, declined or cancelled, we send a POST to the URL the owner specified · package: Business and above · an HMAC signature instead of an API key.

Delivery rules

TopicRule
Where to switch it onDashboard: Assistant settings → Other → Booking webhook.
PackageChecked on every delivery, not only when the URL is saved: for an account that moves down to Start, delivery stops.
RequestPOST, content-type: application/json; charset=utf-8.
AttemptsOne, with a 5-second timeout. There is no retry and no queue.
Your responseWe do not read the body. Any 2xx is a success; 3xx is a failure, and we do not follow redirects.
FailureThe event is lost. No warning is sent and there is no log.
The webhook is about speed, not the full picture. A meeting entered by hand and a missed event do not appear in it; Google Calendar gives the full picture.

Events

eventWhenbooking.status
booking.createdA booking was written. Never for a time that is already taken.confirmed; pending if the assistant holds the booking for confirmation
booking.approvedThe shop confirmed the request. From this moment the time is a commitment.confirmed
booking.rejectedThe shop declined the request. Release the time.rejected
booking.cancelledThe booking was cancelled, by the customer in the assistant or through our API.cancelled
webhook.testPress Test in the dashboard. The data is sample data (სატესტო სერვისი, 2030-01-01, 12:00, website), not a real booking.confirmed
  • A booking that needs confirmation produces two events: booking.created (pending), then booking.approved or booking.rejected. A booking without confirmation produces one: booking.created (confirmed).
  • Skip an unknown event and still respond with 2xx: the list will grow.
Request headers
POST /hooks/botai HTTP/1.1
Host: example.ge
content-type: application/json; charset=utf-8
user-agent: BotAI-Webhooks/1.0 (+https://botai.ge)
x-botai-event: booking.created
x-botai-delivery: 0f7b1d2c-9a44-4e13-8b56-2c9f0e5a7d31
x-botai-timestamp: 1789000000
x-botai-signature: v1=66d7ff203a2cb9f512441e6fbbce1f43d8724346f421ff786cacd925ce067d73
HeaderValue
x-botai-eventThe event name, the same as event in the body. For routing before the body is read.
x-botai-deliveryA UUID, unique per attempt; there is only one attempt, so it is also unique per event. Store it for idempotency.
x-botai-timestampUnix seconds at the moment of signing. Part of the signed material.
x-botai-signaturev1= followed by 64 lowercase hexadecimal characters.
Request body
{
  "event": "booking.created",
  "deliveryId": "0f7b1d2c-9a44-4e13-8b56-2c9f0e5a7d31",
  "sentAt": "2026-09-10T00:26:40.480Z",
  "assistantId": "demo-salon",
  "booking": {
    "service": "თმის შეჭრა",
    "date": "2026-09-14",
    "time": "14:30",
    "timezone": "Asia/Tbilisi",
    "durationMinutes": 45,
    "staff": "ნინო",
    "staffRequested": null,
    "channel": "telegram",
    "status": "confirmed",
    "calendarEventId": "6k3q1m0p9r7s2t4u",
    "rejectedReason": null,
    "createdAt": "2026-09-10T00:26:39.000Z"
  }
}

Body fields

FieldTypeNote
eventstringOne of the five listed above.
deliveryIdstringUUID v4; the same as x-botai-delivery.
sentAtstringISO 8601, UTC. When we assembled it.
assistantIdstringThe assistant's identifier, the one in the dashboard URL. Never the account's.
booking.servicestringExactly as the shop wrote it in its list of services.
booking.datestringYYYY-MM-DD, in booking.timezone, not in UTC.
booking.timestringHH:MM, 24-hour, in booking.timezone.
booking.timezonestringCurrently always Asia/Tbilisi. Read it; do not assume it.
booking.durationMinutesnumberThe service duration; 60 if not specified. The same as on the Google Calendar entry.
booking.staffstring | nullThe specialist the booking is with. null: the business has no list of specialists.
booking.staffRequestedstring | nullThe specialist the customer asked for at a business without a list. It is not stored separately in the database, so it appears only on booking.created; null on later events does not mean the customer withdrew the request.
booking.channelstringwebsite, telegram, whatsapp, instagram, messenger. Our channel, not the customer.
booking.statusstringconfirmed | pending | cancelled | rejected. The status after this event.
booking.calendarEventIdstring | nullThe id of the Google Calendar entry (not of the calendar). null: no entry exists, e.g. for a booking awaiting confirmation.
booking.rejectedReasonstring | nullThe shop's own words, on booking.rejected.
booking.createdAtstringISO 8601, when the booking was first created. It is the same on all four events and is the key for ordering them.
  • The customer's name and phone number are not sent: the shop types the webhook URL itself, and personal data would be silently sent to a mistyped URL.
  • You cannot match events to a customer record. You match them to each other by the natural key assistantId + service + date + time; createdAt distinguishes a booking that was made, cancelled and made again for the same time.
  • The body is sent compact, in JSON.stringify form (no whitespace).

Signature

TopicRule
Signed materialv1:<timestamp>:<raw body>, literally, with the colons. <timestamp> is the value of x-botai-timestamp.
AlgorithmHMAC-SHA256, with the key whsec_….
Headerx-botai-signature: v1=<hex>.
Time windowx-botai-timestamp and your clock must differ by no more than 300 seconds, in either direction.
ComparisonIn constant time (timingSafeEqual, compare_digest).
  • Verify the raw body. JSON.parse followed by JSON.stringify does not return the bytes unchanged: whitespace and number formatting change. Take the bytes before your web framework parses the body: in Express express.raw({ type: "application/json" }), in Flask request.get_data(), in FastAPI await request.body().
  • The timestamp is inside the signature, so a replay of an intercepted request will not pass once the window has closed.
  • Reject in both directions: a send time ahead of your clock carries the same risk as an old one.
Verification function
JavaScript
const crypto = require("node:crypto");

// rawBody — Buffer or string, exactly as it arrived.
// headers — headers with lower-case names (Node http, Express).
function verify(rawBody, headers, secret) {
  const ts = headers["x-botai-timestamp"];
  const got = headers["x-botai-signature"];
  if (typeof ts !== "string" || typeof got !== "string") return false;

  const seconds = Number(ts);
  if (!Number.isFinite(seconds)) return false;
  if (Math.abs(Math.floor(Date.now() / 1000) - seconds) > 300) return false;

  const expected =
    "v1=" +
    crypto
      .createHmac("sha256", secret)
      .update(`v1:${ts}:`, "utf8")
      .update(rawBody)
      .digest("hex");
  const a = Buffer.from(got, "utf8");
  const b = Buffer.from(expected, "utf8");
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}
Python
import hashlib
import hmac
import time


# raw_body — bytes, exactly as it arrived.
# headers — a dictionary of headers with lower-case names (Flask and FastAPI headers are fine).
def verify(raw_body: bytes, headers, secret: str) -> bool:
    ts = headers.get("x-botai-timestamp")
    got = headers.get("x-botai-signature")
    if not ts or not got:
        return False
    try:
        seconds = int(ts)
    except ValueError:
        return False
    if abs(time.time() - seconds) > 300:
        return False

    material = b"v1:" + ts.encode() + b":" + raw_body
    expected = "v1=" + hmac.new(secret.encode(), material, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected.encode(), got.encode())
Test vector
secret:    whsec_demo_only_not_a_real_secret
timestamp: 1789000000
body:      {"event":"booking.created","deliveryId":"0f7b1d2c-9a44-4e13-8b56-2c9f0e5a7d31","sentAt":"2026-09-10T00:26:40.480Z","assistantId":"demo-salon","booking":{"service":"თმის შეჭრა","date":"2026-09-14","time":"14:30","timezone":"Asia/Tbilisi","durationMinutes":45,"staff":"ნინო","staffRequested":null,"channel":"telegram","status":"confirmed","calendarEventId":"6k3q1m0p9r7s2t4u","rejectedReason":null,"createdAt":"2026-09-10T00:26:39.000Z"}}
signature: v1=66d7ff203a2cb9f512441e6fbbce1f43d8724346f421ff786cacd925ce067d73
  • body is the body example above, compact, on one line. The headers example contains the signature of exactly this body.
  • The vector will not pass the time window: the timestamp is old. To test, set your clock close to the timestamp or switch off the window check.
  • Changing a single character of body or timestamp must make the comparison return false.

Key

TopicRule
Formatwhsec_…; created when the URL is first saved.
DisplayOnce. We store it encrypted and it will not be shown again; the dashboard shows the last four characters.
LostNew secret in the dashboard. The old one stops verifying immediately, so put the new one in place at the same moment.
Changing the URLDoes not change the secret.

Endpoint

RequestRule
SchemeOnly https://. Over http the signature can be read in transit and replayed within the window.
NetworkPublicly resolvable only. Loopback, link-local (including 169.254.169.254) and private ranges are refused. Checked when saved and before every delivery.
Credentials in the URLhttps://user:pass@… is refused. Put a token in the path or a query parameter, or rely on the signature.
RedirectsNot followed: 3xx is a failed delivery. Give the final URL.
LengthAt most 500 characters.

Receiving side

  • Return 2xx quickly. Put the work in a queue; do not do it inside the request.
  • Be idempotent on x-botai-delivery. Order of arrival is not guaranteed: an event may arrive after an earlier one.
  • Skip an unknown event and still return 2xx.
  • Do not stop reading the calendar periodically.

Have a question, or does something on this page not match the code? Contact us and tell us which endpoint it was.