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.

المصادقة

يجب أن يحمل كل طلب رمز Bearer في ترويسة Authorization. تصدر الرموز من الحساب → رموز API؛ وتُعرض القيمة النصية لك مرة واحدة فقط عند الإنشاء. إلغاء رمز يعيد 401 في الاستدعاء التالي.

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

صيغة الرمز: fxv_ متبوعة بـ 43 محرف base64url. يُخزن ساكنًا كتجزئة SHA-256؛ ولا تُحفظ القيمة النصية أبدًا من جهة الخادم.

حدود المعدل

نافذتان على كل طلب مصادق عليه: اندفاع 10 طلبات/ثانية وثابت 60 طلبًا/دقيقة، وكلاهما مبني على تجزئة Bearer. يضاف فرض الحصة (حدود الفحوص الشهرية لكل باقة) فوق ذلك — راجع الحصص والحدود.

ترقيم الصفحات

تستخدم نقاط نهاية القوائم (/api/v1/scans، /api/v1/findings) ترقيم صفحات قائمًا على المؤشر ومبنيًا على (created_at, id) بترتيب تنازلي. مرّر ?cursor=<next_cursor> لجلب الصفحة التالية. يبقى المؤشر صحيحًا تحت الكتابات المتزامنة (بلا انحراف OFFSET).

أشكال الأخطاء

كل خطأ هو كائن JSON يحتوي على الأقل على مفتاح 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

نقاط النهاية

بدء فحص

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

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

سرد فحوصك

GET/api/v1/scans

يعيد الفحوص للمؤسسة المرتبطة بالرمز المستدعي، الأحدث أولًا. رقّم الصفحات باستخدام ?cursor=. الحد الافتراضي 50، والأقصى 100.

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

// استجابة 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-..."
}

جلب فحص

GET/api/v1/scans/{scanId}

يعيد غلاف الفحص + ملخص الشدة لكل فئة افتراضيًا. مرّر ?include_findings=true للحصول على التقرير الكامل (كبير للفحوص كثيرة الضوضاء — فضّل نقطة نهاية النتائج مع المرشحات).

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

سرد النتائج

GET/api/v1/findings

قائمة نتائج قابلة للترشيح عبر كل فحص في مؤسسة المستدعي. المرشحات: severity=critical,high، check_id=secrets.patterns، since=2026-04-01T00:00:00Z. بترقيم صفحات بالمؤشر.

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

// استجابة 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
}

مواصفة OpenAPI

مواصفة قابلة للقراءة آليًا في /docs/api/openapi (text/yaml). ضعها في مولد الشفرة المفضل لديك (openapi-typescript أو openapi-python-client أو أي سلسلة أدوات OpenAPI 3.1) للحصول على عملاء مضبوطين الأنواع.

واجهة REST API — Docs · FixVibe