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.

Authentication

Κάθε request πρέπει να φέρει bearer token στο header Authorization. Τα tokens εκδίδονται από Λογαριασμός → API tokens· το plaintext εμφανίζεται ακριβώς μία φορά κατά τη δημιουργία. Η ανάκληση token επιστρέφει 401 στην επόμενη κλήση.

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

Μορφή token: fxw_ ακολουθούμενο από 43 base64url χαρακτήρες. Αποθηκεύεται σε ηρεμία ως SHA-256 hash· το plaintext δεν αποθηκεύεται ποτέ server-side.

Όρια ρυθμού

Δύο παράθυρα σε κάθε authenticated request: burst 10 req/sec και steady 60 req/min, και τα δύο κλειδωμένα στο bearer hash. Η επιβολή ποσόστωσης (μηνιαία όρια σαρώσεων) μπαίνει από πάνω — δες Ποσοστώσεις & όρια.

Σελιδοποίηση

Τα list endpoints (/api/v1/scans, /api/v1/findings) χρησιμοποιούν cursor-based pagination με κλειδί (created_at, id) σε φθίνουσα σειρά. Πέρασε ?cursor=<next_cursor> για να πάρεις την επόμενη σελίδα. Ο cursor μένει σωστός με concurrent writes (χωρίς OFFSET skew).

Μορφές σφαλμάτων

Κάθε σφάλμα είναι 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

Ξεκίνα μια σάρωση

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

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

Λίστα σαρώσεών σου

GET/api/v1/scans

Επιστρέφει σαρώσεις για το org που συνδέεται με το token της κλήσης, οι νεότερες πρώτες. Σελιδοποίησε με ?cursor=. Προεπιλεγμένο limit 50, μέγιστο 100.

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

// απόκριση 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-..."
}

Πάρε μια σάρωση

GET/api/v1/scans/{scanId}

Επιστρέφει scan envelope + σύνοψη σοβαρότητας ανά κατηγορία από προεπιλογή. Πέρασε ?include_findings=true για να πάρεις την πλήρη αναφορά (μεγάλη για θορυβώδεις σαρώσεις — προτίμησε το findings endpoint με φίλτρα).

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

Λίστα ευρημάτων

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

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

Μηχανικά αναγνώσιμο spec στο /docs/api/openapi (text/yaml). Ρίξ' το στο αγαπημένο σου codegen (openapi-typescript, openapi-python-client ή οποιοδήποτε OpenAPI 3.1 toolchain) για typed clients.

REST API — Docs · FixWeb