Skip to main content

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 a list of Make.com scenario IDs, runs the FlowBeacon governance catalog against each, 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. Evaluations are asynchronous, polled via REST or pushed via webhooks.
  • It does not accept blueprints inline. Scenarios are referenced by ID. The organization must have previously imported the scenario via its configured Make.com connection.

Core concepts​

ConceptDefinition
OrganizationTenant boundary inside FlowBeacon. Every API key belongs to exactly one organization. All reads and writes are scoped to the owning organization.
API keyA 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.
ScenarioA Make.com scenario that has been imported into the organization in FlowBeacon. Referenced by its Make.com scenario ID.
BlueprintThe stored JSON representation of a scenario inside FlowBeacon. Used internally as the evaluation target; partners address it by scenario ID.
PolicyA 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. See the policy catalog.
EvaluationAn 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.
ViolationA 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.
RemediationOrdered, human-readable steps a user can follow to fix a violation. Generated on demand for a specific scenario_id:policy_code pair.
WatermarkAn 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 tokenA short-lived single-use JWT returned by POST /evaluate. Allows fetching full sanitised results exactly once via GET /results/{token} (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

A competent backend engineer should reach a successful POST /evaluate within 10 minutes of receiving a key. See the Quickstart for a step-by-step walkthrough.

Next steps​