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.

Autentificare

Fiecare cerere trebuie să poarte un bearer token în antetul Authorization. Tokenurile sunt emise din Account → API tokens; textul clar îți este afișat exact o singură dată la creare. Revocarea unui token întoarce 401 la următorul apel.

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

Format token: fxw_ urmat de 43 de caractere base64url. Stocat în repaus ca hash SHA-256; textul clar nu este persistat niciodată server-side.

Limite de rată

Două ferestre pentru fiecare cerere autentificată: burst de 10 req/sec și steady de 60 req/min, ambele pe baza hashului bearer. Aplicarea cotei (plafoane de scanări pe lună) se suprapune peste acestea: vezi Cote și limite.

Paginare

Endpoint-urile de listare (/api/v1/scans, /api/v1/findings) folosesc paginare bazată pe cursor, pe cheia (created_at, id) în ordine descrescătoare. Trimite ?cursor=<next_cursor> ca să aduci pagina următoare. Cursorul rămâne corect sub scrieri concurente (fără deviere OFFSET).

Forme de eroare

Fiecare eroare este un obiect JSON cu cel puțin o cheie 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

Endpoint-uri

Pornește o scanare

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"}'

// răspuns 200

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

Listează scanările tale

GET/api/v1/scans

Întoarce scanările pentru organizația legată de tokenul apelant, cele mai noi primele. Paginatează cu ?cursor=. Limită implicită 50, maxim 100.

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

// răspuns 200

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

Obține o scanare

GET/api/v1/scans/{scanId}

Întoarce implicit anvelopa scanării + rezumatul severității pe categorie. Trimite ?include_findings=true ca să primești raportul complet (mare pentru scanări zgomotoase: preferă endpoint-ul de constatări cu filtre).

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

Listează constatările

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"

// răspuns 200

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

Specificație OpenAPI

Specificație lizibilă de mașină la /docs/api/openapi (text/yaml). Pune-o în generatorul tău preferat (openapi-typescript, openapi-python-client sau orice toolchain OpenAPI 3.1) pentru clienți tipizați.

REST API — Docs · FixWeb