Quickstart

Make your first API call in under 2 minutes

Open in ChatGPT Add as Preferred Source

1. Create an API key

Create an API Key

Go to Settings > API in your Ranked AI dashboard.

Choose your permission level:

Read Only (default) -- fetch keywords, audits, backlinks, AI visibility, content, and reports
Read + Write -- everything above, plus create reports, manage webhooks, and update preferences

2. Find your project ID

Every API call requires a project ID. List your projects to find it:

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

Response:

JSON

{
  "data": [
    {
      "id": "40596405-c27c-4dfc-89e4-142c87846d66",
      "name": "My Website",
      "status": "active",
      "serviceType": "seo",
      "productMode": "managed",
      "websiteUrl": "https://example.com"
    }
  ]
}

Copy the id value -- you'll use it in all subsequent calls. productMode tells you whether Ranked AI's team runs the project (managed) or you run it yourself with the software (software); the data endpoints work the same for both, and software projects simply have no content calendar.

3. Fetch your data

Use the project ID to pull keyword rankings, audit results, AI visibility, and more.

Keyword rankings

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

Each keyword includes positions across four channels:

Field	Description
`desktop_position`	Google Desktop rank
`mobile_position`	Google Mobile rank
`ai_mode_position`	Google AI Mode rank
`maps_position`	Google Maps rank
`net_change`	Combined position change across all channels

What else is available

Endpoint	What it returns
`GET /rankings/keywords`	Keyword positions across Desktop, Mobile, AI Mode, Maps
`GET /prompts`	AI visibility across ChatGPT, Claude, Gemini, Perplexity, Grok, Meta
`GET /audits/latest`	Latest site audit results with issue counts
`GET /backlinks/summary`	Backlink profile with referring domains
`GET /content`	Content calendar with status and scheduling
`GET /reports`	Shareable SEO report links
`POST /webhooks`	Real-time notifications when data changes
`POST /projects`	Create a self-serve software project (no plan needed to create it)

See the full API reference for all endpoints and parameters.

Build with AI

Copy this prompt into Cursor, Claude, or ChatGPT to build an integration:

Give this to your AI coding tool to build a Ranked AI integration.

I need to integrate with the Ranked AI REST API. Here's everything you need:

Base URL: https://app.ranked.ai/api/v1
Auth: Bearer token in Authorization header (format: rk_live_...)
Docs: https://www.ranked.ai/developers

How it works:


GET /projects → returns array of projects with id, name, websiteUrl, status
Use project ID in all other endpoints: /projects//...
Available endpoints:


GET /projects → list SEO projects (each has productMode "managed" or "software"; ?product_mode= filters)
POST /projects → create a self-serve software project from { website_url, name? } (needs write key; response has plan.active + plan.manageUrl)
GET /projects//rankings/keywords?limit=1000 → keyword positions (desktop_position, mobile_position, ai_mode_position, maps_position, net_change, location, last_checked)
GET /projects//rankings/keywords//history → daily position history
GET /projects//prompts?limit=200 → AI visibility across ChatGPT, Claude, Gemini, Perplexity, Grok, Meta (visibility_percentage, average_position, latest_responses per model)
GET /projects//prompts//history → full AI model responses with citations
GET /projects//audits/latest → latest site audit (total_issues, critical_issues, warning_issues, notice_issues)
GET /projects//audits//issues → individual audit issues with severity and affected_count
GET /projects//backlinks/summary → total backlinks, referring domains
GET /projects//backlinks/domains?limit=100 → referring domains with domain_rank
GET /projects//content?limit=100 → content calendar (title, status, scheduled_date)
GET /projects//reports → shareable report links
POST /projects//reports → create report (needs write key)
All responses: { success: true, data: [...], meta: { pagination: { total, limit, offset, has_more } } }

Webhooks (needs write key):


POST /webhooks → create subscription with url, project_id, events array
Events: keywords.updated, content.status_changed, content.created, audit.started, audit.completed, prompts.updated
Payloads include X-Webhook-Signature header (HMAC-SHA256) for verification
Rate limits: 200/min, 5000/hr, 50000/day per key
Max limits: 1000 keywords, 200 prompts, 500 projects per request

Next steps

API Reference

Full endpoint documentation with examples.

Webhooks

Get notified when keyword positions update, content changes, or audits complete.

MCP Integration

Connect Ranked AI to ChatGPT, Claude, or Cursor.

Agency Dashboard

Build a custom client dashboard with the API and webhooks.

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