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.

אָטענטיקאַציע

יעדער request מוז טראָגן אַ bearer token אין דעם Authorization header. Tokens ווערן issued פֿון Account → API tokens; דער plaintext ווערט דיר געוויזן פּינקטלעך איין מאָל בײַ creation. Revoking אַ token גיט צוריק 401 אויף דער קומענדיקער call.

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

Token format: fxw_ נאָכגעפֿאָלגט פֿון 43 base64url characters. Stored at rest ווי אַ SHA-256 hash; דער plaintext ווערט קיינמאָל נישט persisted server-side.

ראַטע־לימיטן

צוויי windows אויף יעדן authenticated request: 10 req/sec burst און 60 req/min steady, ביידע keyed אויף דעם bearer hash. Quota enforcement (per-month scan caps) לייגט זיך דערויף — זע Quotas און לימיטן.

בלאַטנירונג

List endpoints (/api/v1/scans, /api/v1/findings) נוצן cursor-based pagination keyed אויף (created_at, id) אין descending order. גיב איבער ?cursor=<next_cursor> צו fetchן דעם קומענדיקן בלאַט. דער cursor בלײַבט ריכטיק אונטער concurrent writes (קיין OFFSET skew).

טעות־פֿאָרמען

יעדער error איז אַ JSON object מיט לפּחות אַן 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

ענדפּוינטן

אָנהייבן אַ 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"
}

ליסט דײַנע scans

GET/api/v1/scans

גיט צוריק scans פֿאַר דער org וואָס איז פֿאַרבונדן מיטן calling token, נײַסטע ערשט. Paginate מיט ?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-..."
}

באַקומען אַ scan

GET/api/v1/scans/{scanId}

גיט צוריק scan envelope + severity summary פּער category דורך default. גיב איבער ?include_findings=true צו באַקומען דעם פולן באַריכט (גרויס פֿאַר noisy scans — בעסער דער findings endpoint מיט filters).

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

ליסט 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 בײַ /docs/api/openapi (text/yaml). לייג עס אַרײַן אין דײַן באַליבטן codegen (openapi-typescript, openapi-python-client, אָדער סיי וועלכן OpenAPI 3.1 toolchain) פֿאַר typed clients.

REST API — Docs · FixWeb