Your first evaluation

This page walks through one full request loop: submit an evaluation, poll until it completes, fetch sanitised results, and call remediation for one violation. It assumes you have a working signed request (see Authentication).

State machine

pending  → processing → complete
                    ↘ error      (batch-level failure only)

• pending — row created, worker not yet started. Usually milliseconds.
• processing — worker running.
• complete — all scenarios finished. scenarios[] is populated.
• error — batch-level failure before any results were produced. The top-level error field carries the reason. Per-scenario failures do not flip the batch to error — the batch completes and the individual scenario entry carries its own error string.

Step 1 — Submit

Submit one or more scenarios. The batch is capped at 1–10 scenarios per call.

scenario_ids must already exist in your org

These are Make.com scenario IDs that have been imported into your FlowBeacon organization first (via the Make Custom App or the console) — there is no public "list scenarios" endpoint to enumerate them. If any ID does not resolve, the entire request is rejected with 404 and the unknown IDs are listed in the error; nothing is evaluated. To check a blueprint that isn't stored yet, use POST /evaluate/inline instead.

POST /api/public/v1/evaluate
Authorization: Bearer fb_live_EXAMPLE_xxxxxxxxxxxxxxxxxxxx
X-FB-Signature: t=1714564800,v1=9f86...
Content-Type: application/json

{
  "scenario_ids": ["4729318", "4729405"],
  "org_id": "3f7c1e90-2b8a-4d6e-9f10-5a2b6c8d4e12"
}

200 OK:

{
  "ok": true,
  "data": {
    "evaluation_id": "7a1c9b42-5e3d-4f80-9a6b-1c2d3e4f5a6b",
    "status": "processing",
    "total_scenarios": 2,
    "result_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.EXAMPLE.EXAMPLE"
  },
  "meta": { "watermark": "wm_a1b2c3d4" }
}

The result_token is single-use and expires in 15 minutes. Store it alongside the evaluation_id if you intend to use POST /results/fetch for the final fetch.

Step 2 — Poll

GET /api/public/v1/evaluations/7a1c9b42-5e3d-4f80-9a6b-1c2d3e4f5a6b

While running:

{
  "ok": true,
  "data": { "status": "processing", "total_scenarios": 2, "completed": 1 },
  "meta": { "watermark": "wm_a1b2c3d4" }
}

When status == "complete":

{
  "ok": true,
  "data": {
    "status": "complete",
    "total_scenarios": 2,
    "completed": 2,
    "scenarios": [
      {
        "id": "4729318",
        "name": "Lead sync to CRM",
        "score": 85,
        "violations": 3,
        "critical": 1,
        "compliance_gaps": ["SOC 2 CC6.1", "GDPR Art.32"],
        "module_violations": [
          {
            "module_id": "7",
            "module_name": "HTTP Request",
            "module_type": "http:ActionSendData",
            "badge": "critical",
            "violation_count": 2,
            "policies": ["SEC-5", "SEC-9"]
          }
        ]
      }
    ]
  },
  "meta": { "watermark": "wm_a1b2c3d4" }
}

Recommended poll interval

2 seconds is a sensible default. For batches of 5+ scenarios, exponential backoff (2 → 3 → 5 → 8 s) is friendlier on your rate budget. Production integrations should switch to webhooks.

Step 3 — Fetch per-scenario detail

For UI rendering you typically want one scenario at a time:

GET /api/public/v1/scenarios/4729318/results

The response carries the full sanitised violations[] array plus a per-module rollup. Check evaluation_status before showing a green badge — a scenario can exist in your org without ever having been evaluated.

{
  "ok": true,
  "data": {
    "scenario_id": "4729318",
    "scenario_name": "Lead sync to CRM",
    "violations": [
      {
        "policy": "SEC-5",
        "status": "fail",
        "severity": "critical",
        "title": "Hardcoded secrets in module parameters",
        "description": "",
        "remediation_available": true,
        "failing_modules": [
          {
            "module_id": "7",
            "module_name": "HTTP Request",
            "module_type": "http:ActionSendData",
            "reason": "Header value resembles a bearer token.",
            "badge": "critical"
          }
        ],
        "source": "automated"
      }
    ],
    "module_summary": [],
    "evaluated_codes": ["SEC-1", "SEC-3", "SEC-5", "SEC-9", "ARC-6"],
    "passing_count": 4,
    "failing_count": 1,
    "evaluation_status": "evaluated"
  },
  "meta": { "watermark": "wm_a1b2c3d4" }
}

Optional enrichment fields

description, summary, and compliance_frameworks on a violation are best-effort. Depending on the policy and what the evaluator captured, description may be an empty string, and summary and compliance_frameworks may be absent. Render them only when present, and rely on policy, title, severity, status, and failing_modules as the always-present fields.

Step 4 — Get remediation steps for a violation

The violation_id path segment is {scenario_id}:{policy_code}.

GET /api/public/v1/violations/4729318:SEC-5/remediation

Response:

{
  "ok": true,
  "data": {
    "steps": [
      "Click **Open in Platform** above to open your scenario in the Make.com editor.",
      "Open the HTTP Request module flagged under **Issues Found**.",
      "Move the bearer token out of the Headers field into a new Make.com connection.",
      "Click **OK** and **Save** to apply the change.",
      "Return to Flow Beacon and click **Re-analyze** to verify the fix."
    ],
    "severity": "critical",
    "estimated_effort": "low",
    "compliance_frameworks": [
      { "framework": "SOC 2", "control": "CC6.1" },
      { "framework": "GDPR", "article": "Art.32" }
    ]
  },
  "meta": { "watermark": "wm_a1b2c3d4" }
}

Rendering tips

• Severity: for badge colour and filters, prefer the catalog severity from GET /governance/policies. The per-violation severity is contextual and may fall back to medium.
• Module badges: the badge field on each module_violations[] entry already reflects the worst policy touching that module — no need to compute this client-side.
• Compliance chips: the compliance_frameworks[] array on each violation is optional and may be empty or absent. When present, it is the union of framework rows for that policy. Render only frameworks that appear; never invent gaps from its absence.
• Empty states: if evaluation_status == "not_evaluated" show a "Run analysis" prompt rather than a green checkmark.