Local API

Control a running Q-Booth from your own app over HTTP, on the same PC or your local network: start events, capture, print, show QR and read the booth's state.

8 min read Updated 26 Oct 2026

The Local API lets your own app control a running Q-Booth over HTTP — from the same PC or another device on your local network. Start an event, take the guest through the session, print, show the QR code, and read where the booth is at any moment.

Note

This page documents API version 1. A booth reports the version it runs in status → app.apiVersion. The API works on the local network only — it is not reachable over the internet.

Getting started

Open the App Settings window, go to Advanced → Local API and turn on Turn on Local API. (If Advanced is missing, turn on Show all settings first.)
Leave Password empty to have one made for you, or type your own. The default Port is 8730.
To call it from another device, turn on Allow other devices on the network. Windows may ask once to let Q-Booth through the firewall — allow it.
Click Save Settings, then Open test page. The test page has a button for every command, and the booth's own copy of this reference.

The address is http://<booth-pc>:8730 (http://localhost:8730 on the booth PC itself). Every command lives under /api/v1/.

curl http://localhost:8730/api/v1/status -H "Authorization: Bearer YOUR_PASSWORD"

Password

Every call except GET /api/v1/commands needs the password. Send it in any one of these ways:

Authorization: Bearer <password> (recommended)
X-QBooth-Key: <password>
?key=<password> on the URL, for tools that can only open a link

A wrong or missing password returns 401. Ten wrong tries in a minute from one address block it for a minute (429). The password is the operator's key — anyone who has it can control the booth, so keep it private.

Replies

Reads use GET and answer 200 with the data:

{ "ok": true, "data": { ... } }

Actions use POST with a JSON body (or the query string). GET works too, for trigger tools that can only send GET. An accepted action answers 202 as soon as the booth has it — it does not wait for the photo, the print or the guest:

{ "ok": true, "accepted": "camera/capture" }

A refused call says why, with a code you can act on:

{ "ok": false, "error": { "code": "wrong_page", "message": "The booth is on the welcome page. This needs the Camera page." } }

The API never queues a command for later. If the booth is not in a state that allows it, it refuses straight away.

Status

GET /api/v1/status tells you where the booth is. Poll it to follow what happens after an action — every 300 to 1000 ms is fine. If the call can't connect at all, Q-Booth is not running (or the Local API is off).

{
  "app":     { "name": "QBooth", "version": "5.9.1.0", "apiVersion": "1" },
  "event":   { "id": "1781706869_H5A4", "name": "Wedding" },
  "page":    "camera",
  "session": { "active": true, "templateId": "…", "templateName": "Strip 3" },
  "camera":  { "phase": "review", "shot": 3, "shots": 3, "captured": 3, "feed": "live", "retakesLeft": 1 },
  "result":  null,
  "busy":    { "dialog": false, "processing": false },
  "available": ["camera/retake", "camera/process", "session/end", "event/stop"]
}

Field	Meaning
`event`	The running event, or `null` when the booth is not running one.
`page`	`none`, `welcome`, `survey`, `categoryPicker`, `templatePicker`, `input`, `camera` or `result`.
`session`	`active` once the guest has started (and paid, if the event charges), and the template picked so far.
`camera`	Only on the Camera page. `phase` is `liveIdle`, `counting`, `recording`, `capturing`, `reveal`, `shotDelay` or `review`. `retakesLeft` is `null` when unlimited.
`result`	Only on the Result page: which result is on screen, of how many.
`busy`	A dialog on screen (payment, PIN, QR, a notice) or a photo being processed. Actions are refused while either is true.
`available`	The actions the booth would accept right now — worked out by the same checks the actions run, so you can use it to enable or grey out your own buttons.

A guest, step by step

A typical run, each step waiting in status for the page or phase shown:

Call	Then wait for
`POST event/start {"id": "…"}`	`page: welcome`
`POST session/start`	`page: templatePicker` (or `categoryPicker` / `survey`, depending on the event)
`POST template/select {"index": 1}`	`page: camera`, `camera.phase: liveIdle`, `camera.feed: live`
`POST camera/capture`	`camera.phase: review`
`POST camera/process`	`page: result`
`POST result/print`	—
`POST session/end`	`page: welcome`

Tip

The API follows the same rules a guest meets. A survey, a form, a payment or a PIN shows on the booth screen exactly as it would after a tap, and the API does not answer them for the guest. Print limits and the print PIN apply too.

Commands

All paths start with /api/v1/. index is 1-based, in the order the guest sees the cards (top-left gallery first). Send id or index, not both; if both are sent, id is used.

Command	Valid when	What it does
`GET status`	Always	Where the booth is, and which actions it would accept. See Status.
`GET commands`	Always, no password	The command list with the API version — what the test page is built from.
`GET events`	Always	Every event on the PC: `id`, `name`, `archived`, `templateCount`, `running`.
`POST event/start` `{"id": "…"}`	No event running, no dialog open, the event editor not open on another event or with unsaved changes	Starts the event, like its Launch button. A template warning, if any, shows on the booth screen first.
`POST event/stop`	An event is running, no dialog, not processing	Ends the booth session and returns to the app. The exit PIN is not asked.
`GET templates` `?eventId=…` (optional)	Always with `eventId`; without it, an event is running	The templates a guest can pick. With `eventId`: any saved event, running or not. Without it: the running event, and on its Template Picker (or a Welcome page with a template gallery) `onScreen` and `index` say which cards it shows.
`GET categories` `?eventId=…` (optional)	Always with `eventId`; without it, an event is running	The event's enabled categories, by the same `eventId` rule. On the running event's Category Picker, `onScreen` and `index` say which cards it shows.
`POST session/start`	Welcome page	The Start button. A Start PIN or payment, if the event has one, shows on the booth screen.
`POST session/end`	Any page after Welcome	The Home button: closes the guest's session and goes back to Welcome.
`POST category/select` `{"id": "…"}` or `{"index": n}`	Category Picker page	Picks a category like a tap on its card, then opens the Template Picker.
`POST template/select` `{"id": "…"}` or `{"index": n}`	Welcome page (any template in the event), or Template Picker page with the template shown on it	On the Template Picker: picks a template like a tap on its card and confirms it (a Next button is pressed for you). On Welcome: starts the session with that template, like tapping a card in a Welcome template gallery. The Start PIN or payment shows on the booth screen first, then the picker pages are skipped. On Welcome, `index` counts the Welcome gallery's cards; without a gallery there, pick by `id`.
`POST camera/capture`	Camera page, live view idle (or waiting between shots), camera live	The Capture button: starts the countdown and the shots. Between shots of a manual multi-shot, takes the next one.
`POST camera/retake`	Camera page, reviewing the shots, retakes left	The Retake button for the shot on screen, following that button's after-tap setting.
`POST camera/process`	Camera page, reviewing the shots	The Process button: sends the shots to the template.
`POST result/print`	Result page, a printer set up, printing allowed	The Print button for the result on screen. Print PIN, limits and the after-print lock apply; with extra prints on sale it opens the purchase.
`POST result/qr` `{"type": "web"}` or `"local"`	Result page, that QR set up in Settings	Shows the QR code for the result on screen, like the QR Web / QR Local button. Default `web`.

Errors

HTTP	Code	Meaning
400	`bad_request`	A parameter is missing or not valid.
401	`unauthorized`	No password, or the wrong one.
404	`not_found`	Unknown path or command.
404	`unknown_event`, `unknown_template`, `unknown_category`	No event, template or category with that id or index.
405	`method_not_allowed`	POST sent to a read.
409	`no_event`	The command needs a running event.
409	`event_running`	An event is already running.
409	`editor_open`	The event editor is open on the booth PC (another event, or unsaved changes).
409	`no_templates`	The event has no templates.
409	`wrong_page`	Not valid on the page the booth is showing.
409	`wrong_phase`	Camera page, but not at a point where this is possible.
409	`dialog_open`	A dialog is open on the booth screen.
409	`processing`	A photo is being processed.
409	`busy`	The booth is still finishing the last action. Try again in a moment.
409	`not_allowed`	A rule blocks it: no retakes left, print limit reached, print lock after the last print.
409	`not_configured`	No printer, or that QR type is not set up in Settings.
429	`too_many_attempts`	Too many wrong passwords. Wait a minute.
503	`busy`	Q-Booth did not answer in time. Try again.

Log

Every call is written to the app log folder, log\local_api\, one file per day: the caller's address, the command and its parameters, the answer and the reason for any refusal. The password is never written. Successful status polls are left out.

Version history

API version	Q-Booth version	Changes
1	Coming soon	First release: status, commands, events, event start / stop, templates, categories, session start / end, category and template select, camera capture / retake / process, result print and QR.

Still need help?

Our team answers on WhatsApp. Tell us your Q-Booth version and what you see on screen.

Chat on WhatsApp