API Reference

Complete reference for the Ranked AI REST API v1

Base URL

Code

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

Authentication

All requests require a Bearer token in the Authorization header:

Shell

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:

Shell

curl https://app.ranked.ai/api/v1/projects \
  -H "Authorization: Bearer rk_live_your_api_key"

JSON

{
  "data": [
    { "id": "40596405-c27c-...", "name": "My Website", "status": "active", "websiteUrl": "https://example.com" }
  ]
}

Step 2 -- Use the project ID to fetch any data:

Shell

curl "https://app.ranked.ai/api/v1/projects/40596405-c27c-.../rankings/keywords?limit=5" \
  -H "Authorization: Bearer rk_live_your_api_key"

JSON

{
  "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:

Shell

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"]}'

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.
Product mode	Every project is `managed` (Ranked AI's team does the work; the software suite is included in the service plan) or `software` (self-serve SEO Software, billed as prepaid keyword and prompt blocks, no content pipeline). Software projects can be created through the API; managed projects start from the dashboard.

Endpoints

Projects

Method	Path	Description
`GET`	`/projects`	List your SEO projects (`?product_mode=` `managed` or `software` to filter)
`POST`	`/projects`	Create a self-serve software project from a website URL

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

This page is also available as markdown for AI agents, and the whole reference as an OpenAPI spec. Questions? Developer support.