// docs / rest api

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

Fakamo'oni'i

Kuo pau ke 'ave 'e request kotoa ha bearer token 'i he Authorization header. Tokens 'oku issued mei Account → API tokens; 'oku shown e plaintext kiate koe exactly once 'i creation. Revoking a token returns 401 'i he next call.

bash

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

Token format: fxv_ followed by 43 base64url characters. Stored at rest as a SHA-256 hash; 'oku 'ikai persist e plaintext server-side.

Ngaahi rate limits

Two windows on every authenticated request: 10 req/sec burst mo 60 req/min steady, both keyed on the bearer hash. Quota enforcement (per-month scan caps) layers on top — see Quotas & limits.

Fakapeesi

List endpoints (/api/v1/scans, /api/v1/findings) use cursor-based pagination keyed on (created_at, id) in descending order. Pass ?cursor=<next_cursor> ke fetch e next page. 'Oku nofo tonu e cursor under concurrent writes (no OFFSET skew).

Ngaahi fōtunga error

Error kotoa ko ha JSON object mo ha error key 'i he si'isi'i taha.

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

Ngaahi endpoints

Start ha scan

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 tali

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

List ho'o scans

GET/api/v1/scans

Returns scans for the org tied to the calling token, newest first. Paginate with ?cursor=. Default limit 50, max 100.

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

// 200 tali

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

GET/api/v1/scans/{scanId}

Returns scan envelope + per-category severity summary by default. Pass ?include_findings=true to get the full report (large for noisy scans — prefer the findings endpoint with filters).

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

List e findings

GET/api/v1/findings

Filterable findings list across every scan in the caller's org. Filters: severity=critical,high, check_id=secrets.patterns, since=2026-04-01T00:00:00Z. Cursor-paginated.

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

// 200 tali

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

Machine-readable spec 'i /docs/api/openapi (text/yaml). Drop into ho'o favourite codegen (openapi-typescript, openapi-python-client, pe ha OpenAPI 3.1 toolchain) ma'a typed clients.