Skip to main content

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.

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": "org_example_01HZYABCDEFGHJKMNPQRSTVWXY"
}

200 OK:

{
  "ok": true,
  "data": {
    "evaluation_id": "req_example_01HZYABC0K7M3P4QVZ9TN2RXEK",
    "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 GET /results/{token} for the final fetch.

Step 2 — Poll​

GET /api/public/v1/evaluations/req_example_01HZYABC0K7M3P4QVZ9TN2RXEK

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" }
}

:::tip 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": "Static credentials must not be embedded in module configuration.",
        "summary": "Found a key-shaped string in the HTTP Request module headers.",
        "compliance_frameworks": [
          { "framework": "SOC 2", "control": "CC6.1" },
          { "framework": "GDPR", "article": "Art.32" },
          { "framework": "PCI-DSS", "requirement": "Req.3.4" }
        ],
        "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" }
}

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 the union of framework rows for that policy. Render only frameworks that appear; never invent gaps.
  • Empty states: if evaluation_status == "not_evaluated" show a "Run analysis" prompt rather than a green checkmark.

Next steps​