Skip to main content

Quickstart

Sign up, get an API key, and make your first evaluation in five minutes.

Prerequisites
  • A FlowBeacon admin account on the target organization.
  • The ability to make HTTPS requests from a server (this is not a browser API).
  • One Make.com scenario already imported into your organization.

1. Create an account​

If you don't have a FlowBeacon account yet, sign up at app.flowbeacon.ai. If your organization already has an account, ask an admin to invite you.

2. Get an API key​

  1. Sign in to the FlowBeacon web console.
  2. Navigate to Settings → API Keys (/settings/api-keys).
  3. Click Create API key, give it a name (for example make-grid-production), pick the permissions you need, and optionally set an IP allowlist and an expiration date.
  4. Copy the raw key shown in the reveal dialog, then tick the "I've stored this key" confirmation.
The raw key is shown exactly once

Once you dismiss this dialog, the raw value cannot be retrieved. If you lose it, rotate or recreate the key — there is no recovery flow.

Keys look like:

fb_live_EXAMPLE_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

3. Verify reachability​

The health endpoint requires no authentication and no signature — use it to confirm DNS, TLS, and routing.

curl -sS https://api.flowbeacon.ai/api/public/v1/governance/health

Response:

{ "ok": true, "service": "flowbeacon-public-api", "version": "1.0.0" }

4. Submit your first evaluation​

Every authenticated request needs both an Authorization header and an X-FB-Signature HMAC header. The snippets below compute the signature inline. See Sign requests with HMAC for the deep dive.

POST/evaluate 
import crypto from 'node:crypto';

const API_KEY = process.env.FLOWBEACON_API_KEY!;
const ORG_ID  = process.env.FLOWBEACON_ORG_ID!;
const BASE = 'https://api.flowbeacon.ai/api/public/v1';
const PATH = '/evaluate';
const PREFIX = '/api/public/v1';

const ts = Math.floor(Date.now() / 1000);
const body = JSON.stringify({
  scenario_ids: ['4729318'],
  org_id: ORG_ID,
});
const sig = crypto
  .createHmac('sha256', API_KEY)
  .update(`${ts}.POST.${PREFIX}${PATH}.${body}`)
  .digest('hex');

const res = await fetch(`${BASE}${PATH}`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${API_KEY}`,
    'Content-Type': 'application/json',
    'X-FB-Signature': `t=${ts},v1=${sig}`,
  },
  body,
});

const { data } = await res.json();
console.log(data.evaluation_id);

Response (200):

{
  "ok": true,
  "data": {
    "evaluation_id": "req_example_01HZYABC0K7M3P4QVZ9TN2RXEK",
    "status": "processing",
    "total_scenarios": 1,
    "result_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.EXAMPLE.EXAMPLE"
  },
  "meta": { "watermark": "wm_a1b2c3d4" }
}

5. Poll for completion​

GET/evaluations/{evaluation_id} 
SIG=$(sign GET "$PREFIX/evaluations/req_example_01HZYABC0K7M3P4QVZ9TN2RXEK" "")
curl -sS https://api.flowbeacon.ai/api/public/v1/evaluations/req_example_01HZYABC0K7M3P4QVZ9TN2RXEK \
  -H "Authorization: Bearer $API_KEY" \
  -H "X-FB-Signature: $SIG"

When status == "complete" the response contains a scenarios[] array with per-scenario scores, violation counts, and module-level rollups.

Skip polling in production

Register a webhook and react to evaluation.complete deliveries instead. The polling loop above is fine for one-off scripts; webhooks scale better in production.

6. Fetch detailed results​

GET/scenarios/{scenario_id}/results

Either:

  • Use the one-shot result token returned by POST /evaluate — GET /results/{token}. Single-use, 15-minute TTL.
  • Or fetch one scenario at a time with GET /scenarios/{id}/results (idempotent, cacheable).
SIG=$(sign GET "$PREFIX/scenarios/4729318/results" "")
curl -sS "$BASE/scenarios/4729318/results" \
  -H "Authorization: Bearer $API_KEY" \
  -H "X-FB-Signature: $SIG"

The response includes a violations[] array, a per-module rollup, and an evaluation_status field — check evaluation_status before showing a green badge to a user.

Next steps​