// docs / rest api

واجهة REST API

تم مصادقة الحامل JSON API لأتمتة المسح الضوئي وحالة المسح الضوئي والنتائج. تتوفر عمليات الفحص السلبي من خلال REST؛ تتوفر عمليات الفحص النشطة للخطط المدفوعة فقط بعد التحقق من النطاق والترخيص به بشكل صريح في لوحة المعلومات.

المصادقة

يجب أن يحمل كل طلب رمز 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

يفرض فحصًا سلبيًا بشكل افتراضي. بالنسبة للنطاقات التي تم التحقق منها والتي تتمتع بتفويض نشط، يمكن للخطط المدفوعة أن تطلب الوضع النشط. يعود فورًا بمعرف المسح الموجود في قائمة الانتظار؛ استطلاع GET /api/v1/scans/[scanId] حتى 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) للحصول على عملاء مضبوطين الأنواع.