---
name: ranked-ai
description: Use when building integrations with Ranked AI's SEO data - keyword rankings, AI visibility (ChatGPT, Claude, Gemini, Perplexity, Grok, Meta), site audits, backlinks, content calendars, reports and webhooks - via the REST API v1, the TypeScript SDK or the MCP server.
---

# Ranked AI developer skill

Ranked AI exposes its SEO platform data through a REST API, a TypeScript SDK and an MCP server. This skill tells an AI coding tool where the documentation lives and the facts it needs before writing code.

## Documentation

- Documentation index (one line per page): https://www.ranked.ai/developers/llms.txt
- Every documentation page is available as markdown by appending `.md` to its URL, for example https://www.ranked.ai/developers/quickstart.md
- Full documentation in one file: https://www.ranked.ai/developers/llms-full.txt
- OpenAPI 3.1 specification: https://www.ranked.ai/developers/openapi.json
- TypeScript SDK source (single file, zero dependencies): https://www.ranked.ai/developers/sdk/ranked-ai.ts

Fetch the index first, then the specific pages you need. Do not guess endpoint shapes; the API reference pages carry full request and response examples.

## Key facts

- Base URL: `https://app.ranked.ai/api/v1`
- Authentication: `Authorization: Bearer rk_live_...` (API keys are created in the dashboard under Settings > API; read-only keys cover every GET, read+write keys are needed for POST/PATCH/DELETE)
- Everything is scoped to a project: call `GET /projects` first, then use the project id in `/projects/{projectId}/...` paths
- Responses: `{ "success": true, "data": ..., "meta": { "pagination": { "total", "limit", "offset", "has_more" } } }`
- Rate limits: 200 requests/minute, 5,000/hour, 50,000/day per key
- Webhooks: `POST /webhooks` with `url`, `project_id` and an `events` array; deliveries are signed with an `X-Webhook-Signature` HMAC-SHA256 header
- MCP server: `https://app.ranked.ai/api/mcp` (OAuth, not API keys) - setup at https://www.ranked.ai/developers/mcp/setup

## Product modes

Every project has a `productMode`: `managed` (Ranked AI's team does the work; the full software suite is included in the service plan, never billed separately) or `software` (self-serve SEO Software the account runs itself, billed as prepaid blocks of $4.99/month per 100 tracked keywords or 100 AI prompts, one plan per account, no content pipeline). `POST /projects` creates software projects only; managed projects start from the dashboard. A software project upgrades to the managed service via its `addServiceUrl`.

## Endpoints

- `GET /projects` - list projects (`?product_mode=managed|software`)
- `POST /projects` - create a self-serve software project from `{ website_url, name? }` (write key; response carries `plan.active`, `plan.manageUrl`, `addServiceUrl`)
- `GET /projects/{id}/rankings/keywords` and `.../keywords/{keywordId}/history` - positions across Desktop, Mobile, AI Mode and Maps
- `GET /projects/{id}/prompts`, `.../prompts/{promptId}`, `.../prompts/{promptId}/history` - AI visibility per model with citations
- `GET /projects/{id}/audits`, `.../audits/latest`, `.../audits/{auditId}/issues` - site audits and issues
- `GET /projects/{id}/backlinks`, `.../summary`, `.../domains`, `.../history`, `.../anchors` - backlink profile
- `GET /projects/{id}/content`, `.../content/{contentId}`, `GET|PATCH .../content/preferences` - content calendar
- `GET|POST /projects/{id}/reports`, `GET|DELETE .../reports/{reportId}` - shareable report links
- `GET|POST /webhooks`, `GET|PATCH|DELETE /webhooks/{webhookId}`, `POST /webhooks/{webhookId}/test` - webhook subscriptions