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.

Autentikimi

Çdo request duhet të mbajë bearer token në header Authorization. Tokens lëshohen nga Account → API tokens; plaintext shfaqet saktësisht një herë në creation. Revoking token kthen 401 në call-in tjetër.

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

Token format: fxw_ i ndjekur nga 43 base64url characters. Stored at rest si SHA-256 hash; plaintext nuk persist kurrë server-side.

Rate limits

Dy windows në çdo authenticated request: 10 req/sec burst dhe 60 req/min steady, të dy keyed on bearer hash. Quota enforcement (per-month scan caps) shtohet sipër — shihni Kuota dhe kufij.

Paginimi

List endpoints (/api/v1/scans, /api/v1/findings) përdorin cursor-based pagination keyed on (created_at, id) në descending order. Kaloni ?cursor=<next_cursor> për të marrë next page. Cursor mbetet correct under concurrent writes (pa OFFSET skew).

Formatet e gabimeve

Çdo error është JSON object me të paktën një 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

Nis një 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"
}

Listoni skanimet tuaja

GET/api/v1/scans

Kthen scans për org të lidhur me calling token, newest first. Paginate me ?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-..."
}

Merr një scan

GET/api/v1/scans/{scanId}

Kthen scan envelope + per-category severity summary by default. Kaloni ?include_findings=true për full report (large for noisy scans — prefer findings endpoint me filters).

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

Listoni 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 te /docs/api/openapi (text/yaml). Drop into your favourite codegen (openapi-typescript, openapi-python-client ose çdo OpenAPI 3.1 toolchain) për typed clients.

REST API — Docs · FixWeb