التوثيق · REST API

واجهة برمجة تطبيقات REST

واجهة API تستخدم JSON عبر HTTPS وتتيح كل ما يقدّمه تطبيق vetkit. استخدمها لبدء التدقيق من CI، أو اشتراط تقييم محدد للسماح بالإصدار، أو إرسال تقارير SARIF إلى فحص الكود على GitHub.

نظرة عامة

عنوان URL الأساسي	`https://api.vetkit.dev/v1`
OpenAPI	`https://api.vetkit.dev/v1/openapi.json` — المرجع الكامل القابل للقراءة آليًا لجميع المسارات ومخططات البيانات
التنسيق	محتوى الطلبات والاستجابات بصيغة JSON، وطوابع زمنية وفق ISO 8601، ومعرّفات UUID
الأخطاء	RFC 9457 `application/problem+json`

تغطي هذه الصفحة الأساسيات. استخدم وثيقة OpenAPI لتوليد عميل API أو تصفّح مخططات البيانات. يعتمد خادم MCP على واجهة API نفسها.

المصادقة

أنشئ مفتاحًا من Settings → API keys؛ هذه الصلاحية للمالكين والمسؤولين فقط. أرسل المفتاح كرمز Bearer. ينتمي كل مفتاح إلى مؤسسة واحدة ويحمل نطاقات صلاحيات محددة: repos:read وrepos:write وaudits:read وaudits:write وfindings:read وfindings:write وreports:read.

تحقّق من مفتاحك

$ curl https://api.vetkit.dev/v1/me \  -H "Authorization: Bearer $VETKIT_API_KEY"

تعرض الاستجابة نطاقات صلاحيات المفتاح، والمؤسسة التي ينتمي إليها ضمن organizations. استخدم قيمة id لهذه المؤسسة بوصفها ORG_ID في الأمثلة أدناه.

لا تُضف المفاتيح إلى نظام إدارة الإصدارات

احفظ المفاتيح في مخزن الأسرار لدى مزوّد CI، ولا تضعها في الكود. تُعرض القيمة السرية مرة واحدة وتُخزّن بصمة تجزئتها فقط. إذا تسرّب المفتاح، فأبطله من التطبيق؛ يسري الإبطال فورًا.

التدقيق خطوة بخطوة

1. ابدأ تدقيقًا

مرّر معرّف مستودع مرتبط، مع فرع أو وسم أو SHA لـ commit اختياريًا. عند عدم تحديد ref، يُدقّق الفرع الافتراضي. تُعيد API الاستجابة 202 Accepted مع عملية التدقيق المدرجة في قائمة الانتظار. إذا كان تدقيق commit نفسه قيد التشغيل، تُعاد العملية الحالية بدلًا من إنشاء عملية مكررة.

يحدّد analyzers الفحوصات المطلوب تشغيلها من مجموعة الأمان (posture وgitleaks وsecrets-history وosv وvendored وeol وsupply-chain وsast وsast-community وiac وworkflows)، ومجموعة جودة الكود (code-smells وcomplexity وduplication وtests وdocs وhygiene)، ومجموعة الاستدامة (licenses وdep-health وactivity)، ومجموعة مخاطر كود الذكاء الاصطناعي (hallucinated-deps وai-slop وvibe-stack وllm-app وai-signal)، ومجموعة الجاهزية للإنتاج (resilience وdata-access وoperability). احذف هذا الحقل لتشغيل الفحوصات الافتراضية للمستودع. يعرض GET /orgs/$ORG_ID/analyzers كل فحص ومدى إتاحته على الخادم؛ وطلب فحص غير متاح يُعيد 422 ANALYZER_UNAVAILABLE.

إنشاء تدقيق

$ curl -X POST https://api.vetkit.dev/v1/orgs/$ORG_ID/audits \  -H "Authorization: Bearer $VETKIT_API_KEY" \  -H "Content-Type: application/json" \  -d "{\"repositoryId\": \"$REPO_ID\", \"ref\": \"main\", \"analyzers\": [\"gitleaks\", \"osv\", \"sast\"]}"

202 Accepted

{  "id": "0192f3a4-5b6c-7d8e-9f01-23456789abcd",  "status": "QUEUED",  "ref": "main",  "commitSha": "9f3c2e1b7a0d4c55e2f8a61b3d9c07e4a5b6f812",  "repository": { "fullName": "acme/payments-api", "htmlUrl": "https://github.com/acme/payments-api" },  "analyzers": ["gitleaks", "osv", "sast"],  "steps": [],  "summary": null}

2. استعلم دوريًا حتى يكتمل التدقيق

استعلم كل بضع ثوانٍ حتى تصبح status إحدى القيم SUCCEEDED أو FAILED أو CANCELLED. تتضمن عملية التدقيق المكتملة summary.grade وsummary.overallScore وsummary.suiteScores، أي التقييم والدرجة لكل مجموعة شُغّلت، إضافةً إلى أعداد النتائج بحسب مستوى الخطورة.

الاستعلام الدوري باستخدام curl وjq

$ while :; do$   STATUS=$(curl -s https://api.vetkit.dev/v1/orgs/$ORG_ID/audits/$AUDIT_ID \    -H "Authorization: Bearer $VETKIT_API_KEY" | jq -r .status)$   echo "$STATUS"$   case "$STATUS" in SUCCEEDED|FAILED|CANCELLED) break ;; esac$   sleep 3$ done

3. نزّل التقرير

اختر format=json لملخص قابل للقراءة آليًا، أو markdown لتقرير مقروء، أو sarif لصيغة SARIF 2.1.0، أو pdf لتقرير جاهز للطباعة. لتحديد لغة PDF، اضبط locale على en أو de أو es أو fr أو it أو pt أو ru أو tr.

تنزيل SARIF

$ curl "https://api.vetkit.dev/v1/orgs/$ORG_ID/audits/$AUDIT_ID/report?format=sarif" \  -H "Authorization: Bearer $VETKIT_API_KEY" \  -o vetkit.sarif

ارفع الملف باستخدام إجراء GitHub المسمّى github/codeql-action/upload-sarif لعرض النتائج ضمن تنبيهات فحص الكود في مستودعك.

نقاط النهاية الرئيسية

تُضاف المسارات إلى https://api.vetkit.dev/v1. راجع وثيقة OpenAPI للاطلاع على المعاملات ومخططات الاستجابات.

طريقة HTTP	المسار	الوصف	نطاق الصلاحيات
GET	/me	التعرّف على المفتاح والمؤسسة التي ينتمي إليها	أي نطاق
GET	/orgs/{orgId}/repos	عرض المستودعات المرتبطة	repos:read
POST	/orgs/{orgId}/repos	ربط مستودع باستخدام رابطه	repos:write
GET	/orgs/{orgId}/analyzers	عرض الفحوصات بحسب المجموعة، مع الإتاحة والإعدادات الافتراضية	audits:read
POST	/orgs/{orgId}/audits	بدء تدقيق (202 Accepted)	audits:write
GET	/orgs/{orgId}/audits	عرض عمليات التدقيق مع التصفية بحسب المستودع أو الحالة	audits:read
GET	/orgs/{orgId}/audits/{auditId}	حالة التدقيق وخطواته وملخصه	audits:read
POST	/orgs/{orgId}/audits/{auditId}/cancel	إلغاء تدقيق في قائمة الانتظار أو قيد التشغيل	audits:write
DELETE	/orgs/{orgId}/audits/{auditId}	حذف تدقيق مكتمل وتقريره نهائيًا	audits:write
GET	/orgs/{orgId}/audits/{auditId}/findings	عرض النتائج في صفحات، مع التصفية بحسب الخطورة والمجموعة والفئة وغيرها	findings:read
GET	/orgs/{orgId}/audits/{auditId}/report	جلب التقرير بصيغة json أو markdown أو sarif أو pdf	reports:read

عند ربط مستودع لم يثبّت مالكه تطبيق GitHub، تُعاد الاستجابة 409 INSTALLATION_REQUIRED مع installUrl ضمن details.

التقسيم إلى صفحات

تستخدم نقاط نهاية القوائم التقسيم إلى صفحات بمؤشر. مرّر limit من 1 إلى 100؛ القيمة الافتراضية 25. لجلب الصفحة التالية، مرّر قيمة nextCursor من الاستجابة السابقة في الحقل cursor. وتعني القيمة null في nextCursor أنك وصلت إلى النهاية.

بنية الصفحة

{ "items": [ … ], "nextCursor": "eyJpZCI6…" }

الأخطاء

تستخدم الأخطاء الصيغة application/problem+json مع حقل code ثابت وقابل للقراءة آليًا. أرفق requestId عند التواصل مع الدعم.

403 Forbidden

{  "type": "https://vetkit.dev/problems/insufficient-scope",  "title": "Forbidden",  "status": 403,  "detail": "This API key is missing the audits:write scope.",  "code": "INSUFFICIENT_SCOPE",  "requestId": "req_01J9Z3K8V4M2"}

الرموز الشائعة: API_KEY_INVALID، API_KEY_REVOKED، API_KEY_EXPIRED، INSUFFICIENT_SCOPE، VALIDATION_FAILED، NOT_FOUND، INSTALLATION_REQUIRED، AUDIT_CONCURRENCY_LIMIT وRATE_LIMITED.

حدود معدل الطلبات

لكل مفتاح: 60 طلبًا في الدقيقة افتراضيًا، ويمكن ضبط الحد حتى 600 عند إنشاء المفتاح.
عمليات التدقيق المتزامنة: حتى 3 عمليات تدقيق في قائمة الانتظار أو قيد التشغيل لكل مؤسسة. تجاوز هذا الحد يُعيد 409 AUDIT_CONCURRENCY_LIMIT.
بدء التدقيق: 30 عملية في الساعة لكل مؤسسة.

يُعيد تجاوز حد المعدل الاستجابة 429 RATE_LIMITED مع ترويسة Retry-After. انتظر عدد الثواني المحدد فيها قبل إعادة المحاولة. قد تتغير الحدود خلال المرحلة التجريبية؛ ويعرض قسم التسعير القيم الحالية.