// 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.

Autentimine

Iga päring peab kandma bearer tokenit Authorization päises. Tokenid väljastatakse jaotisest Konto → API tokenid; lihttekst kuvatakse sulle loomisel täpselt üks kord. Tokeni tühistamine tagastab järgmisel kõnel 401.

bash

curl -H "Authorization: Bearer fxv_..." \
  https://fixvibe.app/api/v1/scans

Tokeni formaat: fxv_, millele järgneb 43 base64url märki. Puhkeolekus salvestatakse see SHA-256 räsina; lihtteksti serveri poolel kunagi ei säilitata.

Kiiruspiirangud

Iga autenditud päringu puhul on kaks akent: 10 req/sec burst ja 60 req/min steady, mõlemad seotud bearer räsiga. Kvootide jõustamine (kuised skannimispiirid) lisandub peale; vaata Kvoodid ja piirangud.

Lehitsemine

Loendi endpoint'id (/api/v1/scans, /api/v1/findings) kasutavad kursoripõhist lehitsemist võtmega (created_at, id) kahanevas järjekorras. Järgmise lehe saamiseks anna ?cursor=<next_cursor>. Kursor püsib korrektne paralleelsete kirjutuste ajal (OFFSET nihketa).

Veakujud

Iga viga on JSON objekt vähemalt error võtmega.

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'id

Alusta skannimist

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

// 200 vastus

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

Loetle oma skannimised

GET/api/v1/scans

Tagastab kutsuva tokeniga seotud orgi skannimised, uusimad eespool. Lehitse ?cursor= abil. Vaikelimiit 50, maksimum 100.

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

// 200 vastus

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

Hangi skannimine

GET/api/v1/scans/{scanId}

Tagastab vaikimisi skannimise ümbriku + kategooriapõhise tõsiduse kokkuvõtte. Täisraporti saamiseks anna ?include_findings=true (mürarikaste skannimiste puhul suur; eelista leidude endpoint'i filtritega).

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

Loetle leiud

GET/api/v1/findings

Filtreeritav leidude loend kõigist kutsuja orgi skannimistest. Filtrid: severity=critical,high, check_id=secrets.patterns, since=2026-04-01T00:00:00Z. Kursoripõhine lehitsemine.

curl -H "Authorization: Bearer fxv_..." \
  "https://fixvibe.app/api/v1/findings?severity=critical,high&limit=50"

// 200 vastus

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

Masinloetav spetsifikatsioon aadressil /docs/api/openapi (text/yaml). Pane see oma lemmik codegen'i (openapi-typescript, openapi-python-client või mis tahes OpenAPI 3.1 toolchain), et saada tüübitud kliendid.