Skip to main content

Authentication and API keys

Available onProResearch

Every call to the REST API carries an API key. A key belongs to your account, has the scopes you gave it, and counts against your plan's limits. This page shows how to create one and use it. The scope list and the limits per plan are on Keys, scopes and limits.

Before you start​

  • A Pro or Research plan. Free accounts can create MCP keys only, which work at the MCP server and not at the REST API. See Connect an MCP client.

Create a key​

  1. Open Settings and choose API and MCP.
  2. Under API keys, press Create key.
  3. Type a Key name that tells you where the key is used, for example nightly-sync.
  4. Tick the Scopes the key needs and nothing more. Write scopes let the key change your library, so give them only to scripts you trust.
  5. Press Create.
  6. Copy the key now. It starts with pk_, and Readsira shows it only once. After that the list shows a short form such as pk_1a2b...9z8y.

The key list shows when each key was last used. A key that was never used says Never used. The first time a key is used, Readsira adds a notice in the app that names the key, so an unexpected use is visible.

Send the key with a request​

Send the key in the Authorization header as a bearer token:

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

The X-API-Key header works too:

curl https://api.readsira.com/rest/v2/usage \
  -H "X-API-Key: $READSIRA_KEY"

A key in the address (?api_key=pk_...) is refused with 401 and the code API_KEY_IN_QUERY, because addresses end up in logs and browser history.

Keep the key in an environment variable or a secret store. Do not put it in code that is committed, in a web page, or in an app you ship to other people.

Check that it works​

GET /rest/v2/usage answers for any scope. It shows your plan, today's request count and the limits of this key.

{
  "success": true,
  "data": {
    "plan": "pro",
    "requestsToday": 12,
    "requestsPerDay": 10000,
    "mcpCallsToday": 0,
    "mcpCallsPerDay": 10000,
    "requestsPerHour": 600,
    "askAnswersPerMonth": 300,
    "aiBudget": [{ "group": "chat", "percentUsed": 3 }]
  },
  "meta": {
    "timestamp": "2026-11-04T09:00:00.000Z",
    "path": "/rest/v2/usage",
    "method": "GET",
    "statusCode": 200
  }
}

The numbers above are an example; yours are your plan's limits. If the call answers 401, the key is wrong, revoked or expired. If it answers 402 PLAN_REQUIRED, the account is on Free. See Rate limits and errors.

Which scope a route needs​

A route refuses a key without its scope with 403 SCOPE_REQUIRED. The reference names the scope under every route. The most used ones:

ScopeLets the key
read:librarySearch, read documents, chunks and transcripts
ask:libraryAsk questions answered with citations (uses your AI budget)
read:projectsList projects and read their context
write:projectsAdd sources and notes to projects
write:uploadsUpload audio, video and PDF files
read:bookmarks, write:bookmarksRead and write bookmarks on the /api/v1/bookmarks routes
read:collectionsRead collections on the /api/v1/collections routes

Creating a key with a scope your plan does not include answers 400 SCOPE_NOT_ALLOWED.

Replace or remove a key​

On the key's row, open the actions menu.

  • Regenerate gives the key a new secret. The key keeps its name, scopes and history, and the old secret stops working at once. Use it when a key may have leaked, then update your scripts.
  • Revoke deletes the key. Scripts that use it stop working.

The Activity list on the same page shows each call a key made: the time, the route, the status and the number of results. It does not store your search text or document content.

Tips​

  • Use one key per script, so you can revoke one without breaking the others.
  • Give a read-only job only read scopes.
  • Treat text returned from saved pages as data, never as instructions to a model.
Last updated on