Authentication

All requests require an X-API-Key header. Generate yours from the dashboard. Keep it server-side — never expose in client JS.

Getting an API key

1. Sign in to your InstaRank SEO account
2. Go to Settings > API Keys
3. Generate a new API key
4. Store it securely — it won't be shown again

Using your API key

curl -X POST https://instarankseo.com/api/v1/checks/robots-txt \
  -H "X-API-Key: your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{"url": "example.com"}'

Validate your key

GET /api/v1/auth returns the current key status + remaining credits.

curl -H "X-API-Key: your-api-key-here" https://instarankseo.com/api/v1/auth

Rate limits & credits

Two systems run in parallel: per-minute throttle, monthly credit pool.

Response format

All endpoints return application/json. Top-level shape is consistent across every check.

Success

{
  "success": true,
  "check": "robots-txt",
  "url": "https://example.com",
  "domain": "example.com",
  "score": 85,
  "issues": [
    {
      "id": "no-sitemap-reference",
      "title": "No sitemap reference",
      "description": "robots.txt does not reference a sitemap",
      "severity": "moderate"
    }
  ],
  "data": { /* full check breakdown */ },
  "checkedAt": "2026-05-07T14:32:18.401Z",
  "meta": {
    "requestId": "a1b2c3d4e5f60718",
    "creditsUsed": 1,
    "creditsRemaining": 487,
    "processingTimeMs": 843,
    "apiVersion": "1.0"
  }
}

Error

Every non-2xx response shares the canonical envelope. Branch on code (machine-readable enum) and decide retry from retryable.errorType is a legacy alias kept for pre-2026 clients.

{
  "success": false,
  "error": "Invalid URL format",
  "code": "INVALID_URL",
  "retryable": false,
  "requestId": "a6b6777f25f54236",
  "errorType": "INVALID_URL",
  "details": { /* optional structured context */ }
}

The same requestId appears in the X-Request-ID response header — include it when reporting issues to support.

Idempotency-Key

Safe to retry POST requests without double-charging. Send an Idempotency-Key header (≤255 printable-ASCII chars — UUIDs work well). A retry with the same key + body returns the cached response with Idempotency-Replayed: true.

# First call — runs the check, debits 1 credit.
curl -X POST https://instarankseo.com/api/v1/checks/meta-tags \
  -H "X-API-Key: your-api-key" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"url":"example.com"}'

# Same key + body within 24h — returns cached result.
# Response header: Idempotency-Replayed: true
# No credit re-charged.

SEO check endpoints

19 endpoints. All POST. Body: {"url": "example.com"}. Click any row to see the full request/response example.

Domain endpoints

Domain-level metrics that aggregate multiple signals into single composite scores.

Error codes

Quick-start examples

Copy-paste-go in Python or Node. Replace your-api-key with the key from your dashboard.

Python (requests)

import requests

API_KEY = "your-api-key"
BASE_URL = "https://instarankseo.com/api/v1"

response = requests.post(
    f"{BASE_URL}/checks/meta-tags",
    headers={
        "X-API-Key": API_KEY,
        "Content-Type": "application/json",
    },
    json={"url": "example.com"},
)

data = response.json()
print(f"Score: {data['score']}/100")
for issue in data.get("issues", []):
    print(f"  [{issue['severity']}] {issue['title']}")

JavaScript / Node (fetch)

const API_KEY = "your-api-key";
const BASE_URL = "https://instarankseo.com/api/v1";

const response = await fetch(`${BASE_URL}/checks/robots-txt`, {
  method: "POST",
  headers: {
    "X-API-Key": API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ url: "example.com" }),
});

const data = await response.json();
console.log(`Score: ${data.score}/100`);
console.log(`Issues: ${data.issues?.length ?? 0}`);

Batch all checks (bash)

# Run all 19 standalone API check endpoints
CHECKS=(robots-txt sitemap meta-tags canonical-url http-status url-structure \
  internal-links external-links outbound-links mixed-content x-robots-tag \
  keywords content-quality eeat page-speed backlinks llm-optimization \
  social-media spam-score)

for check in "${CHECKS[@]}"; do
  echo "Running $check..."
  curl -s -X POST "https://instarankseo.com/api/v1/checks/$check" \
    -H "X-API-Key: your-api-key" \
    -H "Content-Type: application/json" \
    -d '{"url": "example.com"}' | jq '{check: .check, score: .score}'
done