API Overview

The FlowBeacon Public API is a server-to-server HTTP/JSON API for submitting automation blueprints to FlowBeacon's governance engine and retrieving violations, remediation guidance, and compliance rollups.

What this API does

• Accepts scenarios two ways: by ID (stored scenarios already imported into your org) or as a raw blueprint inline. Inline evaluation is ephemeral — the blueprint is evaluated in memory and never stored.
• Offers a synchronous, one-call inline mode (POST /evaluate/inline) that returns violations, the canvas module graph, and (optionally) remediation in a single response — ideal for real-time governance.
• Runs the FlowBeacon governance catalog against each scenario and returns structured violations, severities, and compliance-framework mappings.
• Returns per-scenario detail that powers badges on individual modules inside a scenario canvas.
• Produces step-by-step remediation guidance for any violation.
• Returns an organization-wide rollup (score, top violations, framework coverage).
• Lets org admins create, list, rotate, and revoke API keys from within the FlowBeacon web console.

What this API does not do

• It does not modify your scenarios. All writes to Make.com must be performed by the integrating party; FlowBeacon only reads and evaluates.
• It does not expose raw evaluator output, model output, or the internal reasoning that produced a violation. Only stable summary fields are returned.
• It does not provide live event streaming. Batch evaluations are polled via REST or pushed via webhooks; for an immediate result in a single round-trip, use synchronous inline evaluation (POST /evaluate/inline).
• It does not store inline blueprints. Ephemeral evaluations are held in memory only (no user_blueprints row, no result token, no webhook) unless you opt in with save_to_workspace.

Core concepts

Concept	Definition
Organization	Tenant boundary inside FlowBeacon. Every API key belongs to exactly one organization. All reads and writes are scoped to the owning organization.
API key	A bearer credential of the form fb_live_<48 hex chars> used to authenticate requests to /api/public/v1/*. Scoped to one organization; carries permissions and rate limits.
Scenario	A Make.com scenario that has been imported into the organization in FlowBeacon. Referenced by its Make.com scenario ID.
Blueprint	The stored JSON representation of a scenario inside FlowBeacon. Used internally as the evaluation target; partners address it by scenario ID.
Policy	A governance rule with a stable code such as SEC-1 or DI-3. Each policy has a severity, category, and list of compliance-framework mappings. Enumerated by GET /governance/policies.
Evaluation	An asynchronous batch job that runs the applicable policy subset against one or more scenarios. State machine: pending → processing → complete | error. Per-scenario failures do not flip the batch status to error — the batch completes and the individual scenario entry carries its own error string.
Violation	A single policy result whose status is fail or warn on a given scenario. Carries a severity, description, optional failing-module list, and a compliance-framework mapping.
Remediation	Ordered, human-readable steps a user can follow to fix a violation. Generated on demand for a specific scenario_id:policy_code pair.
Watermark	An opaque string of the form wm_<8 hex> returned on every authenticated response, logged server-side against the calling key. Used for leak tracing; clients may ignore it.
Result token	A short-lived single-use JWT returned by POST /evaluate. Allows fetching full sanitised results exactly once via POST /results/fetch (15-minute TTL).

Typical partner flow

POST /evaluate                                 → evaluation_id, result_token
loop:
  GET /evaluations/{id}                        → status in {pending, processing, complete, error}
  break when terminal
for each scenario:
  GET /scenarios/{id}/results                  → full sanitised violations + module rollup
  for each violation requiring UX:
    GET /violations/{scenario_id}:{policy_code}/remediation

Or collapse the whole loop into a single synchronous call when you already hold the blueprint (e.g. fetched from the Make API):

POST /evaluate/inline  { blueprint, include_remediation: true }
  → violations + module graph + remediation, in one ephemeral response

See Real-time & inline evaluation for when to use each.