Overview

The RankDebug API gives programmatic access to the same workspace data the dashboard shows: Search Console and analytics reads, crawls, deploys, reports and webhooks. It is a JSON REST API.

Base URL

https://api.rankdebug.com

Every endpoint lives under /v1. The full machine-readable description is an OpenAPI 3.1 document, served without authentication at:

https://api.rankdebug.com/v1/openapi.json

Authentication

Send an API key in the X-API-Key header:

curl https://api.rankdebug.com/v1/workspaces \
  -H "X-API-Key: $RANKDEBUG_API_KEY"

Keys are created on the API Keys page of the dashboard. Each key carries the scopes chosen when it was made, and can be bound to a single workspace. See API Keys and Scopes.

Scopes

Scope	Grants
`workspaces`	Workspaces, request logs and activity
`webhooks`	Webhook endpoints and their deliveries
`search`	Search Console, Google Analytics, CDN, crawl, site check, deploy and digest reads
`deploys`	Recording deploys. Write-only: it reads nothing back
`reports`	Reading shared reports and their comments
`ai`	AI features, which spend from the account's AI balance

Each endpoint page names the scope it needs. A request whose key lacks the scope answers 403.

Most reads take a workspace_id query parameter, and writes take a workspaceId field. The caller must belong to that workspace. A workspace, or any resource inside one, that does not exist and one that belongs to someone else both answer 404, so ids cannot be probed. A key bound to one workspace answers 403 when a request names any other.

Errors

Errors return a JSON body with a machine-readable code and a human-readable explanation, and a matching HTTP status:

{ "error": "validation_error", "message": "workspace_id is required" }

Status	Typical `error`	Meaning
`400`	`validation_error`	A parameter or field is missing or invalid
`401`	`unauthorized`	No key, an unknown key, or an expired key
`403`	`forbidden`	The key lacks the scope, the workspace is outside the key's binding, or the role does not allow it
`404`	`not_found`	The resource does not exist or is not yours
`409`	varies	The request conflicts with the current state, for example a paused webhook
`429`	`too_many_requests`	The rate limit was reached

Some errors carry extra fields alongside error and message.

Rate limits

Requests are limited per API key, per minute. The ceiling depends on the account behind the key. Every response carries these headers:

Header	Meaning
`X-RateLimit-Limit`	Requests allowed in the current minute
`X-RateLimit-Remaining`	Requests left in the current minute
`X-RateLimit-Reset`	When the window resets, in Unix seconds

Past the limit, the API answers 429 with too_many_requests, a retry_after field in seconds and a Retry-After header. Wait that long before retrying.

Endpoints

WorkspacesList, create, update and delete workspaces, and read a workspace's request logs and activity.SearchSearch Console performance, top rows, opportunities and sitemaps for a workspace.TrafficGoogle Analytics landing pages, acquisition and measurement health, and CDN crawler traffic, error paths and firewall rules.DeploysRecord deploys from CI, list them, and read one deploy with its site check, crawl and search impact.Site CrawlsRead crawls of the workspace website, their findings, and every page of one finding.DigestsRead what the latest scheduled digest email for a workspace contained.ReportsRead the reports shared with a workspace, their comment threads, and their PDF.WebhooksCreate and manage webhook endpoints, send test events, and read and replay deliveries.