# مرجع واجهة API

كل مسار يستدعيه تطبيق أو وكيل أو مزوّد هوية: طريقة مصادقته، والنطاق الذي يحتاجه المفتاح، والحقول التي يأخذها، والإجابات التي يعطيها.

## ملف OpenAPI

المرجع نفسه في ملف بصيغة OpenAPI 3.1، لمولّدات الشيفرة واختبارات العقد. ويُبنى من العقد الذي تطابقه اختبارات Azoth نفسها مع المسارات في الاتجاهين: فالمسار الغائب عنه، أو المسار الذي يسمّيه ولا وجود له، يُفشلها.

[openapi.yaml](https://www.azothos.ai/openapi.yaml)

> ملخصات المسارات وأسماء الحقول مكتوبة بالإنجليزية، هنا وفي الملف.

## المصادقة

- `Authorization` — `Bearer <key>`: مفتاح API لمساحة العمل من **الإعدادات › الوصول** — `az_live_…`، أو `az_test_…` في الخطة المجانية. ولا يصل المفتاح ذو النطاقات إلا إلى المسارات التي تغطيها نطاقاته.
- `X-Azoth-API-Key` — `<key>`: المفتاح نفسه في ترويسة خاصة به. وكل مسار يقبل مفتاحًا يقبل الطريقتين.

قراءات لوحة التحكم نفسها — `/api/v1/me` وقراءات GreenOps — تتطلب جلسة مسجّلة، ولا تقبل مفتاحًا أبدًا. وتتطلب مسارات SCIM رمز SCIM الخاص بمساحة العمل ([التزويد عبر SCIM](https://www.azothos.ai/ar/docs/admin#scim)).

## الإجابات والأخطاء

تحمل إجابة الخطأ `error`، وهي جملة، و`code` ثابتًا، و`doc_url` يقود إلى مدخل الرمز في [رموز الأخطاء](https://www.azothos.ai/ar/docs/errors)؛ ويسمّي `400` أيضًا الحقل `field` الذي أخفق. ويجيب حدّ المعدّل بـ `429` مع `retryAfterMs` في الجسم و`Retry-After` في الترويسات. والمسار الذي لا يشغّل النشر وحدته يقول ذلك. يمكن إعادة محاولة استدعاء البوابة غير المتدفق (`/api/v1/chat/completions`، `/api/v1/chat`) بأمان مع ترويس `Idempotency-Key`: خلال الساعة، تتلقى إعادة محاولة استدعاءٍ أُجيب الإجابةَ الأولى نفسها — دون استدعاء ثانٍ للنموذج أو ختم ثانٍ أو إنفاق ثانٍ — متى سمحت سياسة بيانات مساحة العمل لـ Azoth بالاحتفاظ بها؛ وإلا أُبلغت إعادة المحاولة بذلك (`idempotency_replay_unavailable`) مع أثر الاستدعاء الأول.

## المسارات

صفحة لكل جزء من الواجهة، فيها كل مسار من مساراته كاملًا: طريقة مصادقته، والنطاق الذي يحتاجه المفتاح، ومعاملاته وحقول جسمه، وإجاباته ورموزها. وفي الأسفل، كل جزء مع مساراته، سطر لكل مسار، مرتبط بمدخله الكامل. ويتضمن الملف نوع كل حقل وحدوده، وجسم كل إجابة.

## استدعاءات البوابة

استدعاء نموذج عبر البوابة المحكومة — وما يحيط بالاستدعاء: هل يحتاج إلى نموذج، والنموذج الذي يمكن لأول استدعاء استخدامه، واستئناف استدعاء معلّق، وطلب استثناء، والتحقق من الاستناد، وإيصالات خزنتك الخاصة.

[كل مسارات هذا الجزء كاملةً](https://www.azothos.ai/ar/docs/api/gateway)

### `/api/v1/chat`

- [`POST /api/v1/chat/completions`](https://www.azothos.ai/ar/docs/api/gateway#post-api-v1-chat-completions) — The governed gateway, OpenAI-compatible
- [`POST /api/v1/chat`](https://www.azothos.ai/ar/docs/api/gateway#post-api-v1-chat) — The governed gateway with an explicit provider, fallbacks and streaming

### `/api/v1/infer`

- [`POST /api/v1/infer/resume`](https://www.azothos.ai/ar/docs/api/gateway#post-api-v1-infer-resume) — Run a held call once a reviewer approved it
- [`POST /api/v1/infer/preflight`](https://www.azothos.ai/ar/docs/api/gateway#post-api-v1-infer-preflight) — Score whether a request needs a model call at all

### `/api/v1/models`

- [`GET /api/v1/models/defaults`](https://www.azothos.ai/ar/docs/api/gateway#get-api-v1-models-defaults) — Which model a first call can use, per provider

### `/api/v1/exceptions`

- [`POST /api/v1/exceptions`](https://www.azothos.ai/ar/docs/api/gateway#post-api-v1-exceptions) — Ask the rule's owner for a time-limited exception to a refusal
- [`GET /api/v1/exceptions/{id}`](https://www.azothos.ai/ar/docs/api/gateway#get-api-v1-exceptions-id) — Where an exception this key asked for stands

### `/api/v1/grounding`

- [`POST /api/v1/grounding/release`](https://www.azothos.ai/ar/docs/api/gateway#post-api-v1-grounding-release) — Fetch a high-stakes answer the grounding check held, once approved
- [`POST /api/v1/grounding/receipts`](https://www.azothos.ai/ar/docs/api/gateway#post-api-v1-grounding-receipts) — Seal the receipt of a grounding check run on your side

### `/api/v1/vault`

- [`POST /api/v1/vault/receipts`](https://www.azothos.ai/ar/docs/api/gateway#post-api-v1-vault-receipts) — Seal the receipt of a call kept in your own vault

## القياس عن بُعد والتحسين

الإبلاغ عن الاستدعاءات المُجراة خارج البوابة، واختيار نموذج لطلب، والبحث عن الإجابات المخزّنة مؤقتًا وتخزينها، والتحقق من دخول وكيل في حلقة، وضغط المحتوى الطويل، والاستعلام من سوق المزوّدين.

[كل مسارات هذا الجزء كاملةً](https://www.azothos.ai/ar/docs/api/optimisation)

### `/api/ingest`

- [`POST /api/ingest`](https://www.azothos.ai/ar/docs/api/optimisation#post-api-ingest) — Ingest AI usage events

### `/api/arbiter`

- [`POST /api/arbiter/route`](https://www.azothos.ai/ar/docs/api/optimisation#post-api-arbiter-route) — Select optimal model for a request

### `/api/cache`

- [`POST /api/cache/lookup`](https://www.azothos.ai/ar/docs/api/optimisation#post-api-cache-lookup) — Look up a cached answer for a prompt
- [`POST /api/cache/store`](https://www.azothos.ai/ar/docs/api/optimisation#post-api-cache-store) — Store a prompt and its answer in the cache

### `/api/loops`

- [`POST /api/loops/check`](https://www.azothos.ai/ar/docs/api/optimisation#post-api-loops-check) — Check an agent for a loop, reset its counters, or read its state

### `/api/v1/compress`

- [`POST /api/v1/compress`](https://www.azothos.ai/ar/docs/api/optimisation#post-api-v1-compress) — Compress long reasoning content (levels L1 to L3)

### `/api/v1/reconstruct`

- [`POST /api/v1/reconstruct`](https://www.azothos.ai/ar/docs/api/optimisation#post-api-v1-reconstruct) — Reconstruct compressed content from its id

### `/api/v1/marketplace`

- [`GET /api/v1/marketplace`](https://www.azothos.ai/ar/docs/api/optimisation#get-api-v1-marketplace) — The best-fit model of the provider marketplace for your constraints

## الإثبات

قراءة القرارات المختومة، وتصدير ملف التدقيق أو ملف قرار واحد، وجلب المفاتيح العامة التي تتحقق من الإيصالات، وقراءة أدلة Azoth Guard وحوادث مساحة العمل.

[كل مسارات هذا الجزء كاملةً](https://www.azothos.ai/ar/docs/api/proof)

### `/api/v1/journal`

- [`GET /api/v1/journal`](https://www.azothos.ai/ar/docs/api/proof#get-api-v1-journal) — The sealed decisions of the workspace
- [`GET /api/v1/journal/export`](https://www.azothos.ai/ar/docs/api/proof#get-api-v1-journal-export) — The evidence pack, or the signed audit dossier as a ZIP

### `/api/v1/decisions`

- [`POST /api/v1/decisions/export`](https://www.azothos.ai/ar/docs/api/proof#post-api-v1-decisions-export) — The decision dossier of one business decision, as a ZIP

### `/api/proof`

- [`GET /api/proof/keys/{workspaceId}`](https://www.azothos.ai/ar/docs/api/proof#get-api-proof-keys-workspaceid) — A workspace's public receipt keys (JWKS)

### `/api/v1/guard`

- [`GET /api/v1/guard/evidence`](https://www.azothos.ai/ar/docs/api/proof#get-api-v1-guard-evidence) — Azoth Guard's evidence pack, by obligation

### `/api/v1/incidents`

- [`GET /api/v1/incidents`](https://www.azothos.ai/ar/docs/api/proof#get-api-v1-incidents) — The workspace's incidents
- [`POST /api/v1/incidents/{id}/match`](https://www.azothos.ai/ar/docs/api/proof#post-api-v1-incidents-id-match) — Which of your business references an incident touched

## الأنظمة والسياسات

التصريح بأنظمتك (حالات الاستخدام) وقراءتها، مع الاستدعاءات التي جرت خارج ما اعتُمد له أحدها؛ وقراءة الحزم التنظيمية وسياسة البيانات التي يطبّقها SDK.

[كل مسارات هذا الجزء كاملةً](https://www.azothos.ai/ar/docs/api/governance)

### `/api/v1/usecases`

- [`GET /api/v1/usecases`](https://www.azothos.ai/ar/docs/api/governance#get-api-v1-usecases) — The workspace's declared systems (use cases) and their flags
- [`POST /api/v1/usecases`](https://www.azothos.ai/ar/docs/api/governance#post-api-v1-usecases) — Declare a system (use case)
- [`GET /api/v1/usecases/{id}`](https://www.azothos.ai/ar/docs/api/governance#get-api-v1-usecases-id) — One declared system (use case)
- [`PATCH /api/v1/usecases/{id}`](https://www.azothos.ai/ar/docs/api/governance#patch-api-v1-usecases-id) — Always refused — a person reviews a use case, from the dashboard
- [`GET /api/v1/usecases/{id}/divergences`](https://www.azothos.ai/ar/docs/api/governance#get-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`](https://www.azothos.ai/ar/docs/api/governance#get-api-v1-policy-packs) — The regulatory policy packs, or one pack in full

### `/api/v1/governance`

- [`GET /api/v1/governance/config`](https://www.azothos.ai/ar/docs/api/governance#get-api-v1-governance-config) — The workspace's data policy, as the SDK applies it in your process

## الاختبارات وتغييرات النماذج

إدارة مجموعات اختبارات الانحدار وتشغيلها، أو مقارنة نماذج عليها؛ وقراءة عمليات مجموعات المرجع التي تنتظر نظامك عند تغيّر نموذج، وإرسال نتائجها.

[كل مسارات هذا الجزء كاملةً](https://www.azothos.ai/ar/docs/api/testing)

### `/api/v1/regression`

- [`GET /api/v1/regression/suites`](https://www.azothos.ai/ar/docs/api/testing#get-api-v1-regression-suites) — The workspace's regression suites
- [`POST /api/v1/regression/suites`](https://www.azothos.ai/ar/docs/api/testing#post-api-v1-regression-suites) — Create a regression suite
- [`PATCH /api/v1/regression/suites`](https://www.azothos.ai/ar/docs/api/testing#patch-api-v1-regression-suites) — Change a suite's name, description, provider or model
- [`DELETE /api/v1/regression/suites`](https://www.azothos.ai/ar/docs/api/testing#delete-api-v1-regression-suites) — Delete a suite and its runs
- [`GET /api/v1/regression/runs`](https://www.azothos.ai/ar/docs/api/testing#get-api-v1-regression-runs) — The latest regression runs, newest first
- [`POST /api/v1/regression/runs`](https://www.azothos.ai/ar/docs/api/testing#post-api-v1-regression-runs) — Run a suite, or compare 2 to 5 models on it
- [`GET /api/v1/regression/runs/{id}`](https://www.azothos.ai/ar/docs/api/testing#get-api-v1-regression-runs-id) — One run, with each case's result

### `/api/v1/reference-sets`

- [`GET /api/v1/reference-sets/pending`](https://www.azothos.ai/ar/docs/api/testing#get-api-v1-reference-sets-pending) — The reference-set runs waiting for your system (model change control)
- [`POST /api/v1/reference-sets/receipts`](https://www.azothos.ai/ar/docs/api/testing#post-api-v1-reference-sets-receipts) — Post the results of a reference-set run your system ran

## الوكلاء وMCP

قراءة الإنفاق والوفورات لكل وكيل، واستدعاء الأدوات عبر بوابة MCP المحكومة، وتشغيل أدوات القراءة الخاصة بالمساعد.

[كل مسارات هذا الجزء كاملةً](https://www.azothos.ai/ar/docs/api/agents)

### `/api/v1/agents`

- [`GET /api/v1/agents`](https://www.azothos.ai/ar/docs/api/agents#get-api-v1-agents) — Spend and savings per agent

### `/api/v1/mcp`

- [`GET /api/v1/mcp`](https://www.azothos.ai/ar/docs/api/agents#get-api-v1-mcp) — Not used — the MCP gateway opens no stream (405)
- [`POST /api/v1/mcp`](https://www.azothos.ai/ar/docs/api/agents#post-api-v1-mcp) — The governed MCP gateway (Streamable HTTP, tools only)
- [`DELETE /api/v1/mcp`](https://www.azothos.ai/ar/docs/api/agents#delete-api-v1-mcp) — Not used — the MCP gateway keeps no session (405)

### `/api/v1/insights`

- [`POST /api/v1/insights/{tool}`](https://www.azothos.ai/ar/docs/api/agents#post-api-v1-insights-tool) — Run one of the assistant's read tools

## الاستخدام والإنفاق والبصمة

قراءة آثار الاستخدام، وتقرير الإنفاق والوفورات، والميزانيات واستهلاكها، والبصمة التقديرية من الطاقة والكربون.

[كل مسارات هذا الجزء كاملةً](https://www.azothos.ai/ar/docs/api/usage)

### `/api/v1/usage`

- [`GET /api/v1/usage`](https://www.azothos.ai/ar/docs/api/usage#get-api-v1-usage) — The workspace's usage traces, newest first (paginated)

### `/api/v1/report`

- [`GET /api/v1/report`](https://www.azothos.ai/ar/docs/api/usage#get-api-v1-report) — The spend and savings report of the workspace

### `/api/v1/budgets`

- [`GET /api/v1/budgets`](https://www.azothos.ai/ar/docs/api/usage#get-api-v1-budgets) — The workspace's budgets and their use

### `/api/v1/greenops`

- [`GET /api/v1/greenops/footprint`](https://www.azothos.ai/ar/docs/api/usage#get-api-v1-greenops-footprint) — The workspace's estimated energy and carbon footprint, over an API key
- [`GET /api/v1/greenops/energy`](https://www.azothos.ai/ar/docs/api/usage#get-api-v1-greenops-energy) — Energy per day and per strategy, and the workspace's energy budget
- [`GET /api/v1/greenops/summary`](https://www.azothos.ai/ar/docs/api/usage#get-api-v1-greenops-summary) — GreenOps key figures (the dashboard's read)
- [`GET /api/v1/greenops/carbon`](https://www.azothos.ai/ar/docs/api/usage#get-api-v1-greenops-carbon) — Estimated carbon totals and their monthly trend (the dashboard's read)
- [`GET /api/v1/greenops/provider-efficiency`](https://www.azothos.ai/ar/docs/api/usage#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`](https://www.azothos.ai/ar/docs/api/usage#get-api-v1-greenops-replay-savings) — Energy saved by reusing answers (the dashboard's read)
- [`GET /api/v1/greenops/abatement`](https://www.azothos.ai/ar/docs/api/usage#get-api-v1-greenops-abatement) — Avoided CO₂ with its traceability (the dashboard's read)
- [`GET /api/v1/greenops`](https://www.azothos.ai/ar/docs/api/usage#get-api-v1-greenops) — مُهمَل — Deprecated: use /api/v1/greenops/summary

## الخدمة والحساب

التحقق من أن الخدمة تعمل، ومعرفة الوحدات الجاهزة للإنتاج، وتصدير بيانات مساحة العمل، وقراءة حسابك الخاص أو محوه.

[كل مسارات هذا الجزء كاملةً](https://www.azothos.ai/ar/docs/api/account)

### `/api/health`

- [`GET /api/health`](https://www.azothos.ai/ar/docs/api/account#get-api-health) — Health check, for uptime monitors

### `/api/v1/system`

- [`GET /api/v1/system/modules`](https://www.azothos.ai/ar/docs/api/account#get-api-v1-system-modules) — Which modules are production-grade, beta or experimental

### `/api/v1/export`

- [`GET /api/v1/export`](https://www.azothos.ai/ar/docs/api/account#get-api-v1-export) — The workspace's data, for portability (GDPR art. 20)

### `/api/v1/me`

- [`GET /api/v1/me`](https://www.azothos.ai/ar/docs/api/account#get-api-v1-me) — Your personal data (GDPR art. 15) — signed in, never an API key
- [`DELETE /api/v1/me`](https://www.azothos.ai/ar/docs/api/account#delete-api-v1-me) — Erase your account (GDPR art. 17) — signed in, never an API key

## التزويد عبر SCIM

إنشاء المستخدمين والمجموعات وتحديثهم وإزالتهم من مزوّد هويتك، برمز SCIM الخاص بمساحة العمل.

[كل مسارات هذا الجزء كاملةً](https://www.azothos.ai/ar/docs/api/scim)

### `/api/scim/v2`

- [`GET /api/scim/v2/Users`](https://www.azothos.ai/ar/docs/api/scim#get-api-scim-v2-users) — SCIM: list users (filter, paginate)
- [`POST /api/scim/v2/Users`](https://www.azothos.ai/ar/docs/api/scim#post-api-scim-v2-users) — SCIM: create + provision a user
- [`GET /api/scim/v2/Users/{id}`](https://www.azothos.ai/ar/docs/api/scim#get-api-scim-v2-users-id) — SCIM: get a user
- [`PUT /api/scim/v2/Users/{id}`](https://www.azothos.ai/ar/docs/api/scim#put-api-scim-v2-users-id) — SCIM: replace a user
- [`PATCH /api/scim/v2/Users/{id}`](https://www.azothos.ai/ar/docs/api/scim#patch-api-scim-v2-users-id) — SCIM: patch a user (e.g. deactivate via active=false)
- [`DELETE /api/scim/v2/Users/{id}`](https://www.azothos.ai/ar/docs/api/scim#delete-api-scim-v2-users-id) — SCIM: delete (deprovision) a user
- [`GET /api/scim/v2/Groups`](https://www.azothos.ai/ar/docs/api/scim#get-api-scim-v2-groups) — SCIM: list groups
- [`POST /api/scim/v2/Groups`](https://www.azothos.ai/ar/docs/api/scim#post-api-scim-v2-groups) — SCIM: create a group
- [`GET /api/scim/v2/Groups/{id}`](https://www.azothos.ai/ar/docs/api/scim#get-api-scim-v2-groups-id) — SCIM: get a group
- [`PATCH /api/scim/v2/Groups/{id}`](https://www.azothos.ai/ar/docs/api/scim#patch-api-scim-v2-groups-id) — SCIM: patch a group (membership changes)
- [`DELETE /api/scim/v2/Groups/{id}`](https://www.azothos.ai/ar/docs/api/scim#delete-api-scim-v2-groups-id) — SCIM: delete a group
- [`GET /api/scim/v2/ServiceProviderConfig`](https://www.azothos.ai/ar/docs/api/scim#get-api-scim-v2-serviceproviderconfig) — SCIM: service provider configuration (RFC 7643 §5)
- [`GET /api/scim/v2/ResourceTypes`](https://www.azothos.ai/ar/docs/api/scim#get-api-scim-v2-resourcetypes) — SCIM: supported resource types
- [`GET /api/scim/v2/ResourceTypes/{id}`](https://www.azothos.ai/ar/docs/api/scim#get-api-scim-v2-resourcetypes-id) — SCIM: a single resource type
- [`GET /api/scim/v2/Schemas`](https://www.azothos.ai/ar/docs/api/scim#get-api-scim-v2-schemas) — SCIM: supported schemas
- [`GET /api/scim/v2/Schemas/{id}`](https://www.azothos.ai/ar/docs/api/scim#get-api-scim-v2-schemas-id) — SCIM: a single schema definition
