المفاتيح والنطاقات والحدود

لدى Readsira واجهتان برمجيتان تتشاركان نظام مفاتيح واحدًا:

• REST API v2 على https://api.readsira.com/rest/v2 للسكربتات ومهام المزامنة وتطبيقاتك الخاصة (Pro وResearch).
• خادم MCP على https://api.readsira.com/mcp لمساعدين مثل Claude Code وCursor (كل الخطط، وأدوات القراءة في Free). راجع ربط عميل MCP.

إنشاء مفتاح

افتح الإعدادات، API وMCP في التطبيق واختر Create key (لـ REST) أو Create MCP key. اختر النطاقات التي يحق للمفتاح استخدامها. يظهر المفتاح مرة واحدة فقط؛ يخزن Readsira قيمة تجزئة له فقط، ويعرضه بعد ذلك بصيغة pk_1a2b...9z8y.

أرسل المفتاح كرمز حامل (bearer token):

curl https://api.readsira.com/rest/v2/usage \
  -H "Authorization: Bearer $READSIRA_KEY"

كما يعمل X-API-Key: pk_.... أما المفتاح داخل الرابط (?api_key=pk_...) فيُرفض مع 401 API_KEY_IN_QUERY، لأن الروابط تنتهي في السجلات وتاريخ المتصفح.

Regenerate يمنح المفتاح سرًّا جديدًا ويُبقي معرّفه ونطاقاته وسجله: يتوقف السر القديم عن العمل فورًا. Revoke يحذف المفتاح؛ ويبقى سجل نشاطه في الإعدادات.

النطاقات

لا يستطيع المفتاح فعل إلا ما تسمح به نطاقاته. نطاقات الكتابة معطلة افتراضيًا.

النطاق	ما يتيحه	الخطط
mcp	استخدام المفتاح مع خادم MCP (يُضبط عبر "Create MCP key")	الكل
read:library	البحث والمستندات والمقاطع والنصوص المفرغة	الكل
ask:library	POST /rest/v2/ask (يشغّل نموذج Readsira، ويستهلك ميزانية الذكاء الاصطناعي)	Pro, Research
read:projects	MCP list_projects وget_project_context؛ GET /rest/v2/projects وGET /rest/v2/projects/:id/context	الكل (REST: Pro, Research)
write:projects	POST /rest/v2/projects/:id/items وPOST /rest/v2/projects/:id/notes؛ MCP add_bookmark / create_note مع projectId	Pro, Research
write:uploads	POST /rest/v2/uploads (صوت وفيديو وPDF)	Pro, Research
read:bookmarks	مسارات الإشارات المرجعية في v1 (قراءة)	Pro, Research
write:bookmarks	عمليات الكتابة على الإشارات المرجعية في v1؛ MCP add_bookmark	Pro, Research
write:notes	MCP create_note	Pro, Research
read:collections, write:collections, read:feeds, write:feeds, read:entries, read:user	مسارات v1	Pro, Research

إنشاء مفتاح بنطاق لا تشمله خطتك يعيد 400 SCOPE_NOT_ALLOWED. إذا خفّضت خطتك، تُتجاهل النطاقات التي تتجاوز الخطة الجديدة إلى أن ترقّي من جديد: لا يُحذف شيء.

الحدود

Plan	REST keys	MCP keys	REST requests per day	MCP tool calls per day	Requests per hour per key
Free	0	1	0	100	60
Pro	5	10	10,000	10,000	600
Research	10	10	50,000	25,000	1,200

كل حدود كل خطة، بما فيها ما هو خارج الواجهة البرمجية، موجودة في حدود الخطط.

• يُقيَّد إعداد الحد الساعي للمفتاح بالحد الأقصى لكل مفتاح في الخطة.
• الأيام بتوقيت UTC. لا تُحتسب initialize وtools/list في MCP؛ أما get_document فيُحتسب كل 12,000 حرف مطلوب كاستدعاء واحد، وأدوات الكتابة تُحتسب باستدعاءين.
• عند تجاوز الحد تحصل على 429 مع Retry-After (بالثواني) وX-RateLimit-Limit / X-RateLimit-Remaining. استدعاءات أدوات MCP التي تتجاوز الحد اليومي تعيد خطأ أداة RATE_LIMITED مع retryAfterSeconds.

يعيد GET /rest/v2/usage أعداد اليوم وحدودك.

الاستجابات والأخطاء

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

تستخدم استجابات REST غلافًا واحدًا:

{
  "success": true,
  "data": { "...": "payload" },
  "meta": {
    "timestamp": "...",
    "path": "...",
    "method": "GET",
    "statusCode": 200
  }
}

تحمل الأخطاء error.code ثابتًا:

الحالة	الرمز	المعنى
401	API_KEY_INVALID	مفتاح مفقود أو غير معروف أو ملغى أو منتهي الصلاحية (WWW-Authenticate: Bearer)
401	API_KEY_IN_QUERY	أُرسل المفتاح في الرابط؛ أرسله في ترويسة Authorization
402	PLAN_REQUIRED	خطتك لا تتضمن REST API (Free). تبقى مفاتيح MCP تعمل على /mcp.
402	PLAN_LIMIT_REACHED	حد عددي (المفاتيح، إجابات ask هذا الشهر)
402	AI_QUOTA_EXCEEDED	استُهلكت ميزانية الذكاء الاصطناعي لهذا الشهر (/ask)
403	SCOPE_REQUIRED	ينقص المفتاح نطاق المسار (error.details.scopes)
404	-	غير موجود، أو ليس لك (لا تذكر الواجهة أيهما)
429	RATE_LIMITED	حد ساعي أو يومي؛ راجع Retry-After
503	AI_PAUSED	الذكاء الاصطناعي متوقف لهذا اليوم (/ask فقط؛ يستمر البحث بالعمل)

الخصوصية

يُسجَّل كل استدعاء لعرض النشاط في الإعدادات (الوقت والمفتاح والمسار أو الأداة والحالة والعميل وعدد النتائج). لا يسجّل Readsira هناك نص بحثك أو ملاحظاتك أو محتوى مستنداتك أبدًا. يُحتفظ بالنشاط 90 يومًا.