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 во header Authorization. Tokens се издаваат од 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 никогаш не се persist server-side.

Rate limits

Два windows на секој authenticated request: 10 req/sec burst и 60 req/min steady, двата keyed on bearer hash. Quota enforcement (per-month scan caps) се слои одозгора — видете Квоти и лимити.

Пагинација

List endpoints (/api/v1/scans, /api/v1/findings) користат cursor-based pagination keyed on (created_at, id) во descending order. Пратете ?cursor=<next_cursor> за next page. Cursor останува correct under concurrent writes (без OFFSET skew).

Облици на грешки

Секоја error е JSON object со најмалку key error.

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

Стартувај 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, newest first. 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 + per-category severity summary by default. Пратете ?include_findings=true за full report (large for noisy scans — prefer 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). Drop into your favourite codegen (openapi-typescript, openapi-python-client или било кој OpenAPI 3.1 toolchain) за typed clients.

REST API — Docs · FixWeb