---
title: "مواصفة OpenAPI وعملاء TypeScript"
description: "مواصفة OpenAPI 3.1.0 قابلة للقراءة آليًا لواجهة Minds API. أنشئ عملاء TypeScript بأنواع محددة أو مرّر ملف JSON مباشرةً إلى نموذج LLM الخاص بك."
---

# OpenAPI Spec

توفّر واجهة Minds العامة مواصفة OpenAPI 3.1.0 قابلة للقراءة آليًا. ابنِ عملاء بأنواع محددة أو سلّم ملف JSON إلى نموذج LLM — نفس مصدر الحقيقة الذي يستند إليه هذا التوثيق.

## Endpoint

<table>
<thead>
  <tr>
    <th>
      URL
    </th>
    
    <th>
      ما الذي تحصل عليه
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        https://getminds.ai/_openapi.json
      </code>
    </td>
    
    <td>
      مواصفة JSON بصيغة OpenAPI 3.1.0. مرّرها إلى أي مولّد.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        https://getminds.ai/_openapi-3.0.json
      </code>
    </td>
    
    <td>
      عرض توافق OpenAPI 3.0.2 مُنشأ لأدوات الاستيراد مثل RapidAPI.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        https://getminds.ai/api/v1/openapi.json
      </code>
    </td>
    
    <td>
      المواصفة نفسها، مُقدَّمة إلى جانب نقاط النهاية التي تصفها. لا حاجة إلى مفتاح API.
    </td>
  </tr>
</tbody>
</table>

تتضمّن المواصفة فقط نقاط النهاية العامة `/api/v1/**` التي تعلن عن بيانات OpenAPI الوصفية. أمّا نقاط النهاية الداخلية (admin وdebug وcron وMCP وغيرها) فهي مستبعدة.

## المصادقة

كل عملية في المواصفة محميّة بـ `ApiKeyAuth` — أرسل مفتاح API الشخصي الخاص بك بصيغة bearer token:

```http
Authorization: Bearer minds_…_key
```

أنشئ مفتاحًا من [الإعدادات ← مفاتيح API](/settings/api-keys). راجع [المصادقة](/docs/api/authentication) للاطلاع على التدفّق الكامل.

## إنشاء عميل TypeScript

أسرع طريقة: استخدم [`openapi-typescript`](https://openapi-ts.dev/) لتوليد أنواع صارمة من المواصفة الحيّة.

```bash
npx openapi-typescript https://getminds.ai/_openapi.json -o minds.d.ts
```

ثم استخدمها مع `openapi-fetch` للحصول على عميل بأنواع كاملة:

```ts
import createClient from 'openapi-fetch'
import type { paths } from './minds'

const client = createClient<paths>({
  baseUrl: 'https://api.getminds.ai',
  headers: { Authorization: `Bearer ${process.env.MINDS_API_KEY}` },
})

// All params + responses are typed from the live spec.
const { data, error } = await client.GET('/api/v1/minds', {
  params: { query: { limit: 10 } },
})
```

تفضّل SDK في وقت التشغيل؟ يعمل أي مولّد متوافق مع OpenAPI 3.1 — [`openapi-generator`](https://openapi-generator.tech/) و[`orval`](https://orval.dev/) و[`kubb`](https://www.kubb.dev/) وغيرها.

## استخدامها مع نموذج LLM

مواصفة JSON صغيرة بما يكفي لإسقاطها داخل محادثة:

```bash
curl -s https://getminds.ai/_openapi.json | pbcopy
```

ثم الصقها في ChatGPT / Claude / Cursor مع موجّه مثل:

> هذه هي مواصفة OpenAPI لواجهة Minds API. اكتب لي سكربت Python يسرد الـ sparks الخاصة بي ويطبع أسماءها.

تتضمّن المواصفة مخططات الطلب/الاستجابة، وأمثلة على الحمولات، وعقد المصادقة عبر bearer token — لدى النموذج كل ما يحتاجه.

## التغطية

تسرد المواصفة كل نقطة نهاية ضمن `/api/v1/**`. تأتي المسارات بمخططات طلب/استجابة كاملة عندما تحمل كتلة `defineRouteMeta`؛ أمّا المسارات التي لا تحملها فتظهر بالمسار + الطريقة فقط مع وصف عام. نعمل على تغطية السطح تدريجيًا بمرور الوقت — وتبقى المواصفة دقيقة في كل الأحوال لأنها مولّدة من الموجّه الحيّ وليست مُحافَظًا عليها يدويًا.

> **ملاحظة حول الاستقرار:** يعمل توليد OpenAPI على راية Nitro التجريبية `openAPI`. صيغة المواصفة مستقرّة (OpenAPI 3.1.0)؛ ومن الممكن حدوث انحراف هيكلي طفيف في بيانات تعريف العمليات مع نضج ميزة Nitro الأساسية. ثبّت خطوة توليد العميل على أحد مخرجات البناء إذا كنت بحاجة إلى عقد مجمّد.

## الخطوات التالية

- احصل على المواصفة الحية على [/_openapi.json](/_openapi.json)
- اقرأ [المصادقة](/docs/api/authentication) لمعرفة تدفّق bearer token
- انتقل إلى [Minds](/docs/api/minds) أو [Studies](/docs/api/studies) أو [Chat](/docs/api/chat) لاستعراض نقاط النهاية