מפתחות, הרשאות ומגבלות

ל-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 באפליקציה ובחרו יצירת מפתח (REST) או יצירת מפתח MCP. בחרו את ההרשאות שהמפתח רשאי להשתמש בהן. המפתח מוצג פעם אחת; Readsira שומרת רק גיבוב שלו ומציגה אותו אחר כך בתור pk_1a2b...9z8y.

שלחו את המפתח כאסימון נושא (bearer):

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

גם X-API-Key: pk_... עובד. מפתח בכתובת ה-URL (?api_key=pk_...) נדחה עם 401 API_KEY_IN_QUERY: כתובות מגיעות ליומנים ולהיסטוריית הדפדפן.

יצירה מחדש נותנת למפתח סוד חדש ושומרת את המזהה, ההרשאות וההיסטוריה שלו: הסוד הישן מפסיק לעבוד מיד. ביטול מוחק את המפתח; היסטוריית הפעילות שלו נשארת בהגדרות.

הרשאות

מפתח יכול לעשות רק מה שההרשאות שלו מאפשרות. הרשאות כתיבה כבויות כברירת מחדל.

הרשאה	מאפשרת	תוכניות
mcp	שימוש במפתח עם שרת ה-MCP (נקבעת על ידי "יצירת מפתח MCP")	כולן
read:library	חיפוש, מסמכים, קטעים, תמלולים	כולן
ask:library	POST /rest/v2/ask (מריץ את המודל של Readsira, משתמש בתקציב ה-AI)	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

כל מגבלה של כל תוכנית, כולל אלה שמחוץ ל-API, נמצאת במגבלות התוכניות.

• ההגדרה השעתית של מפתח מוגבלת למקסימום לכל מפתח של התוכנית.
• הימים הם לפי 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	המפתח נשלח ב-URL; שלחו אותו בכותרת Authorization
402	PLAN_REQUIRED	לתוכנית שלכם אין REST API (Free). מפתחות MCP עדיין עובדים ב-/mcp.
402	PLAN_LIMIT_REACHED	מגבלת ספירה (מפתחות, תשובות Ask החודש)
402	AI_QUOTA_EXCEEDED	תקציב ה-AI של החודש נוצל (/ask)
403	SCOPE_REQUIRED	למפתח חסרה ההרשאה של הנתיב (error.details.scopes)
404	-	לא נמצא, או לא שלכם (ה-API אף פעם לא אומר איזה מהשניים)
429	RATE_LIMITED	מגבלה שעתית או יומית; ראו Retry-After
503	AI_PAUSED	ה-AI מושהה להיום (/ask בלבד; החיפוש ממשיך לעבוד)

פרטיות

כל קריאה נרשמת ביומן לתצוגת הפעילות שלכם בהגדרות (שעה, מפתח, נתיב או כלי, סטטוס, לקוח, מספר תוצאות). Readsira אף פעם לא רושמת שם את טקסט החיפוש, ההערות או תוכן המסמכים שלכם. הפעילות נשמרת 90 יום.