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.
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.
Create a new key and revoke the old one. Revocation takes effect from the very next request.
CORS
None, on purpose: the key can write, so it is used only from a server, never from a browser.
Refusal
401 unauthorized: the key is missing, unknown, malformed or revoked.
Which key
Where 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.
Scope
Level
What it opens (after /api/v1)
Key without a list
knowledge:read
Assistant level
GET /knowledge
Closed
knowledge:write
Assistant level
POST / PATCH /knowledge
Closed
conversations:read
Assistant level
GET /conversations, /conversations/{channel}/{userId}, /contacts, /handoffs
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
Level
The key reaches
Assistant in the request
Another 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:
Field
What it says
returned
How many rows are in this response.
truncated
false = that is everything. true = more exists than you received.
limit
The page size actually used, after clamping.
To request the rest, where that is possible, the response has one more field:
Field
Where
What to do
nextOffset
/conversations, /contacts
Repeat with ?offset= set to this number.
nextFrom
/bookings, /bookings/busy
Repeat with ?from= set to this date. Rows for that date will come again; filter duplicates by id.
nextBefore
/handoffs
Repeat 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.
Limit
Value
?limit=
Maximum 500, default 100
Transcript of one conversation
Up to 900
total
Only 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
Section
Type
Entry fields and limits
POST
PATCH
description
string
—
Replaced
Replaced
services
array
At 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 full
Matched by name, ignoring case and leading or trailing whitespace: a match is updated, the rest is added
faq
array
At most 300. question and answer are both required.
Replaced in full
Matched by question, by the same rule
rules
array of string
At most 100. An empty string is not allowed.
Replaced in full
Added if not already present; nothing is deleted
documents
array
At 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 deleted
Updated 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.
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
Field
Type
Note
clientId
string
The key's assistant.
description
string
An empty string if nothing has been written.
services
array
name, description, price, priceUnit, durationMinutes: whatever has been written.
faq
array
question, answer.
rules
array of string
documents
array
Only those written via the API: id, label, text, charCount, updatedAt (ISO 8601). Files uploaded in the dashboard are not returned.
Errors
Status
error
When
404
assistant_not_found
The key's assistant no longer exists.
POST/api/v1/knowledgeknowledge: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())
Above a section's limit (200 / 20 / 300 / 100 / 10), or the assistant's knowledge sources would exceed 10 in total.
413
document_too_long
A document's text is longer than 8 000 characters.
502
write_failed
Part 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/knowledgeknowledge: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())
channel, userId, lastMessage, lastRole (user or assistant), lastTimestamp (ISO 8601), messageCount.
returned, limit, offset
integer
How many came back; the page size used; where it started.
total
integer
Length of the list. With countsComplete: false, a lower bound.
truncated
boolean
true: more exists, or countsComplete: false.
nextOffset
integer
Only if a next page exists: repeat with ?offset= set to this number.
countsComplete
boolean
false: 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.
integer, number | null, string | null, ISO 8601 | null
Reviews; the rating and comment are from the latest review, not the best one.
manualStage
string | null
new, qualified, booked, won, lost: the CRM stage set by a person or by the system.
manualStageSource
string | null
manual: set by a person; system: set automatically because of a booking.
manualNote, manualUpdatedAt
string | null, ISO 8601 | null
The note and when it was written.
Errors
Status
error
When
500
contacts_unreadable
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.
GET/api/v1/handoffsconversations:read
Where a customer asked for a person. Newest to oldest.
Parameters
Parameter
Type
Required
Default · limit
Note
limit
integer
No
100 · max 500
A malformed value falls back to the default; not an error.
open
string
No
—
true: only unanswered ones (acknowledgedAt: null). Any other value: all.
null: the customer is still waiting. “A notification was sent” and “someone took it” are two different facts.
returned, limit
integer
truncated
boolean
true: the oldest ones did not fit.
nextBefore
string
Only with truncated: true: repeat with ?before= set to this time.
Errors
Status
error
When
400
invalid_request
before 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/bookingsbookings:read
List of bookings by date and time, in the order of the day.
Parameters
Parameter
Type
Required
Default · limit
Note
from
string
No
—
YYYY-MM-DD, inclusive.
to
string
No
—
YYYY-MM-DD, inclusive.
limit
integer
No
100 · max 500
A malformed value falls back to the default; not an error.
In the shop's own words; not null means the booking was declined and is also cancelled: true.
attended
boolean | null
true: a person marked “attended”; false: “did not attend”; null: nobody recorded anything.
createdAt
string
ISO 8601.
Errors
Status
error
When
400
invalid_request
from 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/busybookings: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.
date, time, service, staffName (string | null), pendingApproval (boolean). Active bookings: not cancelled and not declined; those awaiting confirmation are included.
returned, limit
integer
limit is always 500.
truncated
boolean
true: the window holds more than 500 bookings.
nextFrom
string
Only with truncated: true.
source
string
bookings: our table only.
hours
object
The business's working week: timeZone (always Asia/Tbilisi), mustFinishInside and week. It may be absent altogether; see below.
hours.week
object
Seven keys: mon…sun. Each has a state: open (then opens and closes, HH:MM), closed, or unknown.
hours.mustFinishInside
boolean
Always true: a booking must finish within working hours, not just start within them.
Errors
Status
error
When
400
invalid_request
from 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/bookingsbookings:write
New booking. The assistant's own setting “bookings need my confirmation” applies to this request as well.
Body fields
Parameter
Type
Required
Default · limit
Note
userId
string
Yes
—
The customer's identifier in your system; it links the booking to the contact and the conversation.
true: 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
Status
error
When
400
invalid_body
The body is not an object.
400
invalid_booking
userId, service, date or time is missing or malformed; field says which.
404
assistant_not_found
The key's assistant no longer exists.
409
slot_taken
The time is already taken, in our diary or in the calendar. Nothing was booked; choose another time.
409
closed_day
The 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.
409
outside_hours
The 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).
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
Parameter
Type
Required
Default · limit
Note
bookingId
integer
Yes (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"
id, channel, userId, service, date, time, staffName.
Errors
Status
error
When
400
invalid_request
bookingId is not a positive integer.
404
booking_not_found
No such booking belongs to this assistant. Another assistant's id and one that does not exist get the same response.
409
ambiguous_booking
The 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.
clientId, name, active (boolean), language, tone, requireBookingApproval (boolean).
returned
integer
How many assistants were returned.
total
integer
How many the account record names.
truncated
boolean
true: 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/assistantsassistants: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
Parameter
Type
Required
Default · limit
Note
clientId
string
Yes
—
Lowercase Latin letters, digits and single hyphens; uppercase letters are converted to lowercase. Permanent: it cannot be changed later.
name
string
Yes
—
The name this branch introduces itself by.
active
boolean
No
false
Must be true to create it switched on; any other value means switched off.
templateName
string
No
—
The name of the starter template; if omitted, the default template is used. An unknown name returns create_failed.
The number of assistants agreed for the account; before an agreement, the package minimum; null means unlimited.
botCount
integer
Assistants on the account, including the new one.
Errors
Status
error
When
400
invalid_client_id
clientId is missing or not in an allowed form.
400
invalid_request
name is missing.
400
create_failed
The assistant could not be created: the clientId is taken by another account, or no such templateName exists. The response deliberately does not say which.
403
bot_limit_reached
Above the assistant limit. The response contains plan, botLimit, botCount.
409
client_id_taken
This account already has an assistant with that clientId.
502
attach_failed
The 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.
After the change: clientId, name, active, language, tone, requireBookingApproval.
Errors
Status
error
When
400
unsupported_field
The 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.
400
nothing_to_write
The body did not name any field.
400
invalid_request
A field's value has the wrong type or is empty; field says which.
404
assistant_not_found
No such assistant belongs to this account.
409
write_conflict
The 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/usageusage:read
Messages and tokens per assistant.
Parameters
Parameter
Type
Required
Default · limit
Note
from
string
No
First day of the current month
YYYY-MM-DD, inclusive.
to
string
No
Today
YYYY-MM-DD, inclusive. One request covers at most 92 days.
What the replies cost us. The sum over measured calls.
unmeasuredCalls
integer
The part of calls whose tokens we could not measure. These are not free calls.
byModel[]
array
The same figures per model: provider, model, calls, the four token fields, unmeasuredCalls. Empty if there were no calls.
Errors
Status
error
When
400
invalid_request
from or to is not YYYY-MM-DD, or from is later than to.
400
window_too_long
The window is longer than 92 days. The response contains maxDays.
404
assistant_not_found
clientId does not belong to this account.
413
window_too_large
The 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.
Condition
Value
Base URL
https://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.
Scope
products: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.
Body
JSON, at most 1 000 000 bytes (413 body_too_large).
Limits
Products per request: 500; variants per product: 100, per request: 5 000.
Rate
60 requests per minute per assistant; 120 per IP address.
Money
Whole tetri: 18999 = 189.99 ₾.
Body fields
Parameter
Type
Required
Default · limit
Note
products
array
Yes
1–500
Products. An empty array returns 400 empty_catalogue.
sourceId
integer
No
—
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
Field
Type
Required
Limit
Note
id
string | integer
Yes
—
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.
name
string
Yes
500 characters
Required on PATCH as well.
description
string
No
20 000 characters
category
string
No
500 characters
imageUrl
string
No
2 000 characters
Synonym: image.
status
string
No
—
active (default), hidden, archived. A product's status is derived from its variants: one active variant keeps the product active.
variants
array
No
100
If the product has a single form, omit this: sku, price, stock and attributes are written on the product itself.
products[].variants[] fields
Field
Type
Required
Limit
Note
id
string | integer
Conditional
—
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.
sku
string
No
200 characters
priceTetri
integer | string | null
No
2 147 483 647
Price; rules below. Synonym: price.
salePriceTetri
integer | string | null
No
2 147 483 647
Sale price; counted only together with the regular price. Synonym: salePrice.
stock
integer | string | null
No
2 147 483 647
Stock; rules below.
status
string
No
—
Same as on the product.
attributes
object
No
20 keys
Value: a string or a number: {"Size": "42", "Color": "Black"}.
Price and stock
Value
How it is read
Price, JSON number
18999 = 18999 tetri. A fraction (189.99) returns 400 invalid_product, and the error says 18999. A negative value returns 400.
Price, JSON string
Read 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/productsproducts: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.
Archived products: those that were in this source and were not named in the request.
variants
integer
Variants written.
warnings[]
array
code, message (in Georgian), index (the product's position, if applicable).
Errors
Status
error
When
400
invalid_body
The body is not an object; products is not an array; sourceId is not a positive integer (field).
400
empty_catalogue
products is empty.
400
invalid_product
A 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.
400
duplicate_product_id, duplicate_variant_id
The same id twice in one request (within one product, a variant's).
400
too_many_variants
More than 100 variants on one product.
404
source_not_found
No such source belongs to this assistant.
413
too_many_products
More than 500 products in one request.
413
too_many_variants
More than 5 000 variants in one request.
413
body_too_large
The body is larger than 1 000 000 bytes; the response contains maxBytes.
502
write_failed
Part was written and part was not. The response shows what was written (created, updated, variants); nothing was archived.
An empty POSTdoes 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/productsproducts:write
Partial update: only the named products are updated or added; nothing is archived. Body and errors are the same as for POST.
The field is not in the PATCH response: PATCH archives nothing.
Everything else
Same 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.
Condition
Value
Endpoint
POST 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.
Scope
payments: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.
Money
Whole tetri: 18999 = 189.99 ₾.
Currency
Whatever is in the catalog. Card payments are available in GEL, USD, EUR, GBP; nothing is converted anywhere.
Rate
30 sales per minute per assistant; 120 requests per minute per IP address.
Body fields
Field
Type
Required
Limit
Note
variantId
string | integer
Yes
128 characters
The variant id in the catalog: the Products API's id (or sku).
productId
string | integer
No
128 characters
Only narrows: needed when one variantId is on two products in this shop.
quantity
integer
No
1–1000 · default 1
method
string
No
online (default), cod
cod: cash on delivery.
orderRef
string
No
A-Za-z0-9_-, 4–64 characters
Order number and idempotency key. If you omit it, we will assign one.
customer
object
No
name 120, phone 40, email 160
The buyer. Long values are truncated.
description
string
No
200 characters
Sent to Quickpay for card payments. Long values are truncated.
note
string
No
500 characters
Stored on the order. Long values are truncated.
amountTetri
integer
No
—
For checking only: must match the catalog total.
currency
string
No
—
For checking only: must match the catalog currency.
POST/api/v1/paymentspayments: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.
One field is malformed; field says which. amountTetri is whole tetri; 149.99 is an error here.
403
addon_required
The assistant does not have the products add-on.
403
scope_required
The key does not have payments:write; scope names it.
404
variant_not_found
No such variant is in this assistant's catalog. Another assistant's variant gets the same response.
409
variant_ambiguous
Two variants with the same id were found in this shop. Specify productId.
409
variant_not_for_sale, variant_unpriced
The variant has been taken off sale, or it has no price.
409
amount_mismatch, currency_mismatch
The body named an amount or a currency that did not match the catalog. Nothing was created.
409
amount_not_chargeable
The total (price × quantity) is zero or exceeds 2 147 483 647 tetri.
409
currency_not_chargeable
A card payment cannot be created in this currency. chargeableIn lists the ones it can be created in.
409
cod_disabled
The 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).
409
payment_account_missing, payment_key_unreadable
Quickpay has not been connected yet, or the stored key can no longer be read. The owner needs to fix this.
409
order_ref_taken
A different sale is already open under this number. Choose a new number.
400, 404, 409, 429, 502
payment_provider
Quickpay refused or is not responding. failure names the reason, message is in Georgian; currency appears if the refusal concerns the currency.
502
order_not_saved
The 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.
Status
error
What happened
400
invalid_body
The body is not an object, or a section has the wrong type.
One 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.
400
duplicate_document_id
The same id came twice in one request.
400
invalid_booking
A required booking field is missing or malformed.
400
invalid_request
A parameter, path segment or required field is malformed: a booking id that is not a positive integer; a name missing from POST /assistants.
400
invalid_product
Products API: a product or variant is malformed. index and field say which.
400
empty_catalogue
Products API: products is empty. An empty POSTdoes not clear the catalog; this is almost always an error in your export. Send what you want to take off sale with "status": "archived".
400
duplicate_product_id / duplicate_variant_id
Products API: the same id twice in one request.
400
invalid_client_id
clientId is not in an allowed form.
400
create_failed
The assistant could not be created: the clientId is taken by another account, or no such templateName exists. The response does not say which.
400
unsupported_field
PATCH /assistants was sent a field it does not change.
400
window_too_long
The usage window is longer than 92 days.
401
unauthorized
The key is missing, unknown, malformed or revoked.
403
plan_required
The account is not on the Corporate package.
403
scope_required
The key does not have the scope this endpoint requires. scope names it.
403
addon_required
The assistant does not have the products add-on.
403
no_account
The key's assistant has no owning account, so the account-level endpoints are unavailable to it.
403
bot_limit_reached
Above the account's assistant limit.
404
assistant_not_found
No such assistant belongs to this account.
404
booking_not_found
No such booking belongs to this assistant.
404
source_not_found
No such catalog source belongs to this assistant.
409
write_conflict
POST / 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.
409
client_id_taken
POST /assistants: this account already has an assistant with that clientId.
409
slot_taken
Someone else took the time between the check and the write. Nothing was booked.
409
closed_day
The 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.
409
outside_hours
The 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.
409
ambiguous_booking
The cancellation would affect more than one booking. Nothing was cancelled.
A knowledge document is longer than 8 000 characters.
413
too_many_products
Products API: more than 500 products in one request.
400 / 413
too_many_variants
Products API: above the variant limit per product or per request.
413
window_too_large
The window contains more calls than one request can read.
429
rate_limited
Too many requests per minute for this assistant. retryAfterMs says how long to wait.
429
too_many_attempts
Too many requests per minute from this IP address, counted before we look at the key.
500
internal_error
Our fault. Try again.
500
contacts_unreadable
GET /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.
502
write_failed
Part 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.
502
attach_failed
The 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.
Limit
Corporate API
Products API
Body
512 000 bytes
1 000 000 bytes
Requests per minute, per assistant
120
60
Requests per minute, per IP address
120
120
List page
500 rows
500 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 error
Retry?
Action
429rate_limited, too_many_attempts
Yes
Wait the retryAfterMs milliseconds from the response body and repeat the same request.
500internal_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.
500contacts_unreadable
Later
A fault on our side. Do not treat the response as an empty list. If it persists, write to us.
502write_failed
Yes, unchanged
The write partly succeeded; nothing was deleted. The response says what was written; the request is idempotent.
502order_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.
502attach_failed
No
The assistant was created and could not be attached to the account. A retry will return create_failed. Write to us.
409write_conflict
After a read
Nothing was written. Call GET /knowledge or GET /assistants and send again.
409slot_taken
No, not as is
Nothing was booked. Choose another time.
409closed_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.
409outside_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.
409ambiguous_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.
Date
Change
2026-09-19
v1: 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
Field
Type
Note
summary
string
<service> — <customer name>. Without a name: უცნობი მომხმარებელი (“unknown customer”).
description
string
Lines: ტელეფონი: … (phone; - if there is no phone), არხი: … (channel), მოთხოვნილი დრო: YYYY-MM-DD HH:MM (requested time); when a specialist was requested, also მოთხოვნილი სპეციალისტი: … (requested specialist).
start, end
object
dateTime is in UTC (Z), timeZone is Asia/Tbilisi. end = start + the service duration; without a duration, 60 minutes.
transparency
string
Always opaque. A transparent entry does not appear in the freebusy response at all, neither as busy nor as free.
extendedProperties.private
object
Four keys; see below.
extendedProperties.private
Key
Value
Purpose
botaiSource
botai.ge/booking
A constant marker. Write your filter on this.
botaiClientId
The assistant's identifier, e.g. demo-salon
Several assistants can write to one calendar; this is how you tell them apart.
botaiChannel
telegram, website, whatsapp, …
The same as the channel line of description.
botaiRequested
The time the customer requested, as text, e.g. 2026-09-14 14:30
The 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
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
Topic
Rule
Where to switch it on
Dashboard: Assistant settings → Other → Booking webhook.
Package
Checked on every delivery, not only when the URL is saved: for an account that moves down to Start, delivery stops.
Request
POST, content-type: application/json; charset=utf-8.
Attempts
One, with a 5-second timeout. There is no retry and no queue.
Your response
We do not read the body. Any 2xx is a success; 3xx is a failure, and we do not follow redirects.
Failure
The 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
event
When
booking.status
booking.created
A booking was written. Never for a time that is already taken.
confirmed; pending if the assistant holds the booking for confirmation
booking.approved
The shop confirmed the request. From this moment the time is a commitment.
confirmed
booking.rejected
The shop declined the request. Release the time.
rejected
booking.cancelled
The booking was cancelled, by the customer in the assistant or through our API.
cancelled
webhook.test
Press 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.
The assistant's identifier, the one in the dashboard URL. Never the account's.
booking.service
string
Exactly as the shop wrote it in its list of services.
booking.date
string
YYYY-MM-DD, in booking.timezone, not in UTC.
booking.time
string
HH:MM, 24-hour, in booking.timezone.
booking.timezone
string
Currently always Asia/Tbilisi. Read it; do not assume it.
booking.durationMinutes
number
The service duration; 60 if not specified. The same as on the Google Calendar entry.
booking.staff
string | null
The specialist the booking is with. null: the business has no list of specialists.
booking.staffRequested
string | null
The 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.channel
string
website, telegram, whatsapp, instagram, messenger. Our channel, not the customer.
booking.status
string
confirmed | pending | cancelled | rejected. The status after this event.
booking.calendarEventId
string | null
The id of the Google Calendar entry (not of the calendar). null: no entry exists, e.g. for a booking awaiting confirmation.
booking.rejectedReason
string | null
The shop's own words, on booking.rejected.
booking.createdAt
string
ISO 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
Topic
Rule
Signed material
v1:<timestamp>:<raw body>, literally, with the colons. <timestamp> is the value of x-botai-timestamp.
Algorithm
HMAC-SHA256, with the key whsec_….
Header
x-botai-signature: v1=<hex>.
Time window
x-botai-timestamp and your clock must differ by no more than 300 seconds, in either direction.
Comparison
In 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())
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
Topic
Rule
Format
whsec_…; created when the URL is first saved.
Display
Once. We store it encrypted and it will not be shown again; the dashboard shows the last four characters.
Lost
New secret in the dashboard. The old one stops verifying immediately, so put the new one in place at the same moment.
Changing the URL
Does not change the secret.
Endpoint
Request
Rule
Scheme
Only https://. Over http the signature can be read in transit and replayed within the window.
Network
Publicly 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 URL
https://user:pass@… is refused. Put a token in the path or a query parameter, or rely on the signature.
Redirects
Not followed: 3xx is a failed delivery. Give the final URL.
Length
At 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.