Keys, scopes and limits

Readsira has two programmatic surfaces that share one key system:

• REST API v2 at https://api.readsira.com/rest/v2 for scripts, sync jobs and your own apps (Pro and Research).
• MCP server at https://api.readsira.com/mcp for assistants such as Claude Code and Cursor (every plan, read tools on Free). See Connect an MCP client.

Create a key

Open Settings, API and MCP in the app and choose Create key (REST) or Create MCP key. Pick the scopes the key may use. The key is shown once; Readsira stores only a hash of it and lists it afterwards as pk_1a2b...9z8y.

Send the key as a bearer token:

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

X-API-Key: pk_... works too. A key in the URL (?api_key=pk_...) is refused with 401 API_KEY_IN_QUERY: URLs end up in logs and browser history.

Regenerate gives the key a new secret and keeps its id, scopes and history: the old secret stops working at once. Revoke deletes the key; its activity history stays in Settings.

Scopes

A key can only do what its scopes allow. Write scopes are off by default.

Scope	Allows	Plans
mcp	Using the key with the MCP server (set by "Create MCP key")	all
read:library	Search, documents, chunks, transcripts	all
ask:library	POST /rest/v2/ask (runs Readsira's model, uses AI budget)	Pro, Research
read:projects	MCP list_projects, get_project_context; GET /rest/v2/projects, GET /rest/v2/projects/:id/context	all (REST: Pro, Research)
write:projects	POST /rest/v2/projects/:id/items, POST /rest/v2/projects/:id/notes; MCP add_bookmark / create_note with projectId	Pro, Research
write:uploads	POST /rest/v2/uploads (audio, video, PDF)	Pro, Research
read:bookmarks	v1 bookmark routes (read)	Pro, Research
write:bookmarks	v1 bookmark writes; 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 routes	Pro, Research

Creating a key with a scope your plan does not include answers 400 SCOPE_NOT_ALLOWED. If you downgrade, scopes beyond the new plan are ignored until you upgrade again: nothing is deleted.

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

Every limit of every plan, including the ones outside the API, is on Plan limits.

• A key's own hourly setting is capped at the plan's per-key maximum.
• Days are UTC. MCP initialize and tools/list do not count; get_document counts one call per 12,000 characters requested, write tools count two.
• Over a limit you get 429 with Retry-After (seconds) and X-RateLimit-Limit / X-RateLimit-Remaining. MCP tool calls over the daily limit return a tool error RATE_LIMITED with retryAfterSeconds.

GET /rest/v2/usage returns today's counts and your limits.

Responses and errors

REST responses use one envelope:

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

Errors carry a stable error.code:

Status	Code	Meaning
401	API_KEY_INVALID	Missing, unknown, revoked or expired key (WWW-Authenticate: Bearer)
401	API_KEY_IN_QUERY	The key was sent in the URL; send it in the Authorization header
402	PLAN_REQUIRED	Your plan has no REST API (Free). MCP keys still work at /mcp.
402	PLAN_LIMIT_REACHED	A count limit (keys, ask answers this month)
402	AI_QUOTA_EXCEEDED	This month's AI budget is used (/ask)
403	SCOPE_REQUIRED	The key lacks the route's scope (error.details.scopes)
404	-	Not found, or not yours (the API never says which)
429	RATE_LIMITED	Hourly or daily limit; see Retry-After
503	AI_PAUSED	AI is paused for the day (/ask only; search keeps working)

Privacy

Every call is logged for your activity view in Settings (time, key, route or tool, status, client, result count). Readsira never logs your search text, notes or document content there. Activity is kept for 90 days.