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.

احراز هویت

هر request باید bearer token را در header Authorization داشته باشد. Tokenها از Account → API tokens صادر می‌شوند؛ plaintext دقیقا یک بار هنگام creation به شما نمایش داده می‌شود. Revoking یک token در call بعدی 401 برمی‌گرداند.

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

فرمت token: fxv_ و بعد ۴۳ کاراکتر base64url. در حالت at rest به‌صورت hash با SHA-256 ذخیره می‌شود؛ plaintext هرگز سمت سرور persist نمی‌شود.

Rate limitها

دو window روی هر request احرازشده: burst با ۱۰ req/sec و steady با ۶۰ req/min، هر دو keyed روی bearer hash. اجرای quota (سقف اسکن ماهانه) روی آن قرار می‌گیرد؛ سهمیه‌ها و محدودیت‌ها را ببینید.

صفحه‌بندی

Endpointهای list (/api/v1/scans، /api/v1/findings) از صفحه‌بندی cursor-based استفاده می‌کنند که روی (created_at, id) به ترتیب نزولی keyed شده است. ?cursor=<next_cursor> را بفرستید تا صفحه بعد را fetch کنید. cursor زیر writeهای همزمان درست می‌ماند (بدون OFFSET skew).

شکل خطاها

هر error یک 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

Endpointها

شروع یک اسکن

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

فهرست اسکن‌های شما

GET/api/v1/scans

اسکن‌های org متصل به token فراخوان را برمی‌گرداند، تازه‌ترین‌ها اول. با ?cursor= صفحه‌بندی کنید. limit پیش‌فرض 50، حداکثر 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-..."
}

دریافت یک اسکن

GET/api/v1/scans/{scanId}

به‌صورت پیش‌فرض scan envelope + خلاصه severity برای هر category را برمی‌گرداند. ?include_findings=true را بفرستید تا report کامل را بگیرید (برای scanهای پرسر و صدا بزرگ است؛ بهتر است endpoint findings را با filter استفاده کنید).

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

فهرست findings

GET/api/v1/findings

فهرست قابل filter از findings در همه اسکن‌های org فراخوان. Filterها: severity=critical,high، check_id=secrets.patterns، since=2026-04-01T00:00:00Z. با cursor صفحه‌بندی می‌شود.

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 spec

Spec خوانا برای ماشین در /docs/api/openapi (text/yaml). برای clientهای typed آن را در codegen محبوب خود بگذارید (openapi-typescript، openapi-python-client، یا هر toolchain OpenAPI 3.1).

REST API — Docs · FixVibe