مرجع API

نظرة عامة

توثّق هذه الصفحة العقد الخارجي الحالي لوكلاء الذكاء الاصطناعي في Flashcards.

ابدأ من نقطة الاكتشاف الأساسية:

GET https://api.flashcards-open-source-app.com/v1/

الحمولة نفسها متاحة أيضًا عبر GET /v1/agent، لكن /v1/ هو نقطة الدخول العامة الأساسية.

تخبر استجابة الاكتشاف الوكيل كيف:

• يبدأ تسجيل الدخول عبر OTP بالبريد
• يستبدل OTP بمفتاح API طويل العمر
• يحمّل سياق الحساب
• ينشئ أو يختار مساحة عمل
• يتابع عبر سطح SQL المنشور

المواصفات المنشورة

عناوين المواصفات الأساسية لسطح الوكيل الخارجي:

• https://api.flashcards-open-source-app.com/v1/agent/openapi.json
• https://api.flashcards-open-source-app.com/v1/agent/swagger.json

وتوجد أيضًا أسماء بديلة من الجذر:

• https://api.flashcards-open-source-app.com/v1/openapi.json
• https://api.flashcards-open-source-app.com/v1/swagger.json

تهيئة المصادقة

تعمل مرحلة OTP الأولى على خدمة auth:

• POST https://auth.flashcards-open-source-app.com/api/agent/send-code
• POST https://auth.flashcards-open-source-app.com/api/agent/verify-code

التدفق هو:

1. نفّذ GET /v1/.
2. أرسل بريد المستخدم إلى send-code.
3. اقرأ otpSessionToken من الاستجابة.
4. اطلب من المستخدم أحدث رمز بريد مكوّن من 8 أرقام.
5. استدعِ verify-code مع code وotpSessionToken وlabel.
6. خزّن مفتاح API المُعاد خارج ذاكرة المحادثة.

متغير البيئة المقترح:

export FLASHCARDS_OPEN_SOURCE_API_KEY="fca_ABCDEFGH_0123456789ABCDEFGHJKMNPQRS"

تستخدم الطلبات الموثّقة:

Authorization: ApiKey <key>

سطح الوكيل بعد تسجيل الدخول

بعد التحقق، يصبح السطح الحالي كالآتي:

• GET /v1/agent/me
• GET /v1/agent/workspaces
• POST /v1/agent/workspaces
• POST /v1/agent/workspaces/{workspaceId}/select
• POST /v1/agent/sql/query (للقراءة فقط)
• POST /v1/agent/sql/execute (للكتابة)

التهيئة المعتادة تبدو هكذا:

1. GET /v1/agent/me
2. GET /v1/agent/workspaces?limit=100
3. إذا لزم الأمر، POST /v1/agent/workspaces مع {"name":"Personal"}
4. إذا لزم الأمر، POST /v1/agent/workspaces/{workspaceId}/select
5. استخدم POST /v1/agent/sql/query للقراءة وPOST /v1/agent/sql/execute للكتابة

اختيار مساحة العمل صريح لكل اتصال بمفتاح API. يجب على الوكلاء اتباع نص instructions وdocs.openapiUrl المُعادين بدل التخمين.

سطح SQL

POST /v1/agent/sql/query هو سطح القراءة فقط بشكل صارم (SHOW TABLES وDESCRIBE وSELECT) وPOST /v1/agent/sql/execute هو سطح الكتابة (INSERT وUPDATE وDELETE)؛ يجب أن يكون الطلب الواحد إما قراءات بالكامل أو كتابات بالكامل.

هو محدود عمدًا وليس PostgreSQL كاملًا. تغطي هذه الوثائق اللهجة المدعومة فقط، وليست مرجع توافق مع PostgreSQL.

لا يصلح أي مسار قراءة البيانات، ولا يعيد حساب الجدولة، ولا يغيّر حالة البطاقة. استخدم POST /v1/agent/sql/execute لكل كتابة.

العائلات الحالية للأوامر:

• SHOW TABLES
• DESCRIBE <resource>
• SELECT
• INSERT
• UPDATE
• DELETE

الموارد المنطقية المنشورة حاليًا تشمل:

• workspace
• cards
• decks
• review_events

ملاحظات:

• القيمة الافتراضية لـ LIMIT هي 100 والحد الأقصى أيضًا 100
• استخدم ORDER BY عندما تحتاج إلى ترقيم صفحات ثابت
• استخدم SHOW TABLES أو DESCRIBE cards لاكتشاف المخطط
• العقد الخارجي بعد الاختيار يكون ضمن نطاق مساحة العمل

مثال طلب:

curl -X POST https://api.flashcards-open-source-app.com/v1/agent/sql/query \
  -H "Content-Type: application/json" \
  -H "Authorization: ApiKey $FLASHCARDS_OPEN_SOURCE_API_KEY" \
  -d '{"sql":"SHOW TABLES"}'

يتوفر أيضًا خادم MCP بعيد على https://mcp.flashcards-open-source-app.com/mcp باستخدام OAuth 2.1 (Dynamic Client Registration + PKCE). يكشف التقسيم نفسه عبر أداتين، sql_query (للقراءة فقط بشكل صارم) وsql_execute (للكتابة)، بالإضافة إلى list_workspaces للقراءة فقط بشكل صارم.

الأمان والنطاق

سطح SQL هو لهجة محتواة ومفروضة من المحلّل اللغوي وليس PostgreSQL كاملًا. وسائل الحماية هي:

• قائمة عبارات مغلقة: فقط SHOW TABLES وDESCRIBE وSHOW COLUMNS وSELECT للقراءة، وINSERT وUPDATE وDELETE للكتابة. وأي شيء آخر يُرفض أثناء التحليل.
• موارد محدودة: لا يمكن للعبارات أن تمسّ سوى موارد workspace وcards وdecks وreview_events.
• النطاق لكل مساحة عمل: كل عبارة مقيّدة بمساحة العمل المحددة لديك، بدون وصول عبر المستأجرين.
• الحدود: حتى 100 صف لكل عبارة، وحتى 50 عبارة لكل دفعة، وحد للنتائج يبلغ نحو 12k رمز. وتُطبَّق دفعات التعديل بشكل ذرّي.
• الفصل بين القراءة والكتابة: sql_query وlist_workspaces للقراءة فقط بشكل صارم (readOnlyHint) ولا تصلح البيانات أو تعيد حساب الجدولة أو تغيّر حالة البطاقة. sql_execute هو أداة الكتابة الوحيدة وينفّذ عمليات الكتابة (destructiveHint)؛ ويجب أن يكون الاستدعاء الواحد إما كله قراءة أو كله كتابة.

واجهات API البشرية والمزامنة

يتضمن Flashcards أيضًا واجهات منفصلة للعملاء البشريين ولمزامنة العمل دون اتصال أولًا، لكنها ليست العقد الرئيسي للوكلاء الخارجيين:

• تستخدم تدفقات المتصفح ملفات تعريف ارتباط مشتركة النطاق مع حماية CSRF
• يستخدم العملاء الذين يعملون دون اتصال أولًا مسارات المزامنة المنفذة تحت /v1/workspaces/{workspaceId}/sync/push و/v1/workspaces/{workspaceId}/sync/pull
• تبقى مسارات المزامنة عمدًا خارج سطح OpenAPI الخارجي للوكلاء