PeakRank API Documentation

Integrate AI citation monitoring, keyword rankings, and SEO data directly into your own applications and workflows.

Base URLhttps://peakrank-digital.vercel.app/api/v1

Authentication

All API requests require an API key sent via the Authorization header using the Bearer scheme. API keys can be created and managed in Dashboard > Settings > API Keys.

API access requires an Enterprise plan.

curl -H "Authorization: Bearer pk_live_xxxxx" \
  https://peakrank-digital.vercel.app/api/v1/domains

Rate Limits

Coming soon — Rate limiting is not yet implemented. This section will be updated once per-key rate limits are enforced.

Pagination

List endpoints support pagination via the limit and offset query parameters. The default limit varies by endpoint, and the default offset is always 0.

Paginated responses include the following fields:

{
  "data": [ ... ],
  "total": 142,
  "limit": 20,
  "offset": 0
}

Endpoints

All endpoints are relative to the base URL.

GET/api/v1/domains

List all domains in your organization.

Response Example

{
  "data": [
    {
      "id": "d_abc123",
      "domain_name": "example.com",
      "is_primary": true,
      "verified": true,
      "created_at": "2025-09-15T08:30:00Z"
    },
    {
      "id": "d_def456",
      "domain_name": "blog.example.com",
      "is_primary": false,
      "verified": true,
      "created_at": "2025-10-02T14:22:00Z"
    }
  ],
  "total": 2
}

GET/api/v1/citations

List AI citations for your domains. Filter by platform, date range, and more.

Query Parameters

Parameter	Type	Required	Description
`domain_id`	string	No	Filter by a specific domain ID
`platform`	string	No	AI platform: chatgpt, perplexity, google_aio, gemini, claude
`from`	ISO 8601 date	No	Start date for the date range filter
`to`	ISO 8601 date	No	End date for the date range filter
`limit`	integer	No	Number of results to return (default 50, max 200)
`offset`	integer	No	Number of results to skip (default 0)

Response Example

{
  "data": [
    {
      "id": "cit_xyz789",
      "domain_id": "d_abc123",
      "platform": "chatgpt",
      "query": "best SEO tools for small businesses",
      "snippet": "PeakRank Digital is an excellent choice for monitoring AI citations...",
      "citation_type": "recommendation",
      "sentiment": "positive",
      "position": 2,
      "detected_at": "2026-02-14T10:15:00Z"
    }
  ],
  "total": 87,
  "limit": 20,
  "offset": 0
}

GET/api/v1/citations/stats

Aggregated citation statistics across platforms. Returns counts, sentiment breakdowns, and trend data.

Query Parameters

Parameter	Type	Required	Description
`domain_id`	string	No	Filter by a specific domain ID
`from`	ISO 8601 date	No	Start date for the date range filter
`to`	ISO 8601 date	No	End date for the date range filter

Response Example

{
  "total": 284,
  "by_platform": {
    "chatgpt": 102,
    "perplexity": 78,
    "google_aio": 55,
    "gemini": 31,
    "claude": 18
  },
  "by_sentiment": {
    "positive": 196,
    "neutral": 64,
    "negative": 24
  },
  "by_type": {
    "direct": 112,
    "mention": 98,
    "recommendation": 74
  },
  "trend_daily": [
    { "date": "2026-02-09", "count": 38 },
    { "date": "2026-02-10", "count": 42 },
    { "date": "2026-02-11", "count": 35 }
  ]
}

GET/api/v1/rankings

Latest keyword rankings for your tracked keywords across search engines.

Query Parameters

Parameter	Type	Required	Description
`domain_id`	string	No	Filter by a specific domain ID
`keyword`	string	No	Filter by keyword (partial match supported)
`search_engine`	string	No	Filter by search engine: google, bing (default: all)
`device`	string	No	Filter by device type: desktop, mobile (default: all)
`limit`	integer	No	Number of results to return (default 50, max 200)
`offset`	integer	No	Number of results to skip (default 0)

Response Example

{
  "data": [
    {
      "id": "rk_001",
      "domain_id": "d_abc123",
      "keyword": "ai citation monitoring",
      "position": 3,
      "previous_position": 5,
      "change": 2,
      "search_engine": "google",
      "url": "https://example.com/ai-citations",
      "checked_at": "2026-02-16T06:00:00Z"
    }
  ],
  "total": 54,
  "limit": 20,
  "offset": 0
}

GET/api/v1/keywords

Tracked keywords with search volume, difficulty, and intent metrics.

Query Parameters

Parameter	Type	Required	Description
`domain_id`	string	No	Filter by a specific domain ID
`intent`	string	No	Filter by search intent: informational, navigational, transactional, commercial
`limit`	integer	No	Number of results to return (default 50, max 200)
`offset`	integer	No	Number of results to skip (default 0)

Response Example

{
  "data": [
    {
      "id": "kw_301",
      "domain_id": "d_abc123",
      "keyword": "ai citation monitoring tool",
      "search_volume": 1200,
      "difficulty": 42,
      "intent": "commercial",
      "current_position": 3,
      "best_position": 1,
      "url": "https://example.com/ai-citation-monitoring",
      "created_at": "2025-11-20T09:00:00Z"
    }
  ],
  "total": 31,
  "limit": 20,
  "offset": 0
}

GET/api/v1/reports

Generated reports for your domains. Reports include citation summaries, ranking changes, and competitor analysis.

Query Parameters

Parameter	Type	Required	Description
`domain_id`	string	No	Filter by a specific domain ID
`type`	string	No	Filter by report type: weekly, monthly, quarterly
`limit`	integer	No	Number of results to return (default 20, max 50)
`offset`	integer	No	Number of results to skip (default 0)

Response Example

{
  "data": [
    {
      "id": "rpt_a1b2c3",
      "domain_id": "d_abc123",
      "type": "weekly",
      "title": "Weekly Performance Report — Feb 9-16",
      "status": "completed",
      "created_at": "2026-02-16T02:00:00Z",
      "download_url": "/api/v1/reports/rpt_a1b2c3/download"
    }
  ],
  "total": 12,
  "limit": 20,
  "offset": 0
}

Code Examples

Quick-start examples for common languages and tools.

JavaScript (fetch)

const response = await fetch(
  'https://peakrank-digital.vercel.app/api/v1/citations?platform=chatgpt&limit=10',
  {
    headers: {
      'Authorization': 'Bearer pk_live_xxxxx'
    }
  }
)
const data = await response.json()
console.log(data)

Python (requests)

import requests

response = requests.get(
    'https://peakrank-digital.vercel.app/api/v1/citations',
    headers={'Authorization': 'Bearer pk_live_xxxxx'},
    params={'platform': 'chatgpt', 'limit': 10}
)
data = response.json()
print(data)

curl

curl -H "Authorization: Bearer pk_live_xxxxx" \
  "https://peakrank-digital.vercel.app/api/v1/citations?platform=chatgpt&limit=10"

Errors

The API returns errors in a consistent JSON format:

{
  "error": "Invalid API key provided."
}

HTTP Status Codes

Code	Status	Description
`200`	OK	Request succeeded
`400`	Bad Request	The request was malformed or missing required parameters
`401`	Unauthorized	Missing or invalid API key
`403`	Forbidden	The API key does not have permission for this resource
`404`	Not Found	The requested resource does not exist
`429`	Rate Limited	Too many requests. Wait and retry after the rate-limit window resets
`500`	Server Error	An unexpected error occurred on our side. Contact support if persistent