OverviewAuthenticationMindsKnowledgeChatLatencyErrors
Minds Team

مواصفة OpenAPI وعملاء TypeScript

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

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

Endpoint

URLما الذي تحصل عليه
https://getminds.ai/_openapi.jsonمواصفة JSON بصيغة OpenAPI 3.1.0. مرّرها إلى أي مولّد.
https://getminds.ai/api/v1/openapi.jsonالمواصفة نفسها، مُقدَّمة إلى جانب نقاط النهاية التي تصفها. لا حاجة إلى مفتاح API.

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

المصادقة

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

Authorization: Bearer minds_…_key

أنشئ مفتاحًا من الإعدادات ← مفاتيح API. راجع المصادقة للاطلاع على التدفّق الكامل.

إنشاء عميل TypeScript

أسرع طريقة: استخدم openapi-typescript لتوليد أنواع صارمة من المواصفة الحيّة.

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

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

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/sparks', {
  params: { query: { limit: 10 } },
})

تفضّل SDK في وقت التشغيل؟ يعمل أي مولّد متوافق مع OpenAPI 3.1 — openapi-generator وorval وkubb وغيرها.

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

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

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 الأساسية. ثبّت خطوة توليد العميل على أحد مخرجات البناء إذا كنت بحاجة إلى عقد مجمّد.

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