API Reference

Introduction

Authentication

Quickstart

From zero to your first audit result in four steps:

# 1. Get your key + secret: Dashboard → Settings → API & Integrations
# 2. Check your balance
curl "https://www.airanklab.com/api/v1/credits" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-api-secret: YOUR_API_SECRET"

# 3. Start an audit (returns 202 + jobId)
curl -X POST "https://www.airanklab.com/api/v1/audits" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-api-secret: YOUR_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com"}'

# 4. Poll for the result
curl "https://www.airanklab.com/api/v1/jobs/JOB_ID" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-api-secret: YOUR_API_SECRET"

Prefer Postman? Import the ready-made collection from /api/v1/postman.json (in Postman: Import → Link) — it includes every endpoint, saves the last jobId automatically, and only needs your key and secret set as collection variables. Logged-in users can also try every endpoint live in the API Playground.

Async jobs

Credits & billing

API calls spend the same credit balance as the dashboard — a tool costs the same everywhere. Data endpoints are free. Costs per tool call:

Rate limits

Errors

Errors share one envelope: { "success": false, "error": { "code", "message", "details" }, "requestId" }

Get credit balance

Returns your current credit balance, total credits used, and the 20 most recent transactions.

curl "https://www.airanklab.com/api/v1/credits" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-api-secret: YOUR_API_SECRET"

{
  "success": true,
  "data": {
    "balance": 1250,
    "totalUsed": 750,
    "recentTransactions": [
      { "type": "usage", "amount": -50, "description": "Used 50 credits for api_audits.create" }
    ]
  },
  "requestId": "a1b2c3d4e5f6a7b8"
}

AI bot visit statistics

Aggregated AI and search bot visit stats for one of your registered domains: totals, AI bot share, top bots, and top pages. The domain must be registered on your account. Responses are cached for ~2 minutes.

curl "https://www.airanklab.com/api/v1/tracking/stats?domain=example.com" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-api-secret: YOUR_API_SECRET"

{
  "success": true,
  "data": {
    "domain": "example.com",
    "totalVisits": 4821,
    "uniqueBots": 12,
    "aiBotVisits": 3106,
    "visitsLast30Days": 913,
    "topBots": [{ "name": "GPTBot", "count": 1204, "isAIBot": true }],
    "topPages": [{ "url": "/pricing", "count": 402 }]
  },
  "requestId": "..."
}

AI engine citations

Citations of your domain by AI engines (ChatGPT, Claude, Gemini, Perplexity) with a per-bot breakdown. Responses are cached for ~2 minutes.

curl "https://www.airanklab.com/api/v1/citations?domain=example.com&days=30" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-api-secret: YOUR_API_SECRET"

{
  "success": true,
  "data": {
    "domain": "example.com",
    "periodDays": 30,
    "total": 42,
    "byBot": [{ "bot": "ChatGPT", "count": 18 }],
    "citations": [
      { "bot": "ChatGPT", "path": "/blog/what-is-aeo", "timestamp": "2026-07-09T14:02:11Z" }
    ]
  },
  "requestId": "..."
}

Poll an async job

Returns the status of an async tool job and — once status is "completed" — its result. Jobs and results are retained for 7 days. If a job fails, credits are refunded automatically and the refund is visible in /credits.

curl "https://www.airanklab.com/api/v1/jobs/1b9d6bcd-bbfd-4b2d-9b5d-ab8dfbbd4bed" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-api-secret: YOUR_API_SECRET"

{
  "success": true,
  "data": {
    "jobId": "1b9d6bcd-bbfd-4b2d-9b5d-ab8dfbbd4bed",
    "tool": "audits",
    "status": "completed",
    "result": { "...": "tool-specific result object" },
    "creditsCharged": 50,
    "creditsRefunded": false
  },
  "requestId": "..."
}

Run a URL audit

Full technical + AEO audit of a single URL: HTTP and security headers, robots.txt / sitemap / llms.txt, structured data, heading hierarchy, and content quality signals.

curl -X POST "https://www.airanklab.com/api/v1/audits" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-api-secret: YOUR_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/pricing"}'

{
  "success": true,
  "data": {
    "jobId": "…",
    "tool": "audits",
    "status": "pending",
    "creditsCharged": 50,
    "pollUrl": "/api/v1/jobs/…"
  },
  "requestId": "..."
}

Core Web Vitals scan

Google PageSpeed Insights scan for a URL — LCP, INP, CLS and the overall performance score, for mobile or desktop.

curl -X POST "https://www.airanklab.com/api/v1/core-web-vitals" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-api-secret: YOUR_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com","strategy":"mobile"}'

{ "success": true, "data": { "jobId": "…", "status": "pending", "pollUrl": "/api/v1/jobs/…" } }

Keyword research

Keyword research from a website URL (topics are auto-extracted from the site) or from up to 10 seed keywords. Provide either "url" or "keywords" — not both.

curl -X POST "https://www.airanklab.com/api/v1/keyword-research" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-api-secret: YOUR_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"keywords":["answer engine optimization","ai seo"]}'

{ "success": true, "data": { "jobId": "…", "status": "pending", "pollUrl": "/api/v1/jobs/…" } }

AI brand visibility check

Asks an AI engine your prompt and analyzes whether — and how — your brand or domain appears in the answer: mention position, sentiment, citations, and competitor mentions.

curl -X POST "https://www.airanklab.com/api/v1/brand-visibility" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-api-secret: YOUR_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"prompt":"Best AEO platforms?","domain":"example.com","engine":"ChatGPT"}'

{ "success": true, "data": { "jobId": "…", "status": "pending", "pollUrl": "/api/v1/jobs/…" } }

Generate FAQs

Generates 8-10 FAQ question/answer pairs from a page's content, plus a ready-to-embed FAQPage JSON-LD schema block.

curl -X POST "https://www.airanklab.com/api/v1/faq-generator" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-api-secret: YOUR_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/features"}'

{ "success": true, "data": { "jobId": "…", "status": "pending", "pollUrl": "/api/v1/jobs/…" } }

Generate llms.txt

Generates an llms.txt markdown file for a website — the emerging standard that helps AI language models understand, navigate, and cite your site.

curl -X POST "https://www.airanklab.com/api/v1/llms-txt" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-api-secret: YOUR_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com"}'

{ "success": true, "data": { "jobId": "…", "status": "pending", "pollUrl": "/api/v1/jobs/…" } }