# Quickstart

Source: https://www.ranked.ai/developers/quickstart

> Make your first API call in under 2 minutes

## 1. Create an API key

- [Create an API Key](https://app.ranked.ai/dashboard/settings?tab=api-keys): 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

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

## 2. Find your project ID

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

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

```javascript JavaScript
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
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']}")
```

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.

> **Tip:** No project yet? A Read + Write key can [create a software project](https://www.ranked.ai/developers/api-reference/projects/create) from a website URL, no plan or payment needed.

## 3. Fetch your data

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

### Keyword rankings

```bash cURL
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
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
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']}")
```

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](https://www.ranked.ai/developers/api-reference/introduction) 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.**

```text
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:
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 (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/{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
```

## Next steps

  - [API Reference](https://www.ranked.ai/developers/api-reference/introduction): Full endpoint documentation with examples.
  - [Webhooks](https://www.ranked.ai/developers/webhooks/overview): Get notified when keyword positions update, content changes, or audits complete.
  - [MCP Integration](https://www.ranked.ai/developers/mcp/overview): Connect Ranked AI to ChatGPT, Claude, or Cursor.
  - [Agency Dashboard](https://www.ranked.ai/developers/guides/agency-dashboard): Build a custom client dashboard with the API and webhooks.