Schlüssel, Scopes und Limits

Readsira hat zwei programmatische Schnittstellen, die ein gemeinsames Schlüsselsystem nutzen:

• REST API v2 unter https://api.readsira.com/rest/v2 für Skripte, Sync-Jobs und deine eigenen Apps (Pro und Research).
• MCP-Server unter https://api.readsira.com/mcp für Assistenten wie Claude Code und Cursor (jeder Tarif, Lese-Tools in Free). Siehe Einen MCP-Client verbinden.

Einen Schlüssel erstellen

Öffne in der App Einstellungen, API und MCP und wähle Schlüssel erstellen (REST) oder MCP-Schlüssel erstellen. Wähle die Scopes, die der Schlüssel nutzen darf. Der Schlüssel wird einmal angezeigt; Readsira speichert nur einen Hash davon und listet ihn danach als pk_1a2b...9z8y auf.

Sende den Schlüssel als Bearer-Token:

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

X-API-Key: pk_... funktioniert ebenfalls. Ein Schlüssel in der URL (?api_key=pk_...) wird mit 401 API_KEY_IN_QUERY abgelehnt: URLs landen in Logs und im Browserverlauf.

Neu erzeugen gibt dem Schlüssel ein neues Geheimnis und behält seine ID, Scopes und seinen Verlauf: Das alte Geheimnis funktioniert sofort nicht mehr. Widerrufen löscht den Schlüssel; sein Aktivitätsverlauf bleibt in den Einstellungen erhalten.

Scopes

Ein Schlüssel kann nur tun, was seine Scopes erlauben. Schreib-Scopes sind standardmäßig aus.

Scope	Erlaubt	Tarife
mcp	Den Schlüssel mit dem MCP-Server nutzen (gesetzt durch „MCP-Schlüssel erstellen“)	alle
read:library	Suche, Dokumente, Chunks, Transkripte	alle
ask:library	POST /rest/v2/ask (führt Readsiras Modell aus, verbraucht KI-Budget)	Pro, Research
read:projects	MCP list_projects, get_project_context; GET /rest/v2/projects, GET /rest/v2/projects/:id/context	alle (REST: Pro, Research)
write:projects	POST /rest/v2/projects/:id/items, POST /rest/v2/projects/:id/notes; MCP add_bookmark / create_note mit projectId	Pro, Research
write:uploads	POST /rest/v2/uploads (Audio, Video, PDF)	Pro, Research
read:bookmarks	v1-Lesezeichen-Routen (lesen)	Pro, Research
write:bookmarks	v1-Lesezeichen-Schreibzugriffe; 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-Routen	Pro, Research

Wenn du einen Schlüssel mit einem Scope erstellst, den dein Tarif nicht enthält, antwortet die API mit 400 SCOPE_NOT_ALLOWED. Wenn du herunterstufst, werden Scopes über den neuen Tarif hinaus ignoriert, bis du wieder hochstufst: Es wird nichts gelöscht.

Limits

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

Jedes Limit jedes Tarifs, auch die außerhalb der API, steht unter Tariflimits.

• Die stündliche Einstellung eines Schlüssels ist auf das Maximum pro Schlüssel des Tarifs begrenzt.
• Tage sind UTC. MCP initialize und tools/list zählen nicht; get_document zählt einen Aufruf pro 12.000 angeforderte Zeichen, Schreib-Tools zählen zwei.
• Über einem Limit bekommst du 429 mit Retry-After (Sekunden) und X-RateLimit-Limit / X-RateLimit-Remaining. MCP-Tool-Aufrufe über dem Tageslimit liefern einen Tool-Fehler RATE_LIMITED mit retryAfterSeconds.

GET /rest/v2/usage liefert die heutigen Zähler und deine Limits.

Antworten und Fehler

Die vollständige Liste mit Fehlerform, Headern und Hinweisen zum Wiederholen steht unter Ratenlimits und Fehler.

REST-Antworten verwenden einen einheitlichen Umschlag:

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

Fehler tragen einen stabilen error.code:

Status	Code	Bedeutung
401	API_KEY_INVALID	Fehlender, unbekannter, widerrufener oder abgelaufener Schlüssel (WWW-Authenticate: Bearer)
401	API_KEY_IN_QUERY	Der Schlüssel wurde in der URL gesendet; sende ihn im Authorization-Header
402	PLAN_REQUIRED	Dein Tarif hat keine REST-API (Free). MCP-Schlüssel funktionieren weiterhin unter /mcp.
402	PLAN_LIMIT_REACHED	Ein Mengenlimit (Schlüssel, Ask-Antworten in diesem Monat)
402	AI_QUOTA_EXCEEDED	Das KI-Budget dieses Monats ist aufgebraucht (/ask)
403	SCOPE_REQUIRED	Dem Schlüssel fehlt der Scope der Route (error.details.scopes)
404	-	Nicht gefunden oder nicht deins (die API sagt nie, was von beidem)
429	RATE_LIMITED	Stunden- oder Tageslimit; siehe Retry-After
503	AI_PAUSED	KI ist für den Tag pausiert (nur /ask; die Suche funktioniert weiter)

Datenschutz

Jeder Aufruf wird für deine Aktivitätsansicht in den Einstellungen protokolliert (Zeit, Schlüssel, Route oder Tool, Status, Client, Anzahl der Ergebnisse). Readsira protokolliert dort nie deinen Suchtext, deine Notizen oder Dokumentinhalte. Die Aktivität wird 90 Tage aufbewahrt.