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.

Authentication (සත්‍යාපනය)

සෑම request එකකම Authorization header තුළ bearer token තිබිය යුතුය. Tokens Account → API tokens වෙතින් issue කරයි; plaintext එක creation මත ඔබට හරියටම එක් වරක් පමණක් පෙන්වයි. Token එක revoke කළാൽ ඊළඟ call එකේ 401 return වේ.

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

Token format: fxv_ අනුගමනය කරන base64url characters 43ක්. At rest SHA-256 hash ලෙස stored; plaintext server-side කිසිදා persist නොකරයි.

Rate limits (අනුපාත සීමා)

සෑම authenticated request එකකම windows දෙකක්: 10 req/sec burst සහ 60 req/min steady, දෙකම bearer hash මත keyed. Quota enforcement (per-month scan caps) එය මත layers වේ — Quotas & limits බලන්න.

Pagination (පිටුකරණය)

List endpoints (/api/v1/scans, /api/v1/findings) descending order හි (created_at, id) මත keyed cursor-based pagination භාවිතා කරයි. ඊළඟ page fetch කිරීමට ?cursor=<next_cursor> pass කරන්න. Concurrent writes යටතේ cursor එක නිවැරදිව පවතී (OFFSET skew නැත).

Error shapes (දෝෂ ආකෘති)

සෑම error එකක්ම අවම වශයෙන් error key එකක් සහිත JSON object එකකි.

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 (අන්ත ලක්ෂ්‍ය)

Scan එකක් start කරන්න

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 response

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

ඔබගේ scans list කරන්න

GET/api/v1/scans

Calling token එකට බැඳුණු org සඳහා scans, newest first ලෙස return කරයි. ?cursor= සමඟ paginate කරන්න. Default limit 50, max 100.

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

// 200 response

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

Scan එකක් ලබාගන්න

GET/api/v1/scans/{scanId}

Default ලෙස scan envelope + per-category severity summary return කරයි. Full report ලබාගැනීමට ?include_findings=true pass කරන්න (noisy scans සඳහා large — filters සමඟ findings endpoint භාවිතා කිරීම වඩා හොඳයි).

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

Findings list කරන්න

GET/api/v1/findings

Callerගේ org හි සෑම scan එකකම filterable findings list. 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 response

{
  "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 /docs/api/openapi හි ඇත (text/yaml). Typed clients සඳහා ඔබගේ කැමති codegen (openapi-typescript, openapi-python-client, හෝ ඕනෑම OpenAPI 3.1 toolchain) වෙත drop කරන්න.

REST API — Docs · FixVibe