FixWeb

// docs / rest api

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.

Pag-authenticate

Bawat request ay dapat may bearer token sa Authorization header. Inii-issue ang tokens mula sa Account → API tokens; isang beses lang ipinapakita sa iyo ang plaintext sa paggawa. Kapag ni-revoke ang token, magbabalik ng 401 ang susunod na call.

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

Format ng token: fxw_ na sinusundan ng 43 base64url characters. Ini-store at rest bilang SHA-256 hash; hindi kailanman pine-persist server-side ang plaintext.

Mga rate limit

Dalawang window sa bawat authenticated request: 10 req/sec burst at 60 req/min steady, parehong naka-key sa bearer hash. Nakapatong sa ibabaw ang quota enforcement (scan caps kada buwan) — tingnan ang Mga quota at limitasyon.

Paginasyon

Gumagamit ang list endpoints (/api/v1/scans, /api/v1/findings) ng cursor-based pagination na naka-key sa (created_at, id) sa descending order. Ipasa ang ?cursor=<next_cursor> para kunin ang susunod na page. Nananatiling tama ang cursor sa concurrent writes (walang OFFSET skew).

Mga hugis ng error

Bawat error ay JSON object na may kahit man lang error key.

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

Endpoints

Magsimula ng 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 response

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

Ilista ang iyong scans

GET/api/v1/scans

Ibinabalik ang scans para sa org na nakatali sa calling token, pinakabago muna. Mag-paginate gamit ang ?cursor=. Default limit 50, max 100.

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

// 200 response

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

Kumuha ng scan

GET/api/v1/scans/{scanId}

Ibinabalik ang scan envelope + per-category severity summary bilang default. Ipasa ang ?include_findings=true para makuha ang buong report (malaki para sa maingay na scans — mas mainam ang findings endpoint na may filters).

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

Ilista ang 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 response

{
  "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 spec

Machine-readable spec sa /docs/api/openapi (text/yaml). Ipasok sa paborito mong codegen (openapi-typescript, openapi-python-client, o anumang OpenAPI 3.1 toolchain) para sa typed clients.

REST API — Docs · FixWeb