Skip to main content

​
Base URL

https://app.ranked.ai/api/v1

​
Authentication

All requests require a Bearer token in the Authorization header: 
curl https://app.ranked.ai/api/v1/projects \
  -H "Authorization: Bearer rk_live_your_api_key"
Create API keys from Settings > API in your dashboard.

​
Permissions

Key TypeCan do
Read Only (default)Fetch all data: keywords, audits, backlinks, AI visibility, content, reports
Read + WriteEverything above, plus: create reports, manage webhooks, update content preferences
All GET endpoints work with read-only keys. POST, PATCH, and DELETE require read+write.

​
How it works

All data is organized by project. A project represents one website you’re tracking in Ranked AI. Step 1 — Get your project IDs: 
curl https://app.ranked.ai/api/v1/projects \
  -H "Authorization: Bearer rk_live_your_api_key"

{
  "data": [
    { "id": "40596405-c27c-...", "name": "My Website", "status": "active", "websiteUrl": "https://example.com" }
  ]
}
Step 2 — Use the project ID to fetch any data: 
curl "https://app.ranked.ai/api/v1/projects/40596405-c27c-.../rankings/keywords?limit=5" \
  -H "Authorization: Bearer rk_live_your_api_key"

{
  "data": [
    {
      "keyword": "tree care services",
      "desktop_position": 5,
      "mobile_position": 3,
      "ai_mode_position": 3,
      "maps_position": 3,
      "net_change": 93,
      "location": "Sioux City, Iowa, United States"
    }
  ]
}
Step 3 (optional) — Set up webhooks to get notified when data changes: 
curl -X POST https://app.ranked.ai/api/v1/webhooks \
  -H "Authorization: Bearer rk_live_your_write_key" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://your-app.com/webhook","project_id":"40596405-c27c-...","events":["keywords.updated"]}'
Each API key can access all projects owned by the account that created it. If you manage multiple client websites, they’ll all appear in the projects list.

​
Key concepts

TermWhat it means
KeywordsSearch terms you’re tracking in Google. Positions tracked across Desktop, Mobile, AI Mode (Google’s AI search), and Google Maps.
AI VisibilityHow often your brand appears when people ask AI tools (ChatGPT, Claude, Gemini, Perplexity, Grok, Meta) questions related to your business. Each tracked question is called a “prompt”.
Net ChangeThe total position improvement across all four search channels (Desktop + Mobile + AI Mode + Maps). Positive = you moved up.
AuditsAutomated site crawls that find SEO issues like missing tags, broken pages, and performance problems.

​
Endpoints

​
Projects

MethodPathDescription
GET/projectsList your SEO projects

​
Keywords

MethodPathDescription
GET/projects/{id}/rankings/keywordsKeyword positions across all channels
GET/projects/{id}/rankings/keywords/{keywordId}/historyDaily position history for a keyword

​
AI Visibility

MethodPathDescription
GET/projects/{id}/promptsAI visibility prompts with per-model data
GET/projects/{id}/prompts/{promptId}Single prompt detail
GET/projects/{id}/prompts/{promptId}/historyModel response history with citations

​
Audits

MethodPathDescription
GET/projects/{id}/auditsList audit tasks
GET/projects/{id}/audits/latestMost recent completed audit
GET/projects/{id}/audits/{auditId}/issuesIssues for a specific audit
MethodPathDescription
GET/projects/{id}/backlinksTracked backlink targets
GET/projects/{id}/backlinks/summaryTotal backlinks and referring domains
GET/projects/{id}/backlinks/domainsReferring domains with domain rank
GET/projects/{id}/backlinks/historyDaily new/lost backlink counts
GET/projects/{id}/backlinks/anchorsAnchor text analysis

​
Content

MethodPathDescription
GET/projects/{id}/contentContent calendar items
GET/projects/{id}/content/{contentId}Full content with article body
GET PATCH/projects/{id}/content/preferencesContent preferences

​
Reports

MethodPathDescription
GET POST/projects/{id}/reportsList or create report links
GET DELETE/projects/{id}/reports/{reportId}Get or delete a report

​
Webhooks

MethodPathDescription
GET POST/webhooksList or create webhook subscriptions
GET PATCH DELETE/webhooks/{webhookId}Manage a webhook
POST/webhooks/{webhookId}/testSend a test delivery