Clés, portées et limites

Readsira propose deux surfaces programmatiques qui partagent un même système de clés :

• API REST v2 sur https://api.readsira.com/rest/v2 pour les scripts, les tâches de synchronisation et vos propres applications (Pro et Research).
• Serveur MCP sur https://api.readsira.com/mcp pour des assistants comme Claude Code et Cursor (toutes les offres, outils de lecture en Free). Voir Connecter un client MCP.

Créer une clé

Ouvrez Paramètres, API et MCP dans l'application et choisissez Créer une clé (REST) ou Créer une clé MCP. Choisissez les portées que la clé peut utiliser. La clé n'est affichée qu'une seule fois ; Readsira n'en stocke qu'un hachage et la liste ensuite sous la forme pk_1a2b...9z8y.

Envoyez la clé sous forme de jeton porteur (bearer) :

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

X-API-Key: pk_... fonctionne aussi. Une clé dans l'URL (?api_key=pk_...) est refusée avec 401 API_KEY_IN_QUERY : les URL se retrouvent dans les journaux et l'historique du navigateur.

Régénérer donne un nouveau secret à la clé et conserve son identifiant, ses portées et son historique : l'ancien secret cesse de fonctionner immédiatement. Révoquer supprime la clé ; son historique d'activité reste dans les paramètres.

Portées

Une clé ne peut faire que ce que ses portées autorisent. Les portées d'écriture sont désactivées par défaut.

Portée	Autorise	Offres
mcp	Utiliser la clé avec le serveur MCP (définie par « Créer une clé MCP »)	toutes
read:library	Recherche, documents, passages, transcriptions	toutes
ask:library	POST /rest/v2/ask (exécute le modèle de Readsira, utilise le budget d'IA)	Pro, Research
read:projects	MCP list_projects, get_project_context ; GET /rest/v2/projects, GET /rest/v2/projects/:id/context	toutes (REST : Pro, Research)
write:projects	POST /rest/v2/projects/:id/items, POST /rest/v2/projects/:id/notes ; MCP add_bookmark / create_note avec projectId	Pro, Research
write:uploads	POST /rest/v2/uploads (audio, vidéo, PDF)	Pro, Research
read:bookmarks	Routes v1 des marque-pages (lecture)	Pro, Research
write:bookmarks	Écritures v1 des marque-pages ; MCP add_bookmark	Pro, Research
write:notes	MCP create_note	Pro, Research
read:collections, write:collections, read:feeds, write:feeds, read:entries, read:user	Routes v1	Pro, Research

Créer une clé avec une portée que votre offre n'inclut pas répond 400 SCOPE_NOT_ALLOWED. Si vous passez à une offre inférieure, les portées au-delà de la nouvelle offre sont ignorées jusqu'à ce que vous repassiez à une offre supérieure : rien n'est supprimé.

Limites

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

Toutes les limites de chaque offre, y compris celles qui sont extérieures à l'API, se trouvent dans Limites des offres.

• Le réglage horaire propre à une clé est plafonné au maximum par clé de l'offre.
• Les jours sont en UTC. MCP initialize et tools/list ne comptent pas ; get_document compte un appel par tranche de 12 000 caractères demandés, les outils d'écriture comptent deux.
• Au-delà d'une limite, vous recevez 429 avec Retry-After (secondes) et X-RateLimit-Limit / X-RateLimit-Remaining. Les appels d'outils MCP au-delà de la limite quotidienne renvoient une erreur d'outil RATE_LIMITED avec retryAfterSeconds.

GET /rest/v2/usage renvoie les compteurs du jour et vos limites.

Réponses et erreurs

La liste complète, avec la forme de l'erreur, les en-têtes et les conseils pour réessayer, se trouve dans Limites de débit et erreurs.

Les réponses REST utilisent une seule enveloppe :

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

Les erreurs portent un error.code stable :

Statut	Code	Signification
401	API_KEY_INVALID	Clé absente, inconnue, révoquée ou expirée (WWW-Authenticate: Bearer)
401	API_KEY_IN_QUERY	La clé a été envoyée dans l'URL ; envoyez-la dans l'en-tête Authorization
402	PLAN_REQUIRED	Votre offre n'a pas d'API REST (Free). Les clés MCP fonctionnent toujours avec /mcp.
402	PLAN_LIMIT_REACHED	Une limite de quantité (clés, réponses d'Ask ce mois-ci)
402	AI_QUOTA_EXCEEDED	Le budget d'IA de ce mois est épuisé (/ask)
403	SCOPE_REQUIRED	La clé n'a pas la portée de la route (error.details.scopes)
404	-	Introuvable, ou pas à vous (l'API ne dit jamais lequel)
429	RATE_LIMITED	Limite horaire ou quotidienne ; voir Retry-After
503	AI_PAUSED	L'IA est en pause pour la journée (/ask uniquement ; la recherche continue)

Confidentialité

Chaque appel est consigné pour votre vue d'activité dans les paramètres (heure, clé, route ou outil, statut, client, nombre de résultats). Readsira n'y consigne jamais votre texte de recherche, vos notes ni le contenu de vos documents. L'activité est conservée 90 jours.