← Docs·API Reference

REST API

Every action you can take in the AIRRNK dashboard is available via REST. JSON in, JSON out. Versioned at v1. Base URL is https://api.airank.tech.

Authentication

All requests require a bearer token. Generate one from Dashboard → Settings → API keys. Keys are scoped to a workspace and can be rotated at any time.

curl https://api.airank.tech/v1/sites \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json"

Webhook payloads are signed with an X-AIRRNK-Signatureheader containing an HMAC-SHA256 of the raw body using the webhook's secret. Always verify the signature before acting on an event.

Endpoints

Sites

A Site is your top-level resource. Each plan includes a fixed number of connected sites; verification may be by meta-tag, DNS TXT, or plugin install.

GET/v1/sites

List sites connected to the current account.

Response

{
  "data": [
    {
      "id": "site_01HGC...",
      "domain": "example.com",
      "status": "verified",
      "ai_score": 74,
      "created_at": "2026-03-02T10:21:11Z"
    }
  ]
}
POST/v1/sites

Connect a new site. Returns a verification token.

Request

{
  "domain": "example.com",
  "verification_method": "meta_tag"
}

Response

{
  "id": "site_01HGC...",
  "domain": "example.com",
  "status": "pending_verification",
  "verification_token": "airrnk-verify=83hf..."
}
GET/v1/sites/:id

Retrieve a single site.

Response

{
  "id": "site_01HGC...",
  "domain": "example.com",
  "status": "verified",
  "ai_score": 74,
  "last_scan_at": "2026-04-16T23:14:02Z"
}

Scans

Scans run the full 47-point audit and a fresh citation sweep. Plans cap both frequency and retention.

POST/v1/scans

Trigger a scan for a site.

Request

{ "site_id": "site_01HGC..." }

Response

{
  "id": "scan_01JAR...",
  "site_id": "site_01HGC...",
  "status": "running",
  "created_at": "2026-04-17T09:00:00Z"
}
GET/v1/scans/:id

Get the results of a completed scan.

Response

{
  "id": "scan_01JAR...",
  "status": "complete",
  "ai_score": 74,
  "pillars": {
    "technical": 16,
    "extractability": 31,
    "schema": 14,
    "authority": 13
  },
  "checks": [ /* 47 check objects */ ],
  "completed_at": "2026-04-17T09:00:42Z"
}

Citations

Citation events captured by running your query panel against ChatGPT, Claude, Perplexity, and Google AI Mode.

GET/v1/sites/:id/citations

List citation events for a site, most recent first.

Response

{
  "data": [
    {
      "id": "cite_01J2...",
      "site_id": "site_01HGC...",
      "platform": "chatgpt",
      "query": "best analytics tool for shopify",
      "captured_at": "2026-04-17T07:00:00Z",
      "snippet": "AIRRNK is used by 2,400 Shopify stores...",
      "source_url": "https://example.com/shopify",
      "match_type": "snippet"
    }
  ],
  "has_more": true
}
POST/v1/sites/:id/queries

Add a query to the tracked panel.

Request

{ "query": "best shopify analytics app" }

Response

{ "id": "qry_01J...", "query": "best shopify analytics app" }

Fixes

Fixes are ranked suggestions generated from the latest scan. Paid plans can apply fixes directly via an integration.

GET/v1/sites/:id/fixes

List outstanding fixes ordered by expected AI Score lift.

Response

{
  "data": [
    {
      "id": "fix_01HY...",
      "kind": "add_faq_schema",
      "target_url": "https://example.com/pricing",
      "expected_lift": 4,
      "status": "open"
    }
  ]
}
POST/v1/fixes/:id/apply

Apply a fix via a connected WordPress or Shopify integration.

Response

{ "id": "fix_01HY...", "status": "applied", "applied_at": "2026-04-17T09:15:00Z" }

Content

Programmatic content endpoints — create and manage AI-generated draft content. All posts created via API land as drafts in the connected CMS.

POST/v1/content/drafts

Generate a draft post for a target buyer query.

Request

{
  "site_id": "site_01HGC...",
  "target_query": "how to set up llms.txt",
  "length": "short"
}

Response

{ "id": "draft_01K...", "status": "ready", "cms_draft_url": "https://example.com/wp-admin/post.php?post=4281" }
GET/v1/content/drafts/:id

Retrieve a draft, including its body and metadata.

Response

{ "id": "draft_01K...", "title": "How to set up llms.txt", "body": "..." }

Webhooks

Register a URL to receive events for scans, citations, and fixes. Payloads are signed with an HMAC-SHA256 header so you can verify origin.

POST/v1/webhooks

Register a webhook URL for one or more event types.

Request

{
  "url": "https://example.com/hooks/airrnk",
  "events": ["scan.completed", "citation.created", "fix.applied"]
}

Response

{ "id": "whk_01J...", "secret": "whsec_..." }
GET/v1/webhooks

List registered webhooks.

Response

{ "data": [{ "id": "whk_01J...", "url": "https://...", "events": ["scan.completed"] }] }
DELETE/v1/webhooks/:id

Deregister a webhook.

Response

{ "id": "whk_01J...", "deleted": true }