API

01

Authentication

All requests use a bearer token issued from your account settings. Tokens are scoped to a single workspace and can be revoked at any time. Never ship a token to a browser.

curl https://api.rankable.ai/v1/reports \
  -H "Authorization: Bearer $NS_API_KEY"

02

Create a report run

Starts an audit for a website domain or an Amazon storefront. Runs are asynchronous; poll the run or subscribe to the webhook below.

{
  "kind": "domain",            // "domain" | "amazon"
  "input_url": "yourbrand.com",
  "notify_url": "https://example.com/hooks/ns"
}

03

Retrieve a report

{
  "id": "rep_8f21c3",
  "status": "ready",           // pending | ready | failed
  "score": 71,
  "citation_share": 0.031,
  "answer_coverage": 0.42,
  "findings": [
    { "tier": 0, "area": "entity", "title": "Homepage does not state category in text" },
    { "tier": 1, "area": "product", "title": "Specs rendered as images on 214 PDPs" }
  ]
}

04

Webhooks

When a run finishes we POST to your notify_url with an HMAC-SHA256 signature in the x-ns-signature header. Verify it before trusting the payload.

{
  "event": "report.ready",
  "report_id": "rep_8f21c3",
  "occurred_at": "2026-08-11T14:02:11Z"
}

05

Rate limits & errors

Want a token? Email support@rankable.ai with your workspace and use case and we will enable it.