REST API reference

Every endpoint below is relative to this base — e.g. POST /v1/scans/trigger means POST https://api.flawpilot.com/v1/scans/trigger.

https://api.flawpilot.com

Every endpoint except the two health checks requires a Bearer API key. Create and manage keys from the dashboard under Settings → API Keys. A key identifies a workspace (tenant) — there is no per-user auth on this surface, and the same key works for the MCP server too.

Authorization: Bearer YOUR_API_KEY

Missing or invalid keys get:

{ "statusCode": 401, "message": "Unauthorized" }

Exceeding a limit returns 429 with a Retry-After header (seconds until the window resets):

{ "error": "Too many requests. Please retry shortly." }

Authenticated and validated endpoints that fail return a consistent shape. There is no separate machine-readable error code — match on statusCode plus, if needed, the exact message text documented per endpoint.

{ "statusCode": 400, "message": "<human-readable message>" }

Query parameters

Response — 200

[
  { "projectId": "PRJ-3TV1T", "name": "Marketing Site", "status": "ACTIVE" }
]

Example

curl https://api.flawpilot.com/v1/projects \
  -H "Authorization: Bearer YOUR_API_KEY"

Request body

With an email

{
  "projectId": "PRJ-3TV1T",
  "url": "https://example.com",
  "pillars": ["SECURITY"],
  "email": "[email protected]"
}

Skipping the email (these three are equivalent)

{ "projectId": "PRJ-3TV1T", "url": "https://example.com", "email": null }

{ "projectId": "PRJ-3TV1T", "url": "https://example.com", "email": "" }

{ "projectId": "PRJ-3TV1T", "url": "https://example.com" }

Example

curl -X POST https://api.flawpilot.com/v1/scans/trigger \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "projectId": "PRJ-XXXXX",
    "url": "https://example.com",
    "pillars": ["SECURITY"],
    "email": "[email protected]"
  }'

Response — 202 Accepted

{ "scanJobId": "b3f1...", "status": "QUEUED", "queuedAt": "2026-07-27T10:00:00.000Z" }

Errors (confirmed)

Errors (intended, not yet guaranteed)

This public route is always authenticated. The website’s own progress UI polls a separate, unauthenticated version of the same underlying service for logged-in browser sessions — but this API route never accepts unauthenticated calls.

Response — 200 (non-terminal)

{
  "status": "RUNNING",
  "completed": 8,
  "total": 20,
  "startedAt": "2026-07-27T10:00:05.000Z",
  "url": "https://example.com",
  "email": "[email protected]",
  "categories": [
    {
      "pillar": "SECURITY",
      "title": "Security",
      "score": 62.5,
      "max_score": 100,
      "band": "ELEVATED_RISK",
      "results": [ /* subcategory scores */ ]
    }
  ]
}

Once status reaches a terminal value (COMPLETE, PARTIAL, or FAILED), the response also includes:

Errors