// docs / rest api

Fakahinohino REST API

Bearer-authenticated JSON API for passive scan automation, scan status, and findings. Cursor-paginated, rate-limited, and shipped with a machine-readable OpenAPI spec for client codegen. Active scans stay in the dashboard UI for ownership attestation.

Fakamo'oni'i

Kuo pau ke 'ave 'e request kotoa ha bearer token 'i he Authorization header. Tokens 'oku issued mei Account → API tokens; 'oku shown e plaintext kiate koe exactly once 'i creation. Revoking a token returns 401 'i he next call.

bash

curl -H "Authorization: Bearer fxw_..." \
  https://fixweb.app/api/v1/scans

Token format: fxw_ followed by 43 base64url characters. Stored at rest as a SHA-256 hash; 'oku 'ikai persist e plaintext server-side.

Ngaahi rate limits

Two windows on every authenticated request: 10 req/sec burst mo 60 req/min steady, both keyed on the bearer hash. Quota enforcement (per-month scan caps) layers on top — see Quotas & limits.

Fakapeesi

List endpoints (/api/v1/scans, /api/v1/findings) use cursor-based pagination keyed on (created_at, id) in descending order. Pass ?cursor=<next_cursor> ke fetch e next page. 'Oku nofo tonu e cursor under concurrent writes (no OFFSET skew).

Ngaahi fōtunga error

Error kotoa ko ha JSON object mo ha error key 'i he si'isi'i taha.

jsonc

{ "error": "invalid_token" }                              // 401
{ "error": "forbidden" }                                  // 403
{ "error": "not_found" }                                  // 404
{ "error": "quota_exceeded", "quota": {...} }             // 429
{ "error": "rate_limited", "retry_after_seconds": 47 }    // 429
{ "error": "invalid_input", "issues": [...] }             // 400

Ngaahi endpoints

Start ha scan

POST/api/v1/scans

Enqueues a passive scan. Returns immediately with a queued scan id; poll GET /api/v1/scans/[scanId] until status === "completed". Owner-depth mode is not exposed — see Scan types for the attestation-flow rationale.

curl -X POST https://fixweb.app/api/v1/scans \
  -H "Authorization: Bearer fxw_..." \
  -H "content-type: application/json" \
  -d '{"target":"https://staging.example.com"}'

// 200 tali

{
  "id": "8f1c4e2a-8c3a-4b6f-9c0d-9b1e8f3c2a4d",
  "status": "queued",
  "target": "https://staging.example.com",
  "mode": "passive"
}

List ho'o scans

GET/api/v1/scans

Returns scans for the org tied to the calling token, newest first. Paginate with ?cursor=. Default limit 50, max 100.

curl -H "Authorization: Bearer fxw_..." \
  "https://fixweb.app/api/v1/scans?limit=25"

// 200 tali

{
  "scans": [
    {
      "id": "8f1c4e2a-...",
      "target_url": "https://staging.example.com",
      "target_hostname": "staging.example.com",
      "mode": "passive",
      "status": "completed",
      "started_at": "2026-05-07T14:00:00Z",
      "completed_at": "2026-05-07T14:00:23Z",
      "findings_count": { "critical": 1, "high": 3, "medium": 7, "low": 2, "info": 4 },
      "triggered_by": "api",
      "created_at": "2026-05-07T14:00:00Z"
    }
  ],
  "next_cursor": "2026-05-07T14:00:00Z:8f1c4e2a-..."
}

Get ha scan

GET/api/v1/scans/{scanId}

Returns scan envelope + per-category severity summary by default. Pass ?include_findings=true to get the full report (large for noisy scans — prefer the findings endpoint with filters).

curl -H "Authorization: Bearer fxw_..." \
  https://fixweb.app/api/v1/scans/8f1c4e2a-8c3a-4b6f-9c0d-9b1e8f3c2a4d

List e findings

GET/api/v1/findings

Filterable findings list across every scan in the caller's org. Filters: severity=critical,high, check_id=performance.delivery, since=2026-04-01T00:00:00Z. Cursor-paginated.

curl -H "Authorization: Bearer fxw_..." \
  "https://fixweb.app/api/v1/findings?severity=critical,high&limit=50"

// 200 tali

{
  "findings": [
    {
      "id": "...",
      "scan_id": "...",
      "check_id": "secrets.js-bundle-sweep",
      "severity": "critical",
      "title": "Supabase service role key exposed in JS bundle",
      "description": "...",
      "evidence": { ... },
      "remediation": "...",
      "cwe_id": "CWE-798",
      "created_at": "2026-05-07T14:00:23Z"
    }
  ],
  "next_cursor": null
}

OpenAPI specification

Machine-readable spec 'i /docs/api/openapi (text/yaml). Drop into ho'o favourite codegen (openapi-typescript, openapi-python-client, pe ha OpenAPI 3.1 toolchain) ma'a typed clients.