مرجع الـAPI

يوفّر Patchwire مواصفة OpenAPI 3 كاملة. المرجع التفاعلي على:

https://api.patchwire.app/docs

تلك الصفحة يعرضها Redoc ضد نقطة /openapi.json الحيّة، فهي مطابقة دائماً للـAPI المنشور.

المواصفة الخام على:

https://api.patchwire.app/openapi.json

تستطيع تمريرها إلى مولِّد العميل المفضّل لديك — openapi-generator-cli أو oapi-codegen لـGo أو progenitor لـRust… إلخ.

المصادقة

كل النقاط ما عدا /v1/auth/register و/v1/auth/login و/healthz تتطلّب رمز bearer:

http

Authorization: Bearer <jwt>

الـJWT يُصدر من POST /v1/auth/register ومن POST /v1/orgs/{slug}/auth/login. وهو:

صالح 24 ساعة افتراضياً.
يحمل slug المنظمة ودور المستخدم في الحمولة.
مرتبط بمنظمة واحدة — استدعاء نقطة منظمة أخرى برمزك يعيد 403 مع "token is for a different organization".

أنماط شائعة

نطاق الموارد

كل نقطة لكل منظمة شكلها /v1/orgs/{org_slug}/<resource>:

/v1/orgs/{org_slug}/projects
/v1/orgs/{org_slug}/projects/{project_slug}
/v1/orgs/{org_slug}/projects/{project_slug}/scans
/v1/orgs/{org_slug}/projects/{project_slug}/scans/{scan_id}
/v1/orgs/{org_slug}/projects/{project_slug}/scans/{scan_id}/findings
/v1/orgs/{org_slug}/findings
/v1/orgs/{org_slug}/users

slug المنظمة في الرابط يجب أن يطابق الـslug في JWT.

الأخطاء

كل استجابات الخطأ تتشارك شكلاً واحداً:

json

{
  "error": "bad_request",
  "message": "slug must be 2–40 chars (got 1)"
}

حقل error معرّف ثابت قابل للقراءة الآلية؛ حقل message قد تتغيّر صياغته. استعمل error في مسارات الكود.

قابلية التكرار

نقاط POST ليست مفهرسة-بمعرّف-تكرار. إعادة POST /projects بنفس الـslug تعيد 409. إعادة POST /run-scan تنشئ صف فحص جديد.

أمثلة سريعة

التسجيل

bash

curl -X POST https://api.patchwire.app/v1/auth/register \
  -H 'content-type: application/json' \
  -d '{
    "org_name": "Acme Inc.",
    "org_slug": "acme",
    "email": "you@acme.example",
    "password": "use-a-real-password-here"
  }'

الاستجابة:

json

{
  "token": "eyJ0eXAiOiJKV1Qi…",
  "expires_at": "2026-04-26T09:34:20Z",
  "user": { "id": "…", "email": "…", "role": "admin", "status": "active", … }
}

إنشاء مشروع برمز خاص

bash

curl -X POST https://api.patchwire.app/v1/orgs/acme/projects \
  -H "authorization: Bearer $TOKEN" \
  -H 'content-type: application/json' \
  -d '{
    "slug": "web",
    "name": "Acme web app",
    "repo_url": "https://github.com/acme/web.git",
    "default_branch": "main",
    "access_token": "github_pat_…",
    "access_token_user": "x-access-token"
  }'

الاستجابة لا تحتوي أبداً على access_token ولا access_token_enc — فقط has_access_token: true.

إطلاق فحص يدوياً

bash

curl -X POST https://api.patchwire.app/v1/orgs/acme/projects/web/run-scan \
  -H "authorization: Bearer $TOKEN" \
  -H 'content-type: application/json' \
  -d '{"clone_url":"https://github.com/acme/web.git","branch":"main"}'

الاستجابة 202 Accepted مع صف الفحص الجديد. اسأل GET …/scans/{id} للحالة؛ webhooks لنفس المشروع ستكتب أيضاً في جدول scans.

حدود المعدل

لا توجد حدود معدّل على الـAPI اليوم. نقاط الـwebhooks تقبل ما يرسله الـSCM — عنق الزجاجة عند Patchwire هو إنتاجية الماسحات، لا معدل الطلبات. حدّ مستقبلي سيُضاف قبل الاستخدام التجاري.

مرجع الـAPI ​

المصادقة ​

أنماط شائعة ​

نطاق الموارد ​

الأخطاء ​

قابلية التكرار ​

أمثلة سريعة ​

التسجيل ​

إنشاء مشروع برمز خاص ​

إطلاق فحص يدوياً ​

حدود المعدل ​

مرجع الـAPI

المصادقة

أنماط شائعة

نطاق الموارد

الأخطاء

قابلية التكرار

أمثلة سريعة

التسجيل

إنشاء مشروع برمز خاص

إطلاق فحص يدوياً

حدود المعدل