For developers

The Boliq API

Read bollard status and history, raise and lower bollards, and manage their schedules from your own system. The machine readable description is the OpenAPI spec.

Ask to connect your product

Companies that want their product to work with Boliq bollards can ask to connect. We look at every request. If we go ahead, you get a test key straight away and can build against practice bollards. Access to real bollards is agreed with us separately.

Who can use it

Partners such as security device makers and home platforms. Your app sends a bollard owner to Boliq to approve access (see sign in with Boliq below). To become a partner, send us a request below.
Business customers controlling their own bollards from their own systems. Create your own keys in your business account, under API keys.

How you reach a customer's bollards

The customer has a Boliq account: add a "Connect Boliq" button to your app that starts sign in with Boliq (below). The customer approves once, choosing the bollards and what you can do.
The customer only uses your app: Boliq assigns their bollards to you when they are installed, with your own site reference if you give us one.

Either way your live server key reaches every bollard you have been given. Each bollard in GET /devices shows a connection with how it was set up (owner or boliq) and your partner_reference, so you can match it to your customer. If you use sign in with Boliq you can also act with that customer's own access token.

Base address and keys

Everything is under https://boliq.co.uk/api/v1, over HTTPS, with JSON in and out. Send your key in the Authorization header.

curl https://boliq.co.uk/api/v1/devices \
  -H "Authorization: Bearer blq_test_YOUR_KEY"

Key	Starts with	Reaches
Test key	`blq_test_`	Three sandbox bollards that move instantly. Use these to build and test.
Live key	`blq_live_`	Real bollards: the ones an owner has approved for a partner, or a business customer's own.
Owner access token	`blq_at_`	The bollards and permissions one owner approved for your app. Lasts an hour.

Once we approve you, you get a partner account at boliq.co.uk where your team makes, rotates and removes keys (signing in always needs an authenticator app). Live keys are switched on by Boliq once your agreement is in place. Any key Boliq sends you comes as a one time link: open it, press Reveal, and copy the key. Keep keys secret and on your server. Boliq stores only a hash, so a lost key cannot be shown again, only replaced.

What you can do

Permission	Allows
Read (always)	Status, position, battery, last seen, faults, firmware, groups, schedules and event history.
`devices:control`	Lower a bollard.
`devices:raise`	Raise a bollard. Needs `devices:control`. The owner has to tick Allow raising, and Boliq has to enable raising for your app.
`schedules:write`	Create, change and delete schedules. The owner gets a notification each time.

The API never renames, shares, bills, orders, updates firmware on, unlinks or deletes anything, and cannot correct a bollard's position.

Raising and lowering

A bollard is a physical machine behind a mobile connection, so commands are asynchronous. The API answers 202 Accepted with a command id straight away, and the bollard acts when it next checks in: seconds on mains power, up to a few minutes in low power mode. A command is never confirmed in the same call.

curl -X POST https://boliq.co.uk/api/v1/devices/DEVICE_ID/commands \
  -H "Authorization: Bearer blq_test_YOUR_KEY" \
  -H "Idempotency-Key: 6f1c2b7e-0001" \
  -H "Content-Type: application/json" \
  -d '{"position": "lowered"}'

{ "id": "…", "state": "queued", "position": "lowered", "expires_at": "…" }

Then read GET /commands/{id} until it finishes.

State	Meaning
`queued`	Accepted, waiting for the bollard to check in.
`delivered`	The bollard has been told.
`completed`	The bollard reported the position you asked for.
`failed`	It did not happen. `failure_reason` says why, for example a fault, or a newer request or schedule took over.
`expired`	Not acted on within 15 minutes, so the request was withdrawn and the bollard will not move late.

Always send an Idempotency-Key. If a request times out, repeat it with the same key and you get the first command back instead of a second movement.

Raising is refused with 409 if the bollard is offline, has a fault or has not checked in recently. To protect batteries and the connection, each bollard allows a limited number of remote movements in 24 hours (429 movement_limit_reached).

Reading status comes from our database and never wakes a bollard, so position and battery are as of its last check in (last_seen_at). The bollards are access control and are not crash rated.

Sign in with Boliq (OAuth)

For partner apps acting for a bollard owner. It is the standard OAuth 2.0 authorization code flow, so it also works for Alexa and Google Home account linking. PKCE is supported and recommended (S256 only), and your client secret is always needed at the token step.

Send the owner to https://boliq.co.uk/connect.html with response_type=code, your client_id, a registered redirect_uri, a scope (space separated, for example devices:control schedules:write), a state and, if you use PKCE, a code_challenge with code_challenge_method=S256.
The owner signs in, chooses which bollards and permissions to allow, and is sent back to your redirect address with code and your state. If they say no you get error=access_denied.
From your server, POST https://boliq.co.uk/api/oauth/token with grant_type=authorization_code, code, redirect_uri, client_id and client_secret (in the body or as HTTP Basic), plus code_verifier if you used PKCE. You get an access token (1 hour) and a refresh token (90 days).
Refresh with grant_type=refresh_token. Each refresh gives a new pair. The old refresh token keeps working for 10 minutes, in case a reply is lost, then stops.

A code works once and expires after 10 minutes. The owner can disconnect your app at any time, which stops its tokens straight away, so handle 401 by asking them to connect again.

Limits and errors

Requests are limited per key per minute (60 by default). Over the limit you get 429 with a Retry-After header. The X-RateLimit-* headers show what is left.
API access to a bollard pauses while its monthly plan is cancelled or past due (403 plan_inactive).
Errors look like { "error": { "code": "…", "message": "…", "request_id": "req_…" } }. Quote the request_id if you contact us.

Endpoints

Method and path	Does
`GET /me`	Who the key belongs to, its permissions and limit.
`GET /devices`	The bollards you can reach.
`GET /devices/{id}`	One bollard, with its groups.
`POST /devices/{id}/commands`	Raise or lower.
`GET /devices/{id}/commands`	Recent commands.
`GET /commands/{id}`	A command and its state.
`GET /devices/{id}/events`	History. Changes through the API show as "Partner: Name".
`GET, POST /devices/{id}/schedules`	List and create schedules (UK local time).
`PATCH, DELETE /schedules/{id}`	Change and delete a schedule.
`GET /groups`	Named groups of bollards, read only.