Bolrach Bots API reference

Scopes

Reads (templates, directory, bot cards) need bots:read. Chatting and polling a conversation need bots:run. A key with bots:* holds both.

Endpoints

GET /v1/bots/templates

The template gallery: key, name, category and description per template. GET /v1/bots/templates/{key} returns one template with its full flow definition.

curl "https://api.bolrach.io/v1/bots/templates" \
  -H "Authorization: Bearer bt_your_key_here"

GET /v1/bots/directory

All public, live bots, optionally filtered with ?category=. Each entry carries the bot's id and slug, which the card and chat endpoints take.

curl "https://api.bolrach.io/v1/bots/directory" \
  -H "Authorization: Bearer bt_your_key_here"

GET /v1/bots/{slug}

A single bot's public card: name, handle, description, category. 404 when the bot is not public.

curl "https://api.bolrach.io/v1/bots/my-support-bot" \
  -H "Authorization: Bearer bt_your_key_here"

POST /v1/bots/{botId}/chat

Send one end-user message and get the bot's replies for that turn. The first call returns a visitorId; pass it back as sessionKey on later calls so the conversation continues instead of restarting.

Field	Type	Description
`text`	string, required	The end user's message (up to 4,000 characters).
`sessionKey`	string, optional	Continue an existing conversation.
`visitorId`	string, optional	Your own stable id for the end user.

curl -X POST "https://api.bolrach.io/v1/bots/BOT_ID/chat" \
  -H "Authorization: Bearer bt_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"text": "What are your opening hours?"}'

Response

{
  "status": "open",
  "sessionId": "3f2c…",
  "visitorId": "web_a1b2c3d4e5f6",
  "replies": ["We are open 9am-6pm WAT, Monday to Saturday."]
}

GET /v1/bots/{botId}/messages

Poll a conversation for new messages with ?sessionKey= (required) and ?after= (ISO timestamp). This is how human agent replies and delayed bot messages reach your end user. Scoped to that session only.

curl "https://api.bolrach.io/v1/bots/BOT_ID/messages?sessionKey=web_a1b2c3d4e5f6&after=2026-07-14T12:00:00Z" \
  -H "Authorization: Bearer bt_your_key_here"

Limits and errors

Plan rate limits are shared across the platform (plans table). Chatting with a bot that is offline returns { "status": "offline", "replies": [] }; a bot that is not public at all is a 404 in the standard error envelope.

Changelog

Date	Change
2026-07-14	v1 launch: templates, directory, public cards, web-chat and message polling.