Deploys

Recording a deploy needs the deploys scope, which can record deploys and read nothing back. Reading deploys and site checks needs the search scope. The Deploys guide explains what RankDebug does with them.

Record a deploy

POST /v1/deploys

curl -X POST https://api.rankdebug.com/v1/deploys \
  -H "X-API-Key: $RANKDEBUG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "commitSha": "4f9c2a1e7b3d",
    "environment": "production",
    "ref": "main",
    "message": "Move listings to the new template"
  }'

Each entry in signals (up to 50 per file) is { "kind", "change", "line" }, where change is added or removed and line is optional. Send paths and signal names, never code.

Answers 201 with the deploy:

{
  "id": "0b6e2f7a-5c1d-4e8b-a3f9-7d2c4e1b9a60",
  "commitSha": "4f9c2a1e7b3d",
  "environment": "production",
  "ref": "main",
  "message": "Move listings to the new template",
  "source": "webhook",
  "deployedAt": "2026-10-09T14:02:11.000Z",
  "changes": [],
  "createdAt": "2026-10-09T14:02:11.000Z"
}

source says how the deploy arrived: webhook for an API key request without changes, cli for one with changes, manual from the dashboard, and github or gitlab from a connected repository.

The same environment and commitSha again updates that deploy instead of adding another. A new production deploy, or one whose deployedAt moved, queues a site check about two minutes later and a crawl about five minutes later. A viewer's key answers 403.

List deploys

GET /v1/deploys?workspace_id={id}

Newest first. Each deploy carries siteCheck, the latest check that followed it, or null.

Get a deploy

GET /v1/deploys/{id}

One deploy with everything that followed it:

• siteCheck and baseline: the check after the deploy and the one before it it was compared with.
• findings: what got worse between them, each with kind, severity, url, before, after, clicks and causes, the likely causes among the deploy's changes.
• siteCrawl and crawlFindings: the crawl after the deploy and the crawl findings new since the crawl before, with causes.
• impact: Search Console totals for equal windows before and after the deploy, up to seven days each, and when findings name pages, those pages' clicks and impressions against the rest of the site. null until there is data for a day after the deploy.

Latest site check

GET /v1/site-checks/latest?workspace_id={id}

The newest check in any state (latest), the newest finished one (check), the finished check before it (baseline), what got worse between them (findings) and what is wrong in the finished check on its own (issues). Each finding has kind, severity, url, before, after and clicks. The kinds are listed in the findings reference.