> ## Documentation Index
> Fetch the complete documentation index at: https://dev.ranked.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# API Reference

> Complete reference for the Ranked AI REST API v1

## Base URL

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

## Authentication

All requests require a Bearer token in the `Authorization` header:

```bash theme={null}
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](https://app.ranked.ai/dashboard/settings?tab=api-keys).

### 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:

```bash theme={null}
curl https://app.ranked.ai/api/v1/projects \
  -H "Authorization: Bearer rk_live_your_api_key"
```

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

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

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

```json theme={null}
{
  "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:

```bash theme={null}
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"]}'
```

<Info>
  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.
</Info>

## 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                 |