Developers
Venue tools (beta)
Read and change a venue's set-up, bookings, customers and sales with the same tools BookingNinja's own AI assistant uses.
BookingNinja has a set of tools for reading and changing a venue: its sessions, prices, opening times, bookings, customers, gift cards, reports and more. Our own AI assistant uses them. Your app can call them too, on the venue that installed it.
This part of the API is in beta. The tools are BookingNinja's own, exposed as they are:
- Their names, arguments and results can change without a new contract version.
- They use BookingNinja's own numeric ids (a session's id, a booking's id), not the refs the rest of this API uses. "Refs and ids" below shows how to turn one into the other.
- Each tool describes itself, in words written for an AI assistant. Read the description before you call a tool for the first time.
If you need something stable, use the rest of the API. Use the tools for what it does not cover yet.
Scopes
Each tool's reads and writes are unlocked by a scope the venue grants when it connects your app. Ask only for the scopes you need: the venue sees each one on the consent screen.
| Scope | What it unlocks |
|---|---|
venue:read |
Reading how the venue is set up: sessions, guest types, prices, opening times, closures, tables, add-ons, products, settings, its website and booking page |
venue:write |
Changing how the venue is set up |
bookings:read_all |
Searching every booking, a booking's full details, availability checks, quiet times and the hire run sheet |
bookings:write |
Setting a booking's status |
customers:read |
A customer's profile, bookings, logins, memberships and loyalty |
customers:write |
Changing a customer, their flags and notes, and merging customers |
sales:read |
Payment activity, gift card codes and membership members (each also needs customers:read) |
sales:write |
Issuing, crediting, spending and voiding gift card codes, and inviting and removing members (each also needs customers:read) |
reports:read |
Analytics, the weather forecast and its effect, improvement signals, the venue overview and notification activity (notification activity also needs customers:read) |
marketing:write |
Reading and saving draft marketing emails and paused automations. Nothing is ever sent. |
websites:write |
Changing the venue's website and custom booking page |
A write that only checks its arguments (validate) needs the write scope.
Some tools return guests' names, email addresses or phone numbers, so every one of their operations also needs customers:read: payment activity (it can be filtered by a guest's email), gift card codes (buyers and recipients), membership members, and notification activity (who each message went to). GET /api/v1/apps/tools shows these extra scopes as scope.requires, and lists such a tool only when all of them are granted.
Finding the tools
GET /api/v1/apps/tools lists the tools your installation may call, with the operations its scopes allow. A tool, or an operation, that needs a scope the venue did not grant is left out, as is a tool whose scope.requires are not all granted. So is one the venue's plan does not include.
{
"tools": [
{
"name": "manage-closures-tool",
"description": "Manage store closures (blocked days)...",
"scope": { "read": "venue:read", "write": "venue:write" },
"operations": { "list": "read", "load": "read", "validate": "validate", "save": "write", "delete": "write" },
"input_schema": {
"type": "object",
"properties": {
"action": { "type": "string", "enum": ["list", "load", "validate", "save", "delete"] },
"closure_id": { "type": "integer" },
"form": { "type": "object" }
},
"required": ["action"]
}
}
]
}
operationsmaps each operation toread,writeorvalidate.input_schemais the JSON Schema of the tool's arguments. Most tools take anactionargument that picks the operation; its list holds only the operations you may call. A tool without one has a single operation.- The venue is never an argument. BookingNinja fills it in for every call.
Calling a tool
POST /api/v1/apps/tools/{name} with the tool's arguments under arguments:
{
"arguments": {
"action": "save",
"form": { "blocked_date": "2026-12-24", "name": "Christmas Eve tournament", "blocks_overlap": false }
}
}
The reply is the tool's own result, under result:
{
"result": {
"message": "Closure created successfully.",
"closure": { "closure_id": 5433, "form_state": { "id": 5433, "blocked_date": "2026-12-24", "name": "Christmas Eve tournament" } }
}
}
A venue id in the arguments is ignored. Your app only ever reaches the venue that installed it: a session, booking, customer or gift card of any other venue is refused, even when you know its id.
When a call is refused
Refusals use the usual error shape, with a code and a message:
| Code | Status | When |
|---|---|---|
insufficient_scope |
403 | The operation needs a scope the venue did not grant, including a scope the tool requires. |
not_found |
404 | No such tool, or one apps cannot use, or an operation apps cannot use. |
invalid_request |
422 | The tool did not accept the arguments. fields says which, and why. |
tool_failed |
409 | The tool ran and reported a problem, such as a record that is not at this venue. |
rate_limited |
429 | Too many tool calls. Wait for the seconds in the Retry-After header. |
{
"error": {
"code": "invalid_request",
"message": "The tool did not accept these arguments.",
"fields": { "blocked_date": ["The blocked date field is required."] }
}
}
Refs and ids
Events and the booking API name records by ref (bkg_…, cus_…). The tools take numeric ids. POST /api/v1/apps/refs/resolve turns up to 100 refs into ids:
{
"refs": ["bkg_9d3f6e1a", "cus_4k2m8p1q"]
}
{
"refs": {
"bkg_9d3f6e1a": { "type": "booking", "id": 812044 },
"cus_4k2m8p1q": { "type": "customer", "id": 30117 }
}
}
A ref is resolved only when your installation may read its kind of record. Bookings need bookings:read or bookings:read_all. Customers and feedback need customers:read. Gift cards, memberships, orders and payments need sales:read. Any other ref, or one that is not your installation's, is left out of the answer.
The ids are BookingNinja's own and are the same for every app. Keep them inside your app: show people the record's name, not its id.
Changes your app makes
Every change a tool makes is recorded in the venue's Activity Log under your app's name, with the tool it came through. The venue can see it, and can roll most changes back from there. A booking whose status your app sets shows your app's name in the booking's history.
Writes are not made safe to retry for you. A retried write runs again, unless the tool takes its own idempotency key, as setting a booking's status does. Before you retry a write that timed out, read the record back to see whether it went through.
Some tools email guests: inviting a member, resending a gift card, a booking status change with a message. Make sure the venue has asked for it before your app does any of these.
What apps cannot do
- Anything about the venue owner's account: their other venues, billing, their team or the Activity Log itself.
- Change a customer's email address. It would move the guest's login.
- Read website enquiries, change the shared website themes and library, or add a website domain.
- Confirm a hire was delivered or returned, or refund a deposit. Staff do these in the admin.
Limits
Each installation may make 60 tool calls a minute, on top of the API's limit of 300 requests a minute. Some tools run heavy reports or availability checks: cache what you read, and avoid calling the same read again and again.