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 header. You generate the signature yourself — it is not issued by FlowBeacon and is not returned by any endpoint. Each snippet below builds it locally by HMAC-SHA256-signing a canonical request string with your API key (your key is both the bearer credential and the signing secret). See Authentication for the full walkthrough.

Where do I get org_id?

The snippets read an org_id (FLOWBEACON_ORG_ID) value. Your API key is bound to exactly one organization, and the org_id you send must match it — otherwise you get 403 org_id does not match API key organization. To discover it, call GET /me once with your signed key; it returns your organization_id. For org-scoped path routes you can also skip the lookup and pass the literal me — for example GET /org/me/summary.

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": "7a1c9b42-5e3d-4f80-9a6b-1c2d3e4f5a6b",
    "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/7a1c9b42-5e3d-4f80-9a6b-1c2d3e4f5a6b" "")
curl -sS https://api.flowbeacon.ai/api/public/v1/evaluations/7a1c9b42-5e3d-4f80-9a6b-1c2d3e4f5a6b \
  -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 — POST /results/fetch. 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.

Last updated on