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

# Quickstart

> Make your first API call in under 2 minutes

## 1. Create an API key

<Card title="Create an API Key" icon="key" href="https://app.ranked.ai/dashboard/settings?tab=api-keys">
  Go to Settings > API in your Ranked AI dashboard.
</Card>

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

<Warning>
  API keys are shown only once when created. Copy and store it securely. Keys are tied to the project owner account and can only access projects you own directly.
</Warning>

## 2. Find your project ID

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

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

  ```javascript JavaScript theme={null}
  const response = await fetch('https://app.ranked.ai/api/v1/projects', {
    headers: { 'Authorization': 'Bearer rk_live_your_api_key' }
  });
  const { data } = await response.json();

  data.forEach(project => {
    console.log(`${project.name}: ${project.id}`);
  });
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
      'https://app.ranked.ai/api/v1/projects',
      headers={'Authorization': 'Bearer rk_live_your_api_key'}
  )
  for project in response.json()['data']:
      print(f"{project['name']}: {project['id']}")
  ```
</CodeGroup>

Response:

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

Copy the `id` value -- you'll use it in all subsequent calls.

## 3. Fetch your data

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

### Keyword rankings

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://app.ranked.ai/api/v1/projects/YOUR_PROJECT_ID/rankings/keywords?limit=10" \
    -H "Authorization: Bearer rk_live_your_api_key"
  ```

  ```javascript JavaScript theme={null}
  const base = `https://app.ranked.ai/api/v1/projects/${projectId}`;
  const headers = { 'Authorization': `Bearer ${apiKey}` };

  const response = await fetch(`${base}/rankings/keywords?limit=10`, { headers });
  const { data } = await response.json();

  data.forEach(kw => {
    console.log(`${kw.keyword}: Desktop ${kw.desktop_position}, Mobile ${kw.mobile_position}, Net Change ${kw.net_change > 0 ? '+' : ''}${kw.net_change}`);
  });
  ```

  ```python Python theme={null}
  import requests

  base = f'https://app.ranked.ai/api/v1/projects/{project_id}'
  headers = {'Authorization': f'Bearer {api_key}'}

  response = requests.get(f'{base}/rankings/keywords', headers=headers, params={'limit': 10})
  for kw in response.json()['data']:
      print(f"{kw['keyword']}: Desktop {kw['desktop_position']}, Net Change {kw['net_change']}")
  ```
</CodeGroup>

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                            |

See the [full API reference](/api-reference/introduction) for all endpoints and parameters.

## Build with AI

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

<Prompt description="Give this to your AI coding tool to build a Ranked AI integration." actions={["copy", "cursor"]}>
  I need to integrate with the Ranked AI REST API. Here's everything you need:

  Base URL: [https://app.ranked.ai/api/v1](https://app.ranked.ai/api/v1)
  Auth: Bearer token in Authorization header (format: rk\_live\_...)
  Docs: [https://dev.ranked.ai](https://dev.ranked.ai)

  How it works:

  1. GET /projects → returns array of projects with id, name, websiteUrl, status
  2. Use project ID in all other endpoints: /projects/{projectId}/...

  Available endpoints:

  * GET /projects → list SEO projects
  * GET /projects/{id}/rankings/keywords?limit=1000 → keyword positions (desktop\_position, mobile\_position, ai\_mode\_position, maps\_position, net\_change, location, last\_checked)
  * GET /projects/{id}/rankings/keywords/{keywordId}/history → daily position history
  * GET /projects/{id}/prompts?limit=200 → AI visibility across ChatGPT, Claude, Gemini, Perplexity, Grok, Meta (visibility\_percentage, average\_position, latest\_responses per model)
  * GET /projects/{id}/prompts/{promptId}/history → full AI model responses with citations
  * GET /projects/{id}/audits/latest → latest site audit (total\_issues, critical\_issues, warning\_issues, notice\_issues)
  * GET /projects/{id}/audits/{auditId}/issues → individual audit issues with severity and affected\_count
  * GET /projects/{id}/backlinks/summary → total backlinks, referring domains
  * GET /projects/{id}/backlinks/domains?limit=100 → referring domains with domain\_rank
  * GET /projects/{id}/content?limit=100 → content calendar (title, status, scheduled\_date)
  * GET /projects/{id}/reports → shareable report links
  * POST /projects/{id}/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
</Prompt>

## Next steps

<Columns cols={2}>
  <Card title="API Reference" icon="book" href="/api-reference/introduction">
    Full endpoint documentation with examples.
  </Card>

  <Card title="Webhooks" icon="bell" href="/webhooks/overview">
    Get notified when keyword positions update, content changes, or audits complete.
  </Card>

  <Card title="MCP Integration" icon="plug" href="/mcp/overview">
    Connect Ranked AI to ChatGPT, Claude, or Cursor.
  </Card>

  <Card title="Agency Dashboard" icon="chart-mixed" href="/guides/agency-dashboard">
    Build a custom client dashboard with the API and webhooks.
  </Card>
</Columns>