API reference

The full API reference will be auto-generated from our OpenAPI 3.1 spec the moment the surface is stable. We'd rather ship a placeholder than fake-doc endpoints that might still move. In the meantime, here's the shape, what it'll cover, and what to do today.

الشكل (قابل للتغيير)

REST فوق HTTPS. JSON دخولاً وخروجاً. مصادقة Bearer token مع كل طلب. الإصدار في المسار: /v1/.... حد معدّل حسب التوكن، وتأتي الاستجابة بالـ headers المعتادة X-RateLimit-*.

curl

1# تأخذ كل نقطة نهاية مفتاح API في رأس Authorization2curl https://api.verbumia.ca/v1/projects \3  -H "Authorization: ApiKey vrb_live_<prefix>.<secret>" 5{ "data": [{ "id": "proj_xxx", "name": "Checkout", … }] }

تأتي مفاتيح API من Org Settings → API Keys في لوحة التحكم. نفس المفتاح يصلح لـ CLI، وخادم MCP، والاستدعاءات المباشرة لـ REST — يستهلك API الـ bearer فقط.

الموارد التي ستراها عند الإطلاق

هذه هي الموارد التي ستكشفها V1 API. الشكل الدقيق — الحقول، رموز الأخطاء، التصفح — سيُحسم عند نشر مواصفات OpenAPI.

المورد	ما الذي يمثّله	عمليات V1
Projects	Workspaces. Create وlist وarchive ونقل الـ ownership.	GET · POST · PATCH · DELETE
Locales	مجموعة لغات على مستوى المشروع. إضافة لغة، تعيينها كافتراضية، تفعيلها/تعطيلها للعملاء.	GET · POST · PATCH · DELETE
Namespaces	حِزم منطقية للمفاتيح داخل المشروع (مثل "checkout" و"common").	GET · POST · PATCH · DELETE
Keys	مفاتيح الترجمة مع وصفها وروابط لقطات الشاشة وأقصى طول وقواعد الجمع.	GET · POST · PATCH · DELETE
Translations	قيمة المفتاح لكل لغة. حالات draft وin-review وapproved، وتاريخ المراجعات.	GET · POST · PATCH · DELETE
Missing keys	طابور SDK في الـ runtime. قوائم، تجميع حسب التكرار، وضع علامة triaged.	GET · PATCH
Webhooks	الاشتراك في أحداث الترجمة. V2.	V2

ماذا تفعل اليوم

تقريباً كل ما قد تحتاج إلى API لأجله مكشوف بالفعل عبر CLI أو خادم MCP أو SDK في الـ runtime. استخدمها — عند إطلاق API، يمكن لكودك التحول إلى استدعاءات HTTP مباشرة دون تغيير ما يفعله فعلاً.

CLI

@verbumia/cli

Push وpull وimport وexport — يغطّي معظم احتياجات الأتمتة.

MCP

إعداد Claude Desktop

اقرأ المفاتيح، اقترح ترجمات، راجع diffs الخاصة بالـ PRs من أي وكيل.

SDK

React + i18next

اقرأ الترجمات والتقط المفاتيح الناقصة في الـ runtime لديك.

مرجع

كل الوثائق

فهرس بكل ما نشرناه حتى الآن.

OpenAPI الحيّة للمطوّرين الأوائل

إن كنت تشغّل backend Verbumia محلياً، فإن مواصفات OpenAPI 3.1 الحيّة مكشوفة على:

backend محلي

http://localhost:8820/openapi.json

وجّه Stoplight أو Swagger UI أو Insomnia أو Postman أو أي أداة تفهم OpenAPI إلى ذلك العنوان. الشكل يتحرّك — لذا هذه الصفحة placeholder — لكنه الآن المصدر الموثوق إن أردت استكشاف نقاط النهاية مبكراً.

متى يصل المرجع العام؟

ستُقدَّم مواصفات OpenAPI العامة على https://api.verbumia.ca/openapi.json فور تجميد سطح V1. عندها ستتحول هذه الصفحة من placeholder إلى مرجع مُعرَّض بالكامل (Stoplight أو عارض مشابه فوق المواصفات) — بلا نص تسويقي، فقط كل نقطة نهاية، كل حمولة، كل رمز خطأ، مولَّدة من المصدر.