# مرجع API

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

# مرجع API

تاروت توفر واجهة برمجة تطبيقات REST للوصول البرمجي لجميع ميزات المنصة. واجهة API مبنية على tRPC مع دعم OpenAPI.

## الرابط الأساسي

```
https://tarout.sa/api
```

## المصادقة

جميع طلبات API تتطلب مصادقة عبر مفتاح API أو رمز جلسة.

### مفاتيح API

أنشئ مفتاح API في **الإعدادات ← مفاتيح API**.

```bash
curl https://tarout.sa/api/v1/applications \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### رموز الجلسة

عند استخدام واجهة سطر الأوامر أو المتصفح، تُدار رموز الجلسة تلقائيًا.

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

### التطبيقات

```bash
# عرض التطبيقات
GET /api/v1/applications

# تفاصيل التطبيق
GET /api/v1/applications/:id

# إنشاء تطبيق
POST /api/v1/applications

# نشر تطبيق
POST /api/v1/applications/:id/deploy

# حذف تطبيق
DELETE /api/v1/applications/:id
```

### قواعد البيانات

```bash
# عرض قواعد البيانات
GET /api/v1/databases

# إنشاء قاعدة بيانات
POST /api/v1/databases

# حذف قاعدة بيانات
DELETE /api/v1/databases/:id
```

### النطاقات

```bash
# عرض النطاقات
GET /api/v1/domains

# إضافة نطاق
POST /api/v1/domains

# حذف نطاق
DELETE /api/v1/domains/:id
```

## صيغة الاستجابة

جميع الاستجابات تتبع هذه الصيغة:

```json
{
  "result": {
    "data": { ... }
  }
}
```

## معالجة الأخطاء

الأخطاء تُرجع أكواد حالة HTTP المناسبة:

| الكود | الوصف |
|-------|-------|
| `400` | طلب غير صالح - معاملات غير صحيحة |
| `401` | غير مصرّح - مصادقة مفقودة أو غير صالحة |
| `403` | محظور - صلاحيات غير كافية أو حساب معلّق |
| `404` | غير موجود - المورد غير موجود |
| `429` | تجاوز الحد - طلبات كثيرة جدًا |
| `500` | خطأ داخلي في الخادم |

## حدود المعدل

طلبات API محدودة المعدل لمنع سوء الاستخدام. إذا تجاوزت الحد، ستتلقى استجابة `429` مع رأس `Retry-After`.

## بوابة الذكاء الاصطناعي

بوابة الذكاء الاصطناعي نقطة نهاية متوافقة مع OpenAI لإكمالات المحادثة:

```
https://tarout.sa/api/ai/v1
```

تدعم البوابة `POST /chat/completions` و`GET /models` و`GET /models/{id}`،
ويُحتسب الاستخدام لكل رمز (token) بالريال السعودي من الرصيد المدفوع مسبقًا
لمنظمتك.

### مفتاح واحد لجميع النماذج

مفتاح البوابة (`sk_tarout_...`) غير مرتبط بنموذج بعينه، فالمفتاح نفسه يستدعي
أي نموذج في الكتالوج، ويحدد كل طلب نموذجه عبر الحقل `model`. لكل مفتاح اسم،
وحد إنفاق شهري اختياري بالريال، وتاريخ انتهاء اختياري. والمفاتيح التي أُنشئت
قبل هذا التغيير تعمل هي الأخرى مع جميع النماذج، دون أي خطوات إضافية.

أنشئ مفتاحًا من [لوحة التحكم](https://tarout.sa/dashboard/ai-models/keys)، أو
من سطر الأوامر (يمثّل `--monthly-cap` حد الإنفاق الشهري بالريال):

```sh
tarout ai keys create --name production --monthly-cap 50
```

### استدعاء نموذج عبر حزمة Tarout

```sh
npm install @tarout/ai
```

```ts
import Tarout from "@tarout/ai";

// تقرأ الحزمة المفتاح من TAROUT_API_KEY وتستخدم عنوان البوابة أعلاه افتراضيًا.
const client = new Tarout();

const res = await client.chat.completions.create({
  model: "glm",
  messages: [{ role: "user", content: "مرحبًا!" }],
});

console.log(res.choices[0]?.message.content);
```

لتبديل النموذج، غيّر قيمة `model` فقط، ويبقى المفتاح وكل ما عداه كما هو:

```ts
await client.chat.completions.create({
  model: "deepseek-v4-pro",
  messages: [{ role: "user", content: "مرحبًا!" }],
});
```

### عرض النماذج المتاحة

```bash
curl https://tarout.sa/api/ai/v1/models \
  -H "Authorization: Bearer $TAROUT_API_KEY"
```

تعرض الاستجابة كل النماذج التي يمكنك استدعاؤها الآن. ويستدعي
`models.list()` في أي عميل متوافق مع OpenAI نقطة النهاية نفسها، ويعرض الأمر
`tarout ai models` الكتالوج من سطر الأوامر.

للاستعلام عن نموذج واحد، استخدم معرّفه أو اسمه المستعار. يُرجع الاسم المستعار
النموذج الذي يشير إليه، ويُرجع النموذج غير المتاح حاليًا حالة `404` مع
`error.code` بالقيمة `model_not_found` (وهذا ما يستدعيه `models.retrieve()`):

```bash
curl https://tarout.sa/api/ai/v1/models/glm \
  -H "Authorization: Bearer $TAROUT_API_KEY"
```

### النماذج

اضبط `model` على الاسم المختصر الثابت للنموذج (alias) أو على معرّفه الكامل،
فكلاهما يعمل.

**العالمي**: خمسة نماذج رائدة مفتوحة الأوزان، نموذج من كل مختبر.

| النموذج | الاسم المختصر | المعرّف |
|---------|---------------|---------|
| GLM 5.3 | `glm` | `z-ai/glm-5.3` |
| DeepSeek V4 Pro 0813 | `deepseek-v4-pro` | `deepseek/deepseek-v4-pro-0813` |
| Kimi K3 | `kimi-k3` | `moonshotai/kimi-k3` |
| MiniMax M3 | `minimax-m3` | `minimax/minimax-m3` |
| Qwen 3.8 2.4T A95B | `qwen3` | `qwen/qwen3.8-2.4t-a95b` |

**المملكة العربية السعودية**: مسار مهيأ للاستدلال السريع، وتشير اللاحقة
`-local` إلى نماذجه. قد تكون هذه النماذج غير متاحة مؤقتًا، لذا راجع
`GET /api/ai/v1/models` لمعرفة المتاح منها الآن. الأسماء المختصرة والمعرّفات
الكاملة:

```text
gpt-oss-local        groq/openai/gpt-oss-120b
gpt-oss-20b-local    groq/openai/gpt-oss-20b
qwen3.8-local        groq/qwen/qwen3.8-27b
qwen3.6-local        groq/qwen/qwen3.6-27b
```

### الأخطاء

تستخدم كل الأخطاء صيغة OpenAI:
`{"error": {"message": "...", "type": "...", "code": "..."}}`. وفي أخطاء
البوابة يحمل `type` و`code` القيمة نفسها، مثل `PAYMENT_REQUIRED` (الرصيد لا
يغطي الطلب) و`BUDGET_EXCEEDED` (بلغ المفتاح حده الشهري) و`RATE_LIMIT_EXCEEDED`.
وترسل حالة `429` أيضًا الترويسة `Retry-After` بعدد الثواني المطلوب انتظارها.
وإذا فشل طلب البث بعد بدئه، ينتهي بحدث `data:` واحد يحمل كائن `error` نفسه،
يليه `data: [DONE]`.

إذا طلبت نموذجًا غير معروف أو أُزيل من الكتالوج، تُرجع البوابة حالة HTTP `404`
مع `error.type` بالقيمة `MODEL_NOT_FOUND`، وهذه الرسالة:

```text
Model <id> is not offered. Available models: <comma-separated ids>
```

اضبط `model` على أحد المعرّفات الواردة في الرسالة، أو اختر نموذجًا من
`GET /api/ai/v1/models`. تُرفض النماذج المُزالة، ولا تُحوَّل أبدًا إلى نموذج
آخر. أُزيلت النماذج التالية من الكتالوج العالمي:

```text
glm-flash            z-ai/glm-5.3-flash
deepseek-v4-flash    deepseek/deepseek-v4-flash-0731
kimi-code            moonshotai/kimi-k2.7-code
qwen-flash           qwen/qwen3.8-flash
nemotron             nvidia/nemotron-3-ultra-550b-a55b
```

## اعرف المزيد

- [المصادقة](https://tarout.sa/docs/api/authentication) - دليل المصادقة المفصل.
- [سطر الأوامر](https://tarout.sa/docs/cli) - استخدم واجهة سطر الأوامر للعمليات الشائعة.

---

## Every Tarout agent guide

- [Start Here (Agents)](https://tarout.sa/docs/for-ai/start.md)
- [Overview](https://tarout.sa/docs/for-ai.md)
- [Deploying an app](https://tarout.sa/docs/for-ai/deploy.md)
- [Databases](https://tarout.sa/docs/for-ai/database.md)
- [Object storage](https://tarout.sa/docs/for-ai/storage.md)
- [Custom domains](https://tarout.sa/docs/for-ai/domains.md)
- [Plans and upgrades](https://tarout.sa/docs/for-ai/billing.md)
- [Troubleshooting](https://tarout.sa/docs/for-ai/troubleshoot.md)
- [Agent Onboarding](https://tarout.sa/docs/for-ai/onboarding.md)
- [CLI Reference](https://tarout.sa/docs/for-ai/cli-reference.md)
- [CLI JSON Schema](https://tarout.sa/docs/for-ai/cli-json-schema.md)

Whole corpus in one file: https://tarout.sa/llms-full.txt · index: https://tarout.sa/llms.txt
Any docs page is raw markdown at the same URL + `.md`. Short link to the entry point: https://tarout.sa/deploy.md