FixVibe

// docs / rest api

REST API

Bearer-authenticated JSON API for scan automation, scan status, and findings. Passive scans are available through REST; active scans are available for paid plans only after the domain is verified and explicitly authorized in the dashboard.

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 fxv_..." \
  https://fixvibe.app/api/v1/scans

Format token: fxv_ 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 by default. For verified domains with active authorization, paid plans can request active mode. Returns immediately with a queued scan id; poll GET /api/v1/scans/[scanId] until status === "completed".

curl -X POST https://fixvibe.app/api/v1/scans \
  -H "Authorization: Bearer fxv_..." \
  -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 fxv_..." \
  "https://fixvibe.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 fxv_..." \
  https://fixvibe.app/api/v1/scans/8f1c4e2a-8c3a-4b6f-9c0d-9b1e8f3c2a4d

Listează constatările

GET/api/v1/findings

Listă filtrabilă de constatări din toate scanările organizației apelantului. Filtre: severity=critical,high, check_id=secrets.patterns, since=2026-04-01T00:00:00Z. Paginată cu cursor.

curl -H "Authorization: Bearer fxv_..." \
  "https://fixvibe.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 · FixVibe