API Reference - Ranked AI

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 Type	Can do
Read Only (default)	Fetch all data: keywords, audits, backlinks, AI visibility, content, reports
Read + Write	Everything 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

Term	What it means
Keywords	Search terms you’re tracking in Google. Positions tracked across Desktop, Mobile, AI Mode (Google’s AI search), and Google Maps.
AI Visibility	How 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 Change	The total position improvement across all four search channels (Desktop + Mobile + AI Mode + Maps). Positive = you moved up.
Audits	Automated site crawls that find SEO issues like missing tags, broken pages, and performance problems.

Endpoints

Projects

Method	Path	Description
`GET`	`/projects`	List your SEO projects

Keywords

Method	Path	Description
`GET`	`/projects/{id}/rankings/keywords`	Keyword positions across all channels
`GET`	`/projects/{id}/rankings/keywords/{keywordId}/history`	Daily position history for a keyword

AI Visibility

Method	Path	Description
`GET`	`/projects/{id}/prompts`	AI visibility prompts with per-model data
`GET`	`/projects/{id}/prompts/{promptId}`	Single prompt detail
`GET`	`/projects/{id}/prompts/{promptId}/history`	Model response history with citations

Audits

Method	Path	Description
`GET`	`/projects/{id}/audits`	List audit tasks
`GET`	`/projects/{id}/audits/latest`	Most recent completed audit
`GET`	`/projects/{id}/audits/{auditId}/issues`	Issues for a specific audit

Backlinks

Method	Path	Description
`GET`	`/projects/{id}/backlinks`	Tracked backlink targets
`GET`	`/projects/{id}/backlinks/summary`	Total backlinks and referring domains
`GET`	`/projects/{id}/backlinks/domains`	Referring domains with domain rank
`GET`	`/projects/{id}/backlinks/history`	Daily new/lost backlink counts
`GET`	`/projects/{id}/backlinks/anchors`	Anchor text analysis

Content

Method	Path	Description
`GET`	`/projects/{id}/content`	Content calendar items
`GET`	`/projects/{id}/content/{contentId}`	Full content with article body
`GET` `PATCH`	`/projects/{id}/content/preferences`	Content preferences

Reports

Method	Path	Description
`GET` `POST`	`/projects/{id}/reports`	List or create report links
`GET` `DELETE`	`/projects/{id}/reports/{reportId}`	Get or delete a report

Webhooks

Method	Path	Description
`GET` `POST`	`/webhooks`	List or create webhook subscriptions
`GET` `PATCH` `DELETE`	`/webhooks/{webhookId}`	Manage a webhook
`POST`	`/webhooks/{webhookId}/test`	Send a test delivery

​Base URL

​Authentication

​Permissions

​How it works

​Key concepts

​Endpoints

​Projects

​Keywords

​AI Visibility

​Audits

​Backlinks

​Content

​Reports

​Webhooks

Base URL

Authentication

Permissions

How it works

Key concepts

Endpoints

Projects

Keywords

AI Visibility

Audits

Backlinks

Content

Reports

Webhooks