SDK وسطر الأوامر
مرجع واجهة API
كل مسار يستدعيه تطبيق أو وكيل أو مزوّد هوية: طريقة مصادقته، والنطاق الذي يحتاجه المفتاح، والحقول التي يأخذها، والإجابات التي يعطيها.
ملف OpenAPI
المرجع نفسه في ملف بصيغة OpenAPI 3.1، لمولّدات الشيفرة واختبارات العقد. ويُبنى من العقد الذي تطابقه اختبارات Azoth نفسها مع المسارات في الاتجاهين: فالمسار الغائب عنه، أو المسار الذي يسمّيه ولا وجود له، يُفشلها.
ملخصات المسارات وأسماء الحقول مكتوبة بالإنجليزية، هنا وفي الملف.
المصادقة
AuthorizationBearer <key>: مفتاح API لمساحة العمل من الإعدادات › الوصول — az_live_…، أو az_test_… في الخطة المجانية. ولا يصل المفتاح ذو النطاقات إلا إلى المسارات التي تغطيها نطاقاته.X-Azoth-API-Key<key>: المفتاح نفسه في ترويسة خاصة به. وكل مسار يقبل مفتاحًا يقبل الطريقتين.قراءات لوحة التحكم نفسها — /api/v1/me وقراءات GreenOps — تتطلب جلسة مسجّلة، ولا تقبل مفتاحًا أبدًا. وتتطلب مسارات SCIM رمز SCIM الخاص بمساحة العمل (التزويد عبر SCIM).
الإجابات والأخطاء
تحمل إجابة الخطأ error، وهي جملة، وcode ثابتًا، وdoc_url يقود إلى مدخل الرمز في رموز الأخطاء؛ ويسمّي 400 أيضًا الحقل field الذي أخفق. ويجيب حدّ المعدّل بـ 429 مع retryAfterMs في الجسم وRetry-After في الترويسات. والمسار الذي لا يشغّل النشر وحدته يقول ذلك. يمكن إعادة محاولة استدعاء البوابة غير المتدفق (/api/v1/chat/completions، /api/v1/chat) بأمان مع ترويس Idempotency-Key: خلال الساعة، تتلقى إعادة محاولة استدعاءٍ أُجيب الإجابةَ الأولى نفسها — دون استدعاء ثانٍ للنموذج أو ختم ثانٍ أو إنفاق ثانٍ — متى سمحت سياسة بيانات مساحة العمل لـ Azoth بالاحتفاظ بها؛ وإلا أُبلغت إعادة المحاولة بذلك (idempotency_replay_unavailable) مع أثر الاستدعاء الأول.
المسارات
صفحة لكل جزء من الواجهة، فيها كل مسار من مساراته كاملًا: طريقة مصادقته، والنطاق الذي يحتاجه المفتاح، ومعاملاته وحقول جسمه، وإجاباته ورموزها. وفي الأسفل، كل جزء مع مساراته، سطر لكل مسار، مرتبط بمدخله الكامل. ويتضمن الملف نوع كل حقل وحدوده، وجسم كل إجابة.
استدعاءات البوابة
استدعاء نموذج عبر البوابة المحكومة — وما يحيط بالاستدعاء: هل يحتاج إلى نموذج، والنموذج الذي يمكن لأول استدعاء استخدامه، واستئناف استدعاء معلّق، وطلب استثناء، والتحقق من الاستناد، وإيصالات خزنتك الخاصة.
/api/v1/chat
POST /api/v1/chat/completions— The governed gateway, OpenAI-compatiblePOST /api/v1/chat— The governed gateway with an explicit provider, fallbacks and streaming
/api/v1/infer
POST /api/v1/infer/resume— Run a held call once a reviewer approved itPOST /api/v1/infer/preflight— Score whether a request needs a model call at all
/api/v1/models
GET /api/v1/models/defaults— Which model a first call can use, per provider
/api/v1/exceptions
POST /api/v1/exceptions— Ask the rule's owner for a time-limited exception to a refusalGET /api/v1/exceptions/{id}— Where an exception this key asked for stands
/api/v1/grounding
POST /api/v1/grounding/release— Fetch a high-stakes answer the grounding check held, once approvedPOST /api/v1/grounding/receipts— Seal the receipt of a grounding check run on your side
/api/v1/vault
POST /api/v1/vault/receipts— Seal the receipt of a call kept in your own vault
القياس عن بُعد والتحسين
الإبلاغ عن الاستدعاءات المُجراة خارج البوابة، واختيار نموذج لطلب، والبحث عن الإجابات المخزّنة مؤقتًا وتخزينها، والتحقق من دخول وكيل في حلقة، وضغط المحتوى الطويل، والاستعلام من سوق المزوّدين.
/api/ingest
POST /api/ingest— Ingest AI usage events
/api/arbiter
POST /api/arbiter/route— Select optimal model for a request
/api/cache
POST /api/cache/lookup— Look up a cached answer for a promptPOST /api/cache/store— Store a prompt and its answer in the cache
/api/loops
POST /api/loops/check— Check an agent for a loop, reset its counters, or read its state
/api/v1/compress
POST /api/v1/compress— Compress long reasoning content (levels L1 to L3)
/api/v1/reconstruct
POST /api/v1/reconstruct— Reconstruct compressed content from its id
/api/v1/marketplace
GET /api/v1/marketplace— The best-fit model of the provider marketplace for your constraints
الإثبات
قراءة القرارات المختومة، وتصدير ملف التدقيق أو ملف قرار واحد، وجلب المفاتيح العامة التي تتحقق من الإيصالات، وقراءة أدلة Azoth Guard وحوادث مساحة العمل.
/api/v1/journal
GET /api/v1/journal— The sealed decisions of the workspaceGET /api/v1/journal/export— The evidence pack, or the signed audit dossier as a ZIP
/api/v1/decisions
POST /api/v1/decisions/export— The decision dossier of one business decision, as a ZIP
/api/proof
GET /api/proof/keys/{workspaceId}— A workspace's public receipt keys (JWKS)
/api/v1/guard
GET /api/v1/guard/evidence— Azoth Guard's evidence pack, by obligation
/api/v1/incidents
GET /api/v1/incidents— The workspace's incidentsPOST /api/v1/incidents/{id}/match— Which of your business references an incident touched
الأنظمة والسياسات
التصريح بأنظمتك (حالات الاستخدام) وقراءتها، مع الاستدعاءات التي جرت خارج ما اعتُمد له أحدها؛ وقراءة الحزم التنظيمية وسياسة البيانات التي يطبّقها SDK.
/api/v1/usecases
GET /api/v1/usecases— The workspace's declared systems (use cases) and their flagsPOST /api/v1/usecases— Declare a system (use case)GET /api/v1/usecases/{id}— One declared system (use case)PATCH /api/v1/usecases/{id}— Always refused — a person reviews a use case, from the dashboardGET /api/v1/usecases/{id}/divergences— The sealed calls that ran outside what a use case was approved for
/api/v1/policy
GET /api/v1/policy/packs— The regulatory policy packs, or one pack in full
/api/v1/governance
GET /api/v1/governance/config— The workspace's data policy, as the SDK applies it in your process
الاختبارات وتغييرات النماذج
إدارة مجموعات اختبارات الانحدار وتشغيلها، أو مقارنة نماذج عليها؛ وقراءة عمليات مجموعات المرجع التي تنتظر نظامك عند تغيّر نموذج، وإرسال نتائجها.
/api/v1/regression
GET /api/v1/regression/suites— The workspace's regression suitesPOST /api/v1/regression/suites— Create a regression suitePATCH /api/v1/regression/suites— Change a suite's name, description, provider or modelDELETE /api/v1/regression/suites— Delete a suite and its runsGET /api/v1/regression/runs— The latest regression runs, newest firstPOST /api/v1/regression/runs— Run a suite, or compare 2 to 5 models on itGET /api/v1/regression/runs/{id}— One run, with each case's result
/api/v1/reference-sets
GET /api/v1/reference-sets/pending— The reference-set runs waiting for your system (model change control)POST /api/v1/reference-sets/receipts— Post the results of a reference-set run your system ran
الوكلاء وMCP
قراءة الإنفاق والوفورات لكل وكيل، واستدعاء الأدوات عبر بوابة MCP المحكومة، وتشغيل أدوات القراءة الخاصة بالمساعد.
/api/v1/agents
GET /api/v1/agents— Spend and savings per agent
/api/v1/mcp
GET /api/v1/mcp— Not used — the MCP gateway opens no stream (405)POST /api/v1/mcp— The governed MCP gateway (Streamable HTTP, tools only)DELETE /api/v1/mcp— Not used — the MCP gateway keeps no session (405)
/api/v1/insights
POST /api/v1/insights/{tool}— Run one of the assistant's read tools
الاستخدام والإنفاق والبصمة
قراءة آثار الاستخدام، وتقرير الإنفاق والوفورات، والميزانيات واستهلاكها، والبصمة التقديرية من الطاقة والكربون.
/api/v1/usage
GET /api/v1/usage— The workspace's usage traces, newest first (paginated)
/api/v1/report
GET /api/v1/report— The spend and savings report of the workspace
/api/v1/budgets
GET /api/v1/budgets— The workspace's budgets and their use
/api/v1/greenops
GET /api/v1/greenops/footprint— The workspace's estimated energy and carbon footprint, over an API keyGET /api/v1/greenops/energy— Energy per day and per strategy, and the workspace's energy budgetGET /api/v1/greenops/summary— GreenOps key figures (the dashboard's read)GET /api/v1/greenops/carbon— Estimated carbon totals and their monthly trend (the dashboard's read)GET /api/v1/greenops/provider-efficiency— Energy per 1,000 tokens, per provider and model (the dashboard's read)GET /api/v1/greenops/replay-savings— Energy saved by reusing answers (the dashboard's read)GET /api/v1/greenops/abatement— Avoided CO₂ with its traceability (the dashboard's read)GET /api/v1/greenops— مُهمَل — Deprecated: use /api/v1/greenops/summary
الخدمة والحساب
التحقق من أن الخدمة تعمل، ومعرفة الوحدات الجاهزة للإنتاج، وتصدير بيانات مساحة العمل، وقراءة حسابك الخاص أو محوه.
/api/health
GET /api/health— Health check, for uptime monitors
/api/v1/system
GET /api/v1/system/modules— Which modules are production-grade, beta or experimental
/api/v1/export
GET /api/v1/export— The workspace's data, for portability (GDPR art. 20)
/api/v1/me
GET /api/v1/me— Your personal data (GDPR art. 15) — signed in, never an API keyDELETE /api/v1/me— Erase your account (GDPR art. 17) — signed in, never an API key
التزويد عبر SCIM
إنشاء المستخدمين والمجموعات وتحديثهم وإزالتهم من مزوّد هويتك، برمز SCIM الخاص بمساحة العمل.
/api/scim/v2
GET /api/scim/v2/Users— SCIM: list users (filter, paginate)POST /api/scim/v2/Users— SCIM: create + provision a userGET /api/scim/v2/Users/{id}— SCIM: get a userPUT /api/scim/v2/Users/{id}— SCIM: replace a userPATCH /api/scim/v2/Users/{id}— SCIM: patch a user (e.g. deactivate via active=false)DELETE /api/scim/v2/Users/{id}— SCIM: delete (deprovision) a userGET /api/scim/v2/Groups— SCIM: list groupsPOST /api/scim/v2/Groups— SCIM: create a groupGET /api/scim/v2/Groups/{id}— SCIM: get a groupPATCH /api/scim/v2/Groups/{id}— SCIM: patch a group (membership changes)DELETE /api/scim/v2/Groups/{id}— SCIM: delete a groupGET /api/scim/v2/ServiceProviderConfig— SCIM: service provider configuration (RFC 7643 §5)GET /api/scim/v2/ResourceTypes— SCIM: supported resource typesGET /api/scim/v2/ResourceTypes/{id}— SCIM: a single resource typeGET /api/scim/v2/Schemas— SCIM: supported schemasGET /api/scim/v2/Schemas/{id}— SCIM: a single schema definition