Pro API

The Pro API lets you interact with your brewerys' data, i.e. to enable custom build dashboards.

Setup

To enable the Pro API: Got to your brewerys admin page (https://bricks.bierbot.com/#/brewery/admin), locate the "Pro-API" section and toggle the enable toggle to on. The Pro-API key and API key become available. The latter is the normal API key you've used for setting up all your Brick. The first one is an additional API key we need for communicating with the API.

Usage

Note: This requires at least a PRO membership.

All endpoints live under https://bricks.bierbot.com and take your apikey and proapikey as query parameters. Every call — reading or writing — counts once against the same monthly request budget of your membership. You can see how many requests you have left on the brewery admin page; the budget refills at the start of each month.

If you're missing an endpoint, please reach out using the blue feedback button, the contact form or the forum.

List all devices

get

List all devices (their IDs) of a brewery.

Query parameters

apikeystringOptionalExample: 3iHUDCxPfoo42ZyrmmAz

proapikeystringOptionalExample: aAaAa4242CxPfoo42ZyrmmAz

Responses

200

application/json

objectOptional

get/api/devices

GET /api/devices HTTP/1.1
Accept: */*

200

{}

Get device details

get

Get details for a given device.

Query parameters

apikeystringOptionalExample: 3iHUDCxPfoo42ZyrmmAz

proapikeystringOptionalExample: aAaAa4242CxPfoo42Z42

deviceidstringOptionalExample: RqUiO7eDRe3xKyKgXtwc

Responses

200

application/json

objectOptional

get/api/device

GET /api/device HTTP/1.1
Accept: */*

200

{}

List all brews

get

List all brews of a brewery, newest first.

Returns ids and a summary only. The full documents are large — a brew carries its recipe, its steps and its calibration — so use /api/brew/{brewId} for the one you are interested in.

Query parameters

apikeystringRequired

The apikey of your brewery.

Example: 3iHUDCxPfoo42ZyrmmAz

proapikeystringRequired

Your Pro-API key.

Example: aAaAa4242CxPfoo42ZyrmmAz

Responses

200

application/json

idstringOptional

Use this with /api/brew/{brewId}.

Example: Zf1f4Utc1kH6DWQSmXn5

namestringOptional

Name of the recipe being brewed.

Example: Hazy IPA

activebooleanOptional

Whether this brew is currently running.

activeStatestringOptional

e.g. mashing, boiling, fermenting.

Example: mashing

startedMsinteger · int64Optional

Start of the brew, in milliseconds since epoch.

currentStepIndexintegerOptional

Index of the current recipe step.

currentSubStepIndexintegerOptional

Index of the current sub step.

stepsobject[]Optional

The process steps of this brew.

400

Missing or unknown api key.

text/plain

429

Monthly request budget exhausted.

text/plain

get/api/brews

GET /api/brews?apikey=text&proapikey=text HTTP/1.1
Accept: */*

[
  {
    "id": "Zf1f4Utc1kH6DWQSmXn5",
    "name": "Hazy IPA",
    "active": true,
    "activeState": "mashing",
    "startedMs": 1,
    "currentStepIndex": 1,
    "currentSubStepIndex": 1,
    "steps": [
      {}
    ]
  }
]

Get brew details

get

Get the full document of a single brew, including its recipe, process steps and calibration.

GET /api/brew?brewid=... works as well, mirroring /api/device.

Path parameters

brewIdstringRequired

The id of the brew, as returned by /api/brews.

Example: Zf1f4Utc1kH6DWQSmXn5

Query parameters

apikeystringRequired

The apikey of your brewery.

Example: 3iHUDCxPfoo42ZyrmmAz

proapikeystringRequired

Your Pro-API key.

Example: aAaAa4242CxPfoo42ZyrmmAz

Responses

200

application/json

objectOptional

400

Missing api key or brew id.

text/plain

404

No such brew in this brewery.

text/plain

429

Monthly request budget exhausted.

text/plain

get/api/brew/{brewId}

GET /api/brew/{brewId}?apikey=text&proapikey=text HTTP/1.1
Accept: */*

{}

Controlling your brewery

The endpoints above read. The two below change what your hardware does — they are the same commands the buttons in the app send, so anything you trigger here behaves exactly as if you had pressed it yourself. Both are POST for that reason.

Your Pro-API key is enough to switch heating on. Treat it like a password: do not put it in a URL you paste into a support ticket, a screenshot, or a public repository. The key is created once, when you first enable the Pro API, and there is no self-service way to replace it yet — if yours has leaked, please get in touch.

Control a brew

post

Advance, stop, or mark boiling reached on a running brew.

This is the same command the buttons in the app send, so anything you start here behaves exactly as if you had pressed it yourself.

POST, because it changes what your hardware does.

Path parameters

brewIdstringRequired

The id of the brew to control.

Example: Zf1f4Utc1kH6DWQSmXn5

Query parameters

apikeystringRequired

The apikey of your brewery.

Example: 3iHUDCxPfoo42ZyrmmAz

proapikeystringRequired

Your Pro-API key.

Example: aAaAa4242CxPfoo42ZyrmmAz

Body

commandstring · enumRequired

nextstep advances to the next recipe step. stop ends the brew. boiling marks the boiling temperature as reached, which starts the boil timer.

Example: nextstepPossible values:

Responses

200

application/json

okbooleanOptional

brewobjectOptional

The brew after the command was applied.

400

Missing api key, or an unknown command.

text/plain

404

No such brew in this brewery.

text/plain

409

The brew is not in a state that accepts this command, e.g. boiling on a brew that has no boiling step.

text/plain

429

Monthly request budget exhausted.

text/plain

post/api/brew/{brewId}/control

POST /api/brew/{brewId}/control?apikey=text&proapikey=text HTTP/1.1
Content-Type: application/json
Accept: */*
Content-Length: 22

{
  "command": "nextstep"
}

{
  "ok": true,
  "brew": {}
}

Set a device target state

post

Set the target temperature and/or the stirring of a device.

Only these two fields can be set — this is a control surface, not a document editor. Everything else about the device stays read-only.

Path parameters

deviceIdstringRequired

The id of the device, as returned by /api/devices.

Example: RqUiO7eDRe3xKyKgXtwc

Query parameters

apikeystringRequired

The apikey of your brewery.

Example: 3iHUDCxPfoo42ZyrmmAz

proapikeystringRequired

Your Pro-API key.

Example: aAaAa4242CxPfoo42ZyrmmAz

Body

Send tempCelsius, circulate, or both. Sending neither is a 400.

tempCelsiusnumber · min: -20 · max: 150Optional

Target temperature in degree celsius.

Example: 67

circulateinteger · enumOptional

Stirring / circulation: 1 on, 0 off.

Example: 1Possible values:

Responses

200

application/json

okbooleanOptional

deviceobjectOptional

The device's new target and control state.

400

Missing api key, or neither tempCelsius nor circulate was sent.

text/plain

404

No such device in this brewery.

text/plain

429

Monthly request budget exhausted.

text/plain

post/api/device/{deviceId}/target

POST /api/device/{deviceId}/target?apikey=text&proapikey=text HTTP/1.1
Content-Type: application/json
Accept: */*
Content-Length: 32

{
  "tempCelsius": 67,
  "circulate": 1
}

{
  "ok": true,
  "device": {}
}

PreviousConnecting displays

NextChangelog

Last updated 24 days ago

Was this helpful?