Skip to content

brewlytics API Guide

Full API documentation can be found on the API Reference page.

Authentication to the brewlytics APIs is done via a token which is supplied in the REST call using the X-REQUEST-TOKEN header. These tokens are issued by brewauth, the platform’s identity service.

Personal tokens can be generated from your own profile — open the user menu in the top-right of the app and select Credentials.

Give the token a name and choose how long it should last. The secret is shown exactly once, at the moment you create it. Copy it immediately; it cannot be retrieved again. If you lose it, revoke that token and create another.

Every token expires. You choose a lifetime of up to 90 days, and 90 days is the default — there is no non-expiring token.

You can hold up to 10 active tokens at once (your deployment may configure a different limit). At the limit, creating another fails until you revoke one you no longer need.

Note: Your token will run all operations as you; you should safeguard it closely. It carries your full access, and it stops working the moment your account is disabled.

HttpsURLConnection conn = (HttpsURLConnection)url.openConnection();
conn.setRequestProperty("X-REQUEST-TOKEN", "<your_token>");
fetch(url, {
method: 'GET',
headers: {'X-REQUEST-TOKEN': '<your_token>' }
})
headers = {'X-REQUEST-TOKEN': '<your_token>'}
req = requests.get(url, headers=headers)
curl --header "X-REQUEST-TOKEN: <your_token>" {url}

A token’s lifetime cannot be extended: once created, its expiry is fixed. Replacing it is the only option, and there are two ways to do that — they differ in whether you get a window where both tokens work.

The Renew button, on each active token in the Credentials tab, does it in one step: it issues a replacement with the same name, shows you the new secret, and then revokes the old token immediately — so normally there is no period where both work. Use it when you can update your callers right away, and when a secret has leaked and you want the old one dead now.

Two things can leave the old token alive, and the app tells you about both. If the replacement cannot be created — because you are at the token limit, for instance — the old token is untouched and keeps working. If the replacement is created but revoking the old one fails, both tokens are live until you revoke the old one yourself from the list. That second case is the one to watch when you are rotating a leaked secret: confirm the old token is gone from the list before you treat the leak as closed.

Replacing by hand gives you a migration window. Create a second token, move your callers onto it, confirm they are working, and revoke the old one only once nothing is using it. Do it this way when the switch-over takes more than a moment: several callers to update, or a deployment to schedule.

A rejected call fails in one of two ways, and they mean different things:

  • 403 — the token itself was refused, and the message names the reason: it is expired, it has been revoked, it is not recognized, the account it belongs to is not active, or API tokens are turned off for the deployment. Retrying will not help. Create a new token, or get the account re-enabled.
  • 503 — the identity service could not be reached, so the token could be neither accepted nor refused. Your token is probably fine; retry the request.

Revoking a token takes effect within seconds rather than instantly: the result of resolving a token is cached briefly, so a revoked token may still be honoured until that entry expires.

A personal token belongs to a person and dies with their account — a scheduled job authenticated with one stops working when its owner leaves or is disabled. Personal tokens are the right tool for your own scripts and for getting an integration working. For automation that has to outlive any one person, service accounts authenticating with client_credentials are planned, and automation should move to them once they are available.

brewlytics Workflows become their own RESTful endpoints.

The behavior of the REST endpoint is dependent on:

  • What your workflow is set up to accomplish
  • The Workflow’s Variables
  • The Workflow’s Outputs

You can view the REST execution URL from the Workflow Toolbar on the Build canvas.

The workflow toolbar's REST Execution URL panel with inline input/output editors

For quick tests or lightweight integrations, a single functional can be run synchronously without wiring it into a full workflow. POST /api/director/functionals/{uuid}/execute creates a transient, one-component model, executes it, and returns the outputs inline — nothing to build or tear down. (This is the Director-fronted path integrators should call; it forwards internally to the AMEE-side /api/functionals/{uuid}/execute, which isn’t reachable directly from outside the cluster.)

  • Send scalar/list inputs as a JSON body ({"inputs": {...}}), or use multipart/form-data when one of the inputs is a CSV to be ingested as a CV_Table.
  • An optional outputs array filters the response down to just the output names you care about.
  • An optional options.timeoutMs bounds how long the call waits before failing; it’s clamped server-side (default 60s, max 600s).
  • Table outputs aren’t inlined — the response carries their schema and row count plus a fetchUrl you call separately to stream the CSV.
curl --header "X-REQUEST-TOKEN: <your_token>" \
--header "Content-Type: application/json" \
--data '{"inputs": {"name": "world"}}' \
{url}/api/director/functionals/{uuid}/execute

See the API Reference for the full request/response schema, including the multipart form and the table-output fetch endpoint.