Claves, permisos y límites

Readsira tiene dos superficies programáticas que comparten un único sistema de claves:

• API REST v2 en https://api.readsira.com/rest/v2 para scripts, tareas de sincronización y tus propias aplicaciones (Pro y Research).
• Servidor MCP en https://api.readsira.com/mcp para asistentes como Claude Code y Cursor (todos los planes, herramientas de lectura en Free). Consulta Conectar un cliente MCP.

Crear una clave

Abre Configuración, API y MCP en la aplicación y elige Crear clave (REST) o Crear clave MCP. Elige los permisos que puede usar la clave. La clave se muestra una sola vez; Readsira solo guarda un hash de ella y después la lista como pk_1a2b...9z8y.

Envía la clave como token de portador (bearer):

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

X-API-Key: pk_... también funciona. Una clave en la URL (?api_key=pk_...) se rechaza con 401 API_KEY_IN_QUERY: las URL acaban en registros y en el historial del navegador.

Regenerar da a la clave un secreto nuevo y conserva su id, sus permisos y su historial: el secreto antiguo deja de funcionar al instante. Revocar elimina la clave; su historial de actividad permanece en Configuración.

Permisos

Una clave solo puede hacer lo que permiten sus permisos. Los permisos de escritura están desactivados por defecto.

Permiso	Permite	Planes
mcp	Usar la clave con el servidor MCP (se define con "Crear clave MCP")	todos
read:library	Búsqueda, documentos, fragmentos, transcripciones	todos
ask:library	POST /rest/v2/ask (ejecuta el modelo de Readsira, usa presupuesto de IA)	Pro, Research
read:projects	MCP list_projects, get_project_context; GET /rest/v2/projects, GET /rest/v2/projects/:id/context	todos (REST: Pro, Research)
write:projects	POST /rest/v2/projects/:id/items, POST /rest/v2/projects/:id/notes; MCP add_bookmark / create_note con projectId	Pro, Research
write:uploads	POST /rest/v2/uploads (audio, vídeo, PDF)	Pro, Research
read:bookmarks	Rutas de marcadores v1 (lectura)	Pro, Research
write:bookmarks	Escrituras de marcadores 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	Rutas v1	Pro, Research

Crear una clave con un permiso que tu plan no incluye responde 400 SCOPE_NOT_ALLOWED. Si pasas a un plan inferior, los permisos que van más allá del plan nuevo se ignoran hasta que vuelvas a mejorar: no se elimina nada.

Límites

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

Todos los límites de todos los planes, incluidos los que quedan fuera de la API, están en Límites de los planes.

• El ajuste por hora de una clave tiene como tope el máximo por clave del plan.
• Los días son UTC. MCP initialize y tools/list no cuentan; get_document cuenta una llamada por cada 12 000 caracteres solicitados y las herramientas de escritura cuentan dos.
• Al superar un límite recibes 429 con Retry-After (segundos) y X-RateLimit-Limit / X-RateLimit-Remaining. Las llamadas a herramientas MCP por encima del límite diario devuelven un error de herramienta RATE_LIMITED con retryAfterSeconds.

GET /rest/v2/usage devuelve los recuentos de hoy y tus límites.

Respuestas y errores

La lista completa, con la forma del error, las cabeceras y consejos para reintentar, está en Límites de uso y errores.

Las respuestas REST usan un único sobre:

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

Los errores llevan un error.code estable:

Estado	Código	Significado
401	API_KEY_INVALID	Clave ausente, desconocida, revocada o caducada (WWW-Authenticate: Bearer)
401	API_KEY_IN_QUERY	La clave se envió en la URL; envíala en la cabecera Authorization
402	PLAN_REQUIRED	Tu plan no tiene API REST (Free). Las claves MCP siguen funcionando en /mcp.
402	PLAN_LIMIT_REACHED	Un límite de recuento (claves, respuestas de Preguntar este mes)
402	AI_QUOTA_EXCEEDED	Se agotó el presupuesto de IA de este mes (/ask)
403	SCOPE_REQUIRED	La clave no tiene el permiso de la ruta (error.details.scopes)
404	-	No encontrado, o no es tuyo (la API nunca dice cuál de los dos)
429	RATE_LIMITED	Límite por hora o por día; consulta Retry-After
503	AI_PAUSED	La IA está en pausa durante el día (solo /ask; la búsqueda sigue funcionando)

Privacidad

Cada llamada se registra para tu vista de actividad en Configuración (hora, clave, ruta o herramienta, estado, cliente, número de resultados). Readsira nunca registra ahí el texto de tus búsquedas, tus notas ni el contenido de tus documentos. La actividad se conserva durante 90 días.