Authentication and rate limits
Bearer API keys and scopes, per-key rate limits, the daily page quota for scraping and crawling, and request IDs.
Authentication
Section titled “Authentication”The Agent API uses Bearer token authentication with org-scoped API keys. Keys are prefixed with rk_live_ and validated via SHA-256 hash lookup.
Authorization: Bearer rk_live_aBcDeFgHiJkLmNoPqRsTuVwXyZ012345678901API keys are managed by organization admins through the key management endpoints (which use Clerk session auth, not Bearer tokens), or through the Settings > API keys tab in the Rankability UI.
Sign in from a terminal or CI (device authorization)
Section titled “Sign in from a terminal or CI (device authorization)”A script can get its own credential with one browser approval, without anyone copying a key. Rankability supports the OAuth 2.0 device authorization grant (RFC 8628). The script prints a short code and a link; you open the link while signed in to Rankability, check the code, and approve. The script then receives an OAuth access token (oat_...) that works as Authorization: Bearer on every endpoint in this guide, limited to the scopes you approved and to the organization you had active.
-
Register the client once with the device grant declared. A device client needs no redirect URI.
Terminal window curl -sS -X POST https://app.rankability.com/oauth/register \-H "Content-Type: application/json" \-d '{"client_name":"My CI job","grant_types":["urn:ietf:params:oauth:grant-type:device_code","refresh_token"],"token_endpoint_auth_method":"none"}'# => { "client_id": "mcp_...", "grant_types": [...], ... }Clients that identify themselves with a Client ID Metadata Document URL instead list the same
grant_typesin that document. -
Start the request and show the person the code and link.
Terminal window curl -sS -X POST https://app.rankability.com/oauth/device_authorization \--data-urlencode "client_id=mcp_..." \--data-urlencode "scope=reporter:read clients:read"# => { "device_code": "odc_...", "user_code": "BCDF-GHJK",# "verification_uri": "https://app.rankability.com/oauth/device",# "verification_uri_complete": "https://app.rankability.com/oauth/device?user_code=BCDF-GHJK",# "expires_in": 600, "interval": 5 } -
Approve in the browser. The page shows the app’s name, the permissions it asks for and the code. Approve only if you started the request yourself and the code matches.
-
Poll for the token every
intervalseconds until it is issued.Terminal window curl -sS -X POST https://app.rankability.com/oauth/token \--data-urlencode "grant_type=urn:ietf:params:oauth:grant-type:device_code" \--data-urlencode "device_code=odc_..." \--data-urlencode "client_id=mcp_..."# => { "access_token": "oat_...", "token_type": "Bearer", "expires_in": 3600,# "refresh_token": "ort_...", "scope": "reporter:read clients:read" }Until then the response is
400with one of these errors:errorMeaning authorization_pendingNot approved yet. Keep polling. slow_downPolling too often. Add 5 seconds to your interval (the response includes the new interval).access_deniedThe person chose Deny. Stop. expired_tokenThe 10-minute window passed. Start again. invalid_grantUnknown or already-used device code, or a different client. Stop. -
Call the API with the access token, for example
GET /usage(needsreporter:reador any other read scope that endpoint accepts). Refresh it withgrant_type=refresh_tokenbefore the hour is up, exactly as for the MCP OAuth flow.
Each device code works once. Device codes expire after 10 minutes, and code lookups on the approval page are rate-limited. The connection appears under connected apps in Settings, where it can be disconnected. API keys are still created only in Settings > API keys; there is no endpoint that creates a key from another credential.
Plan requirements
Section titled “Plan requirements”API access is included on every paid plan (Core, Team, and Agency) at no add-on cost. Every full-platform paid plan gets the same request-rate limit; see Rate limits for the per-plan table. An active subscription is required — if your org does not have an active subscription, both key creation and job creation return a 403 error.
Scopes
Section titled “Scopes”Each key has one or more scopes that control what operations it can perform:
| Scope | Description |
|---|---|
copywriter:run |
Create jobs, approve briefs, replace drafts, mark/unmark Done, delete jobs |
copywriter:read |
Poll status, retrieve artifacts, list jobs, export content |
reporter:read |
List projects, get SPI scores, results, trends, summary |
reporter:run |
Trigger new Reporter scans |
reporter:write |
Create, update, delete Reporter projects |
clients:read |
List clients, get client details |
clients:write |
Create, update, delete clients |
kb:read |
Fetch all published KB articles and FAQ content |
optimize:run |
Score pages against SERP competitors via the Optimize endpoint |
routines:read |
Read all Automate settings and technical audit history; no changes or runs |
routines:write |
Create, enable, pause and change Automate workflows; authorize their recurring usage |
publishing:read |
Read credential-free connections and delivery receipts without publishing, retrying, or validating |
publishing:write |
Request a confirmed, idempotent draft delivery; never authorizes live publishing |
serena:ask |
Ask Serena client-scoped questions through the read-only consultation endpoint |
Rate limits
Section titled “Rate limits”All agent endpoints are rate-limited per API key (or per OAuth credential for MCP connections) over a sliding 60-second window. MCP tool calls count against the same limit as direct API calls. The limit depends on the product and plan the organization is on:
| Product | Plan | Requests per minute, per key | Requests per day |
|---|---|---|---|
| Rankability | Starter (including trials), and earlier Starter and Core Lite plans | 60 | No daily cap |
| Rankability | Growth (including trials), and earlier Core and Growth plans | 120 | No daily cap |
| Rankability | Pro (including trials), and earlier Team, Scale and Agency plans | 240 | No daily cap |
| Rankability | Free | 30 | No daily cap |
| Copywriter plans | Core | 30 | No daily cap |
| Copywriter plans | Scale | 60 | No daily cap |
| Copywriter plans | High-volume | 120 | No daily cap |
| SEO Researcher | Free sample and Starter | 60 | No daily cap |
| SEO Researcher | Pro | 120 | No daily cap |
| SEO Researcher | Agency | 240 | No daily cap |
| SEO Researcher | Scale | 500 | No daily cap |
There is no daily request cap today. Your X-RateLimit-Limit header is authoritative.
Rate limit headers are included in every response. Retry-After is sent on every 429 that has a known retry time: rate_limit_exceeded, usage_limit_reached, capacity_reached and concurrency_limit_reached.
| Header | Description |
|---|---|
X-RateLimit-Limit |
Maximum requests per minute for this key |
X-RateLimit-Remaining |
Remaining requests in current window |
X-RateLimit-Reset |
Seconds until the window resets |
Retry-After |
Seconds to wait before retrying |
Daily page quota (scrape / crawl)
Section titled “Daily page quota (scrape / crawl)”Separately from the request rate limit, the page-fetching endpoints (POST /scrape and POST /crawl) enforce a per-org daily page-volume quota — a safety cap on how many pages a single org can fetch in a rolling UTC day. When the cap is reached, requests are rejected with 429 quota_exceeded until the UTC day rolls over.
Both endpoints return quota headers on every response — including the 429 quota_exceeded rejection — so you can self-throttle before you hit the hard cap:
| Header | Description |
|---|---|
X-Quota-Limit |
Daily page quota (pages per UTC day) |
X-Quota-Used |
Pages consumed so far in the current UTC day |
X-Quota-Remaining |
Pages remaining before the quota is exhausted |
Counts reset at the start of each UTC day. The numbers reflect usage on the instance that served the request (the quota is enforced per instance), so on a horizontally-scaled deployment the per-request figure is a lower bound on org-wide usage.
To check your allowance without making a billable scrape/crawl call, use the read-only usage endpoint:
GET /crawler/usage (scope: scrape:run or crawl:run){ "daily_page_quota": { "limit": 50000, "used": 1280, "remaining": 48720, "window_date": "2026-06-21", "scope": "this_instance" }}The limit is resolved from your plan tier (the same tier-derived resolution that backs the hard cap), so higher-paying plans see a larger allowance. The same X-Quota-* headers are also set on this response.
Request tracking
Section titled “Request tracking”Every response includes an X-Request-Id header for tracing and debugging.
