# SerpDino REST API — Full Reference

> Programmatic access to keyword rankings, SERP data, keyword research, competitor analysis, and Core Web Vitals.

This document is the authoritative LLM-readable reference for the SerpDino REST API.
A machine-parseable OpenAPI 3.1 spec is available at https://serpdino.com/api/openapi.json.

## Authentication

All endpoints require an API key. Send it on every request:

```http
Authorization: Bearer sd_your_key_here
```

Create keys in **Dashboard → Settings → API Keys**. Maximum 5 active keys per user.

## Use with AI agents (MCP)

Point any MCP-compatible client (Claude, ChatGPT, Cursor, etc.) at `https://serpdino.com/api/mcp` with header `Authorization: Bearer sd_your_key_here`. All 28 tools become available immediately — no install required.

## Base URL

```
https://serpdino.com
```

## Error handling

- All error responses are JSON. The error message lives in the `message` field (NOT `error`).
- Some responses include `success: false` alongside `message`; account/auth errors may omit `success` entirely. Clients should treat any non-2xx status OR `success === false` as an error.
- `/api/tools/keyword-research` returns HTTP 200 with `{ success: false, message }` for all expected failures (bad seed, unsupported geo/lang, upstream timeout). Always check `success` in addition to HTTP status.
- `/api/projects/keyword-ideas` returns HTTP 200 with `{ success: true, ideas: [] }` even when the upstream scraper is unreachable — an empty `ideas` array means "no data available right now," not necessarily success.
- Write endpoints that mutate project data (`POST/DELETE` on `/api/projects/keywords`, `/api/scrape/new-keywords`, `POST/DELETE` on `/api/projects/notes`, `/api/tools/keyword-research`, `/api/projects/keyword-ideas`, `/api/projects/keyword-suggestions`, folder writes) require an **active subscription** — return HTTP 403 `{ message: "Account suspended", suspended: true }` if the account is suspended.
- Many read endpoints bypass auth entirely when the target project has `shared: true` (public dashboard links). Affected: `/api/projects/:id`, `keyword-updates`, `position-history`, `keyword-volumes`, `competitor-positions`, `pages`, `pages-pagespeed`, `notes` (GET), `export`, `export-agent`.
- These domain-level read endpoints are fully **public** (no API key required): `/api/projects/competitors-filtered`, `/api/projects/pagespeed`, `/api/projects/crux-history`, `/api/projects/similarweb`. They read from our DB cache only — no auth needed. Each is rate-limited to 60 req / min (600 / hour) per IP.

### Status codes

| Code | Label | Meaning |
|---|---|---|
| 400 | Bad Request | Missing required parameter or invalid value |
| 401 | Unauthorized | Missing or invalid API key. Body: { message } or { success: false } |
| 403 | Forbidden | Account suspended. Body: { message: "Account suspended", suspended: true } |
| 404 | Not Found | Resource (project, folder, note) does not exist or belongs to another user |
| 405 | Method Not Allowed | HTTP method not supported for this endpoint |
| 429 | Too Many Requests | Rate limit exceeded. /api/tools/serp-check and /api/tools/traffic-check allow 5 req / 60s per API key. /api/tools/keyword-research and /api/projects/keyword-ideas allow 10 req / min (100 / hour) per account. Public endpoints (competitors-filtered, pagespeed, crux-history, similarweb) allow 60 req / min (600 / hour) per IP. Body includes retryAfter (seconds); a Retry-After header is also set. |
| 500 | Server Error | Internal server error |

## Projects

Create and manage SEO tracking projects.

### `GET /api/projects`

List all projects

**Success response:** HTTP 200

```json
{
  "success": true,
  "projects": [
    {
      "_id": "65f1c2a8e1234567890abcde",
      "name": "Acme Corp",
      "domain": "acme.com",
      "aliases": [],
      "competitors": [
        "competitor.com"
      ],
      "folder": null,
      "updateFrequency": "daily",
      "serpTop": 50,
      "createdDate": "2025-01-15T08:32:11.000Z"
    }
  ]
}
```

**Example:**

```bash
curl -H "Authorization: Bearer sd_your_key_here" \
  https://serpdino.com/api/projects
```

### `GET /api/projects/:id`

Get project details

Includes keywords[], domain, competitors[], and full settings.

**Parameters:**

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string | yes | Project ID (Mongo ObjectId) |

**Success response:** HTTP 200

```json
{
  "success": true,
  "project": {
    "_id": "65f1c2a8e1234567890abcde",
    "name": "Acme Corp",
    "domain": "acme.com",
    "competitors": [
      "competitor.com"
    ],
    "keywords": [
      {
        "_id": "65f1c2a8e1234567890fffff",
        "keyword": "seo tools",
        "geoCode": "US",
        "langCode": "en"
      }
    ]
  }
}
```

**Example:**

```bash
curl -H "Authorization: Bearer sd_your_key_here" \
  https://serpdino.com/api/projects/PROJECT_ID
```

### `POST /api/projects`

Create a new project

Returns HTTP 201 on success. Fires fire-and-forget triggers for keyword suggestions, SimilarWeb, PageSpeed, and competitor analysis.

**Parameters:**

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `name` | body | string | yes | Project name |
| `domain` | body | string | yes | Target domain (e.g. example.com). Lowercased server-side. |
| `folder` | body | string | no | Folder ID to place project in |
| `icon` | body | string | no | Icon identifier or URL |
| `aliases` | body | string | no | Comma/newline-separated alternative domains (treated as same property) |
| `competitors` | body | string[] | no | Competitor domains (PUT only — POST ignores this field) |
| `shared` | body | boolean | no | Whether project is shared via public link (default: false) |
| `updateFrequency` | body | enum (daily \| every3days \| weekly \| biweekly \| custom) | no | daily | every3days | weekly | biweekly | custom (default: daily) |
| `customUpdateDays` | body | number[] | no | Required when updateFrequency=custom. Array of weekday numbers 0–6 (0=Sunday). |
| `updateTime` | body | number | no | Hour of day 0–23 to run updates (default: 12) |
| `updateTimezone` | body | string | no | IANA timezone name (default: UTC) |
| `serpTop` | body | number (50 \| 100) | no | 50 | 100 — depth of SERP scrape (default: 50) |

**Success response:** HTTP 201

```json
{
  "success": true,
  "project": {
    "_id": "65f1c2a8e1234567890abcde",
    "name": "My Project",
    "domain": "example.com",
    "updateFrequency": "daily",
    "serpTop": 50
  },
  "message": "Project created successfully"
}
```

**Example:**

```bash
curl -X POST \
  -H "Authorization: Bearer sd_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"name":"My Project","domain":"example.com"}' \
  https://serpdino.com/api/projects
```

### `PUT /api/projects`

Update project settings

_id, name, and domain are ALL required (the handler rejects with 400 if any is missing). To change a single field, send the existing values for the others.

**Parameters:**

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `_id` | body | string | yes | Project ID |
| `name` | body | string | yes | Project name (required even if unchanged) |
| `domain` | body | string | yes | Target domain (required even if unchanged) |
| `competitors` | body | string[] | no | Array of competitor domains |
| `folder` | body | string | no | Folder ID, or empty string to remove from folder |
| `icon` | body | string | no | Icon identifier or URL |
| `aliases` | body | string | no | Comma/newline-separated alias domains |
| `shared` | body | boolean | no | Public sharing toggle |
| `updateFrequency` | body | enum (daily \| every3days \| weekly \| biweekly \| custom) | no | daily | every3days | weekly | biweekly | custom |
| `customUpdateDays` | body | number[] | no | Required when updateFrequency=custom. Weekday numbers 0–6. |
| `updateTime` | body | number | no | Hour 0–23 |
| `updateTimezone` | body | string | no | IANA timezone |
| `serpTop` | body | number (50 \| 100) | no | 50 | 100 |

**Success response:** HTTP 200

```json
{
  "success": true,
  "project": {
    "_id": "65f1c2a8e1234567890abcde",
    "name": "Acme",
    "domain": "acme.com",
    "competitors": [
      "competitor.com"
    ]
  },
  "message": "Project updated successfully"
}
```

**Example:**

```bash
curl -X PUT \
  -H "Authorization: Bearer sd_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"_id":"PROJECT_ID","name":"Acme","domain":"acme.com","competitors":["competitor.com"]}' \
  https://serpdino.com/api/projects
```

### `DELETE /api/projects`

Delete a project and all its data

**Parameters:**

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `_id` | body | string | yes | Project ID |

**Success response:** HTTP 200

```json
{
  "success": true,
  "message": "Project deleted successfully",
  "projects": [],
  "folders": []
}
```

**Example:**

```bash
curl -X DELETE \
  -H "Authorization: Bearer sd_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"_id":"PROJECT_ID"}' \
  https://serpdino.com/api/projects
```

## Folders

Organise projects into folders.

### `GET /api/projects/folders`

List folders

**Success response:** HTTP 200

```json
{
  "success": true,
  "folders": [
    {
      "_id": "FOLDER_ID",
      "name": "Clients",
      "position": 0
    }
  ]
}
```

**Example:**

```bash
curl -H "Authorization: Bearer sd_your_key_here" \
  https://serpdino.com/api/projects/folders
```

### `POST /api/projects/folders`

Create folder

Returns HTTP 409 `{ message: "Folder with this name already exists" }` if a folder with that name (case-insensitive) already exists for this user. Requires active subscription.

**Parameters:**

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `name` | body | string | yes | Folder name |

**Success response:** HTTP 201

```json
{
  "success": true,
  "folder": {
    "_id": "FOLDER_ID",
    "name": "My Folder",
    "position": 0
  },
  "message": "Folder created successfully"
}
```

**Example:**

```bash
curl -X POST \
  -H "Authorization: Bearer sd_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"name":"My Folder"}' \
  https://serpdino.com/api/projects/folders
```

### `PUT /api/projects/folders`

Rename folder

Returns HTTP 409 on name conflict. Requires active subscription.

**Parameters:**

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | query | string | yes | Folder ID |
| `name` | body | string | yes | New folder name |

**Success response:** HTTP 200

```json
{
  "success": true,
  "folder": {
    "_id": "FOLDER_ID",
    "name": "New Name"
  },
  "message": "Folder updated successfully"
}
```

**Example:**

```bash
curl -X PUT \
  -H "Authorization: Bearer sd_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"name":"New Name"}' \
  "https://serpdino.com/api/projects/folders?id=FOLDER_ID"
```

### `DELETE /api/projects/folders`

Delete folder

Detaches all projects in the folder (they remain, just unassigned), then deletes the folder. Returns the refreshed folders[] and projects[] lists. Requires active subscription.

**Parameters:**

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | query | string | yes | Folder ID |

**Success response:** HTTP 200

```json
{
  "success": true,
  "message": "Folder \"My Folder\" deleted successfully",
  "folders": [],
  "projects": []
}
```

**Example:**

```bash
curl -X DELETE -H "Authorization: Bearer sd_your_key_here" \
  "https://serpdino.com/api/projects/folders?id=FOLDER_ID"
```

## Keywords

Track keywords inside a project.

### `POST /api/projects/keywords`

Add keywords to track in a project

Max 3500 keywords per project. Keywords appear in rankings after the next scheduled SERP check. Requires active subscription. Duplicates within the request and against existing project keywords are silently deduped. When the limit is exceeded, returns HTTP 400 with extended fields `{ error: "KEYWORDS_LIMIT_EXCEEDED", currentCount, maxAllowed, availableSlots }`.

**Parameters:**

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `projectId` | body | string | yes | Project ID |
| `keywords` | body | string[] | yes | Array of keyword strings (lowercased server-side) |
| `geoCode` | body | string | yes | ISO-2 country code (e.g. US). Required — no default. |
| `langCode` | body | string | yes | ISO-2 language code (e.g. en). Required — no default. |

**Success response:** HTTP 200

```json
{
  "success": true,
  "message": "Added 2 new keywords",
  "addedCount": 2,
  "project": {
    "_id": "PROJECT_ID",
    "keywords": [
      "KW_ID_1",
      "KW_ID_2"
    ]
  }
}
```

**Example:**

```bash
curl -X POST \
  -H "Authorization: Bearer sd_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"projectId":"PROJECT_ID","keywords":["seo tools","rank tracker"],"geoCode":"US","langCode":"en"}' \
  https://serpdino.com/api/projects/keywords
```

### `DELETE /api/projects/keywords`

Remove tracked keywords

**Parameters:**

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `projectId` | body | string | yes | Project ID |
| `keywordIds` | body | string[] | yes | Array of keyword IDs to remove |

**Success response:** HTTP 200

```json
{
  "success": true,
  "removedCount": 2,
  "project": {
    "_id": "PROJECT_ID"
  }
}
```

**Example:**

```bash
curl -X DELETE \
  -H "Authorization: Bearer sd_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"projectId":"PROJECT_ID","keywordIds":["KW_ID_1","KW_ID_2"]}' \
  https://serpdino.com/api/projects/keywords
```

### `POST /api/scrape/new-keywords`

Trigger a fresh SERP check for keywords

Async — returns immediately (HTTP 200, status: "processing") while scraping happens in the background. Costs 1 balance credit per keyword (×2 for serpTop=100); rejects with HTTP 400 "Insufficient balance" if `keywordIds.length > virtualBalance`. Pass all project keyword IDs to refresh everything. Requires active subscription. All `keywordIds` must belong to the given project.

**Parameters:**

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `projectId` | body | string | yes | Project ID |
| `keywordIds` | body | string[] | yes | Keyword IDs to refresh (must belong to projectId) |

**Success response:** HTTP 200

```json
{
  "success": true,
  "message": "Accepted 10 keywords for processing. Position updates started in background mode.",
  "status": "processing",
  "summary": {
    "total": 10,
    "accepted": 10,
    "errors": 0
  }
}
```

**Example:**

```bash
curl -X POST \
  -H "Authorization: Bearer sd_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"projectId":"PROJECT_ID","keywordIds":["KW_ID_1"]}' \
  https://serpdino.com/api/scrape/new-keywords
```

## Ranking Data

Read keyword positions, SERP snapshots, and volume data.

### `GET /api/projects/keyword-updates`

Get keyword position history

Public when project is shared. Response.data is keyed by keyword ID; each entry contains the full Keywords document plus an `updates` array of dated check results. When startDate/endDate are omitted, defaults to last 30 days.

**Parameters:**

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `projectId` | query | string | yes | Project ID |
| `startDate` | query | string | no | YYYY-MM-DD (default: 30 days ago) |
| `endDate` | query | string | no | YYYY-MM-DD (default: today) |
| `aggregation` | query | enum (daily \| weekly \| monthly) | no | daily | weekly | monthly (default: daily) |
| `search` | query | string | no | Filter keywords by substring (case-insensitive) |
| `geoCode` | query | string | no | Filter by country code (uppercased) |
| `langCode` | query | string | no | Filter by language code (lowercased) |
| `sortBy` | query | enum (keyword \| position \| volume) | no | keyword | position | volume |
| `sortOrder` | query | enum (asc \| desc) | no | asc | desc (default: desc) |

**Success response:** HTTP 200

```json
{
  "success": true,
  "data": {
    "65f1c2a8e1234567890fffff": {
      "keyword": {
        "_id": "65f1c2a8e1234567890fffff",
        "value": "seo tools",
        "geoCode": "US",
        "langCode": "en",
        "avgMonthlySearches": 8100
      },
      "updates": [
        {
          "_id": "UPD_ID",
          "date": "2025-01-16T12:00:00.000Z",
          "status": "success",
          "position": {
            "position": 9,
            "url": "https://example.com/seo-tools",
            "title": "...",
            "domain": "example.com"
          },
          "aiSerpId": null
        },
        {
          "_id": "UPD_ID2",
          "date": "2025-01-15T12:00:00.000Z",
          "status": "success",
          "position": {
            "position": 12,
            "url": "https://example.com/seo-tools",
            "title": "...",
            "domain": "example.com"
          },
          "aiSerpId": null
        }
      ]
    }
  }
}
```

**Example:**

```bash
curl -H "Authorization: Bearer sd_your_key_here" \
  "https://serpdino.com/api/projects/keyword-updates?projectId=PROJECT_ID&startDate=2025-01-01&endDate=2025-01-31"
```

### `GET /api/projects/position-history`

Get full SERP snapshot for a keyword check

Returns top 30 results plus the project domain itself if it ranks beyond 30. Each result includes movement vs the previous successful check (`up`/`down`/`same`/`new`). Public when project is shared.

**Parameters:**

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `keywordUpdateId` | query | string | yes | Keyword update ID (from keyword-updates response) |

**Success response:** HTTP 200

```json
{
  "success": true,
  "data": {
    "keywordId": "65f1c2a8e1234567890fffff",
    "keywordValue": "seo tools",
    "date": "2025-01-16T12:00:00.000Z",
    "resultList": [
      {
        "position": 1,
        "title": "...",
        "domain": "example.com",
        "url": "https://example.com",
        "previousPosition": 2,
        "movement": {
          "type": "up",
          "value": 1
        }
      }
    ],
    "droppedDomains": [
      {
        "domain": "old-competitor.com",
        "previousPosition": 15,
        "movement": {
          "type": "gone",
          "value": null
        }
      }
    ],
    "hasPreviousData": true,
    "aiOverviewResults": [
      {
        "position": 1,
        "title": "...",
        "domain": "wikipedia.org",
        "url": "https://...",
        "isOurDomain": false
      }
    ],
    "aiContainsOurDomain": false
  }
}
```

**Example:**

```bash
curl -H "Authorization: Bearer sd_your_key_here" \
  "https://serpdino.com/api/projects/position-history?keywordUpdateId=UPDATE_ID"
```

### `GET /api/projects/keyword-volumes`

Get search volume, CPC, and competition data

Two modes with different response shapes. Bulk (no keywordId) uses compact field names to minimise payload size. Single mode (with keywordId) returns the full per-keyword detail. CPC values are pre-converted to the project currency. Public when project is shared.

**Parameters:**

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `projectId` | query | string | yes | Project ID |
| `keywordId` | query | string | no | Single keyword ID — when present, returns full volume history for one keyword instead of the bulk map |

**Success response:** HTTP 200

```json
{
  "success": true,
  "data": {
    "65f1c2a8e1234567890fffff": {
      "v": "seo tools",
      "g": "US",
      "l": "en",
      "s": "google",
      "lv": 8100,
      "tr": [
        6600,
        7200,
        7800,
        8000,
        8100,
        8100,
        7900,
        8000,
        8100,
        8200,
        8000,
        8100
      ],
      "am": 8100,
      "ci": 72,
      "cl": 3.1,
      "ch": 5.4
    }
  }
}
```

**Example:**

```bash
curl -H "Authorization: Bearer sd_your_key_here" \
  "https://serpdino.com/api/projects/keyword-volumes?projectId=PROJECT_ID"
```

## Keyword Research

Discover new keywords and run live SERP / traffic checks.

### `POST /api/tools/keyword-research`

Research keyword ideas with volumes, CPC, competition, and trends

Requires active subscription. Rate limited for API-key callers: 10 req / min, 100 req / hour per account — HTTP 429 with `retryAfter` (seconds) when exceeded. All expected failures (bad seed, unsupported geo/lang, upstream timeout, scraper error) are returned as HTTP 200 with `{ success: false, message, error? }` — always check `success`. 60s upstream timeout. `pageSize` is clamped 10–500, `trendsForTopN` is clamped 0–200.

**Parameters:**

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `seed` | body | string | yes | Seed keyword, URL, or domain (mode-dependent) |
| `mode` | body | enum (keyword \| url \| domain) | no | keyword | url | domain (default: keyword) |
| `geo` | body | string | no | ISO-2 country code (default: US) |
| `lang` | body | string | no | ISO-2 language code (default: en) |
| `pageSize` | body | number | no | 10–500 (default: 100) |
| `trendsForTopN` | body | number | no | 0–200 (default: 60) — number of top ideas to enrich with monthly trend data |
| `enrichWithLlm` | body | boolean | no | Apply LLM intent/cluster tagging (default: true) |

**Success response:** HTTP 200

```json
{
  "success": true,
  "ideas": [
    {
      "keyword": "best seo tools",
      "avgMonthlySearches": 8100,
      "competition": "HIGH",
      "cpc": 4.21,
      "intent": "commercial",
      "cluster": "tools"
    }
  ],
  "meta": {
    "totalResults": 100,
    "geo": "US",
    "lang": "en"
  }
}
```

**Example:**

```bash
curl -X POST \
  -H "Authorization: Bearer sd_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"seed":"best seo tools","geo":"US","lang":"en","pageSize":50}' \
  https://serpdino.com/api/tools/keyword-research
```

### `POST /api/tools/serp-check`

Live SERP check — returns top results and search volume for a keyword

Rate limited: 5 req / 60s. When called with an API key (`Authorization: Bearer sd_...`), the limit is **per API user**. When called from the web (Turnstile token), the limit is per client IP. 429 response body includes `retryAfter` (seconds), `limit`, `window`. Returns HTTP 502 if both upstream SERP and volume calls fail.

**Parameters:**

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `keyword` | body | string | yes | Search query |
| `geo` | body | string | yes | ISO-2 country code (e.g. US) |
| `lang` | body | string | yes | ISO-2 language code (e.g. en) |

**Success response:** HTTP 200

```json
{
  "success": true,
  "data": {
    "serp": [
      {
        "position": 1,
        "url": "https://...",
        "title": "...",
        "snippet": "..."
      }
    ],
    "volume": {
      "value": 1300,
      "cpc": 2.5,
      "competition": "MEDIUM"
    }
  },
  "remaining": 4
}
```

**Example:**

```bash
curl -X POST \
  -H "Authorization: Bearer sd_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"keyword":"rank tracker","geo":"US","lang":"en"}' \
  https://serpdino.com/api/tools/serp-check
```

### `POST /api/tools/traffic-check`

Domain traffic check — returns SimilarWeb stats and PageSpeed data

Rate limited: 5 req / 60s — per API user when called with an API key, per IP when called from the web. Triggers a live scraper fetch on DB cache miss for either SimilarWeb or PageSpeed (slow path), or returns cached data immediately. `data` may be null if SimilarWeb has no info on the domain. Domain is validated and normalised server-side (strips protocol, `www.`, path).

**Parameters:**

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `domain` | body | string | yes | Target domain (e.g. example.com or https://www.example.com/path — normalised server-side) |

**Success response:** HTTP 200

```json
{
  "success": true,
  "domain": "example.com",
  "data": {
    "stats": {
      "domain": "example.com",
      "totalVisits": 1234567,
      "engagementMetrics": {
        "bounceRate": 0.42,
        "avgVisitDuration": 134
      },
      "fetchedAt": "2025-01-16T08:00:00.000Z"
    },
    "monthlyVisits": [
      {
        "domain": "example.com",
        "month": "2025-01-01",
        "visits": 1234567
      }
    ]
  },
  "pagespeed": {
    "domain": "example.com",
    "performanceScore": 86,
    "cruxScore": 78,
    "largestContentfulPaint": 1.8,
    "cumulativeLayoutShift": 0.05,
    "fetchedAt": "2025-01-16T08:00:00.000Z"
  },
  "remaining": 4
}
```

**Example:**

```bash
curl -X POST \
  -H "Authorization: Bearer sd_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"domain":"example.com"}' \
  https://serpdino.com/api/tools/traffic-check
```

### `GET /api/projects/keyword-suggestions`

AI-generated keyword suggestions for a project

Polling endpoint — `ready: false` (with no other fields) means the LLM pipeline is still running. Retry every few seconds for ~2 minutes max. Generation is auto-triggered at project creation, so this is just a reader over the cached suggestions doc. Requires active subscription. Each locale ships up to 30 phrases, sorted by lastVolume desc.

**Parameters:**

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `projectId` | query | string | yes | Project ID |

**Success response:** HTTP 200

```json
{
  "success": true,
  "ready": true,
  "domain": "example.com",
  "primary": {
    "lang": "en",
    "geo": "US"
  },
  "locales": [
    {
      "key": "en-US",
      "lang": "en",
      "region": "US",
      "geo": "US",
      "lastUpdatedAt": "2025-01-16T08:00:00.000Z",
      "keywords": [
        {
          "phrase": "best seo tools",
          "lastVolume": 8100,
          "volume": [
            {
              "year": 2024,
              "months": [
                {
                  "month": 12,
                  "value": 8100
                }
              ]
            }
          ]
        }
      ]
    }
  ],
  "pages": [],
  "meta": {
    "seedUsed": "domain"
  },
  "runCount": 1,
  "lastRunAt": "2025-01-16T08:00:00.000Z",
  "lastError": null
}
```

**Example:**

```bash
curl -H "Authorization: Bearer sd_your_key_here" \
  "https://serpdino.com/api/projects/keyword-suggestions?projectId=PROJECT_ID"
```

### `POST /api/projects/keyword-ideas`

Keyword ideas based on a project's domain

Soft-fail endpoint: always returns HTTP 200 with `success: true` when authorised. On upstream errors returns `{ success: true, ideas: [], error: "upstream_error" | "service_unavailable" }` — an empty `ideas` array does NOT mean failure, it means "no data available right now". 30s timeout on the upstream call. Requires active subscription. Rate limited for API-key callers: 10 req / min, 100 req / hour per account — HTTP 429 with `retryAfter` when exceeded.

**Parameters:**

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `projectId` | body | string | yes | Project ID |
| `geo` | body | string | no | Country code (default: US, uppercased) |
| `lang` | body | string | no | Language code (default: en, lowercased) |

**Success response:** HTTP 200

```json
{
  "success": true,
  "ideas": [
    {
      "keyword": "seo tools comparison",
      "avgMonthlySearches": 1000,
      "competition": "MEDIUM"
    }
  ]
}
```

**Example:**

```bash
curl -X POST \
  -H "Authorization: Bearer sd_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"projectId":"PROJECT_ID"}' \
  https://serpdino.com/api/projects/keyword-ideas
```

## Competitors

Compare competitor rankings and traffic.

### `GET /api/projects/competitor-positions`

Get a competitor's ranking positions across all tracked keywords

Searches the project's tracked keywords' SERP history for results matching the competitor domain. `position: 0` means the competitor didn't appear in the top 30 results for that check. Public when project is shared. Deduped to one entry per calendar day per keyword.

**Parameters:**

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `projectId` | query | string | yes | Project ID |
| `competitorDomain` | query | string | yes | Competitor domain (e.g. competitor.com — normalised server-side) |
| `startDate` | query | string | no | YYYY-MM-DD |
| `endDate` | query | string | no | YYYY-MM-DD |

**Success response:** HTTP 200

```json
{
  "success": true,
  "keywordHistory": {
    "65f1c2a8e1234567890fffff": {
      "keyword": {
        "_id": "65f1c2a8e1234567890fffff",
        "value": "seo tools",
        "geoCode": "US",
        "langCode": "en"
      },
      "updates": [
        {
          "_id": "UPD_ID",
          "date": "2025-01-15T12:00:00.000Z",
          "status": "success",
          "position": {
            "position": 4,
            "domain": "competitor.com",
            "title": "-",
            "url": "-"
          },
          "aiSerpId": null
        }
      ]
    }
  }
}
```

**Example:**

```bash
curl -H "Authorization: Bearer sd_your_key_here" \
  "https://serpdino.com/api/projects/competitor-positions?projectId=PROJECT_ID&competitorDomain=competitor.com"
```

### `GET /api/projects/competitors-filtered`

Compare traffic and performance across a domain and its competitors

PUBLIC endpoint — no API key required. Rate limited: 60 req / min (600 / hour) per IP. Reads from the SimilarWeb / PageSpeed cache only (no live fetching). Auto-filters competitors to a balanced sample of 6 (3 above, 3 below main domain traffic) when more than 6 are supplied. `data` is keyed by domain.

**Parameters:**

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `domain` | query | string | yes | Main domain |
| `competitors` | query | string | yes | Comma-separated competitor domains, or repeated query param. Max 50 accepted (HTTP 400 above); auto-filtered to 6 in the response. |

**Success response:** HTTP 200

```json
{
  "success": true,
  "data": {
    "example.com": {
      "stats": {
        "domain": "example.com",
        "totalVisits": 1234567,
        "fetchedAt": "2025-01-16T08:00:00.000Z"
      },
      "monthlyVisits": [
        {
          "month": "2025-01-01",
          "visits": 1234567
        }
      ],
      "pageSpeed": {
        "cruxScore": 78
      }
    }
  },
  "filtered": [
    "competitor.com"
  ],
  "mainDomainVisits": 1234567,
  "totalCompetitors": 1
}
```

**Example:**

```bash
curl -H "Authorization: Bearer sd_your_key_here" \
  "https://serpdino.com/api/projects/competitors-filtered?domain=example.com&competitors=a.com,b.com"
```

## Performance

Page-level rankings and Core Web Vitals.

### `GET /api/projects/pages`

Page-level ranking data: which URLs rank, average position, trend sparklines

Aggregated by the projectPagesPoller. Each page includes 14-point trend data for the last 90 days, bucketed weekly (or daily if there is not enough data for a week-bucket). Public when project is shared. Sorted worst-first by avgPosition.

**Parameters:**

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `projectId` | query | string | yes | Project ID |

**Success response:** HTTP 200

```json
{
  "success": true,
  "data": [
    {
      "url": "https://example.com/blog/post",
      "path": "/blog/post",
      "keywordCount": 12,
      "avgPosition": 8.4,
      "bestPosition": 3,
      "keywords": [
        {
          "keywordId": "KW_ID",
          "value": "seo tools",
          "position": 5
        }
      ],
      "avgPositionTrend": [
        {
          "date": "2025-01-06T00:00:00.000Z",
          "avgPosition": 9.2,
          "keywordCount": 12
        }
      ],
      "avgPositionTrendGranularity": "week",
      "weeklyAvgPositions": [
        {
          "weekStart": "2025-01-06T00:00:00.000Z",
          "avgPosition": 9.2,
          "keywordCount": 12
        }
      ]
    }
  ],
  "lastPagesUpdate": "2025-01-16T08:00:00.000Z"
}
```

**Example:**

```bash
curl -H "Authorization: Bearer sd_your_key_here" \
  "https://serpdino.com/api/projects/pages?projectId=PROJECT_ID"
```

### `GET /api/projects/pagespeed`

PageSpeed Insights (Core Web Vitals) for a domain

PUBLIC endpoint — no API key required. Rate limited: 60 req / min (600 / hour) per IP. Reads from DB cache only (never triggers a live PageSpeed run). Returns `data: null` if domain not in cache. Domain is normalised (strips `www.`, lowercased).

**Parameters:**

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `domain` | query | string | yes | Target domain |

**Success response:** HTTP 200

```json
{
  "success": true,
  "data": {
    "domain": "example.com",
    "performanceScore": 86,
    "accessibilityScore": 92,
    "bestPracticesScore": 90,
    "seoScore": 95,
    "cruxScore": 78,
    "largestContentfulPaint": 1.8,
    "firstContentfulPaint": 1,
    "cumulativeLayoutShift": 0.05,
    "totalBlockingTime": 120,
    "cruxFieldData": {
      "LCP": {
        "p75": 1900
      },
      "CLS": {
        "p75": 0.05
      },
      "INP": {
        "p75": 180
      }
    },
    "fetchedAt": "2025-01-16T08:00:00.000Z"
  }
}
```

**Example:**

```bash
curl -H "Authorization: Bearer sd_your_key_here" \
  "https://serpdino.com/api/projects/pagespeed?domain=example.com"
```

### `GET /api/projects/pages-pagespeed`

Per-page Lighthouse lab metrics for all tracked pages in a project

Public when project is shared. `pages` is keyed by URL. `baseline` is the home-page record when available, falling back to the domain-level snapshot (with `source: "domain"`) so the UI can still compute deltas. Returns `baseline: null` if neither exists.

**Parameters:**

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `projectId` | query | string | yes | Project ID |

**Success response:** HTTP 200

```json
{
  "success": true,
  "baseline": {
    "url": "https://example.com/",
    "path": "/",
    "domain": "example.com",
    "performanceScore": 86,
    "largestContentfulPaint": 1.8,
    "firstContentfulPaint": 1,
    "cumulativeLayoutShift": 0.04,
    "totalBlockingTime": 120,
    "source": "page"
  },
  "pages": {
    "https://example.com/blog/post": {
      "url": "https://example.com/blog/post",
      "path": "/blog/post",
      "performanceScore": 80,
      "largestContentfulPaint": 2.1,
      "source": "page"
    }
  }
}
```

**Example:**

```bash
curl -H "Authorization: Bearer sd_your_key_here" \
  "https://serpdino.com/api/projects/pages-pagespeed?projectId=PROJECT_ID"
```

### `GET /api/projects/crux-history`

Chrome UX Report (CrUX) real-user performance history for a domain

PUBLIC endpoint — no API key required. Rate limited: 60 req / min (600 / hour) per IP. Reads from DB cache only. `data` is the origin-level series (CrUX records with no specific URL); `pages` is per-page records keyed by URL with parsed `path`.

**Parameters:**

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `domain` | query | string | yes | Target domain |

**Success response:** HTTP 200

```json
{
  "success": true,
  "data": [
    {
      "domain": "example.com",
      "date": "2025-01-01",
      "lcp": {
        "p75": 1900
      },
      "cls": {
        "p75": 0.05
      }
    }
  ],
  "pages": [
    {
      "url": "https://example.com/blog/",
      "path": "/blog/",
      "data": [
        {
          "date": "2025-01-01",
          "lcp": {
            "p75": 2100
          }
        }
      ]
    }
  ]
}
```

**Example:**

```bash
curl -H "Authorization: Bearer sd_your_key_here" \
  "https://serpdino.com/api/projects/crux-history?domain=example.com"
```

### `GET /api/projects/similarweb`

SimilarWeb traffic stats and monthly visit history for a domain

PUBLIC endpoint — no API key required. Rate limited: 60 req / min (600 / hour) per IP. Reads from DB cache only. `exists: false` and `data: null` when the domain has never been scraped. `monthlyVisits` capped at 12 months, oldest first.

**Parameters:**

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `domain` | query | string | yes | Target domain |

**Success response:** HTTP 200

```json
{
  "success": true,
  "exists": true,
  "data": {
    "stats": {
      "domain": "example.com",
      "totalVisits": 1234567,
      "fetchedAt": "2025-01-16T08:00:00.000Z"
    },
    "monthlyVisits": [
      {
        "domain": "example.com",
        "month": "2024-02-01",
        "visits": 1100000
      },
      {
        "domain": "example.com",
        "month": "2025-01-01",
        "visits": 1234567
      }
    ]
  }
}
```

**Example:**

```bash
curl -H "Authorization: Bearer sd_your_key_here" \
  "https://serpdino.com/api/projects/similarweb?domain=example.com"
```

## Notes

Timeline annotations for a project.

### `GET /api/projects/notes`

List timeline notes for a project

**Parameters:**

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `projectId` | query | string | yes | Project ID |

**Success response:** HTTP 200

```json
{
  "success": true,
  "data": [
    {
      "_id": "NOTE_ID",
      "date": "2025-01-15",
      "text": "Google algorithm update",
      "color": "warning"
    }
  ]
}
```

**Example:**

```bash
curl -H "Authorization: Bearer sd_your_key_here" \
  "https://serpdino.com/api/projects/notes?projectId=PROJECT_ID"
```

### `POST /api/projects/notes`

Add or update a note on a project timeline

Upsert by `(projectId, date)`: if a note already exists for this date, it is updated in place and the response is HTTP 200 with `message: "Note updated"`. Otherwise a new note is created and the response is HTTP 201 with `message: "Note saved"`. Requires active subscription.

**Parameters:**

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `projectId` | body | string | yes | Project ID |
| `date` | body | string | yes | YYYY-MM-DD (interpreted as 00:00:00 UTC) |
| `text` | body | string | yes | Note content |
| `color` | body | enum (info \| warning \| success \| danger) | no | info | warning | success | danger (default: info, only set on new notes) |

**Success response:** HTTP 201

```json
{
  "success": true,
  "message": "Note saved",
  "data": {
    "_id": "NOTE_ID",
    "projectId": "PROJECT_ID",
    "date": "2025-01-15T00:00:00.000Z",
    "text": "Google algorithm update",
    "color": "warning"
  }
}
```

**Example:**

```bash
curl -X POST \
  -H "Authorization: Bearer sd_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"projectId":"PROJECT_ID","date":"2025-01-15","text":"Google algorithm update","color":"warning"}' \
  https://serpdino.com/api/projects/notes
```

### `DELETE /api/projects/notes`

Delete a note

Returns the remaining notes for the project in `data` after deletion. Requires active subscription.

**Parameters:**

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `noteId` | body | string | yes | Note ID |

**Success response:** HTTP 200

```json
{
  "success": true,
  "message": "Note deleted",
  "data": [
    {
      "_id": "OTHER_NOTE_ID",
      "date": "2025-01-10T00:00:00.000Z",
      "text": "...",
      "color": "info"
    }
  ]
}
```

**Example:**

```bash
curl -X DELETE \
  -H "Authorization: Bearer sd_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"noteId":"NOTE_ID"}' \
  https://serpdino.com/api/projects/notes
```

## Account

Check usage and limits.

### `GET /api/user/capacity`

Check account usage and limits

**Success response:** HTTP 200

```json
{
  "total": 1000,
  "booked": 320,
  "available": 680,
  "projects": 4,
  "keywords": 320,
  "isTrial": false
}
```

**Example:**

```bash
curl -H "Authorization: Bearer sd_your_key_here" \
  https://serpdino.com/api/user/capacity
```

## Export

Export project data as Markdown or CSV.

### `GET /api/projects/export-agent`

Generate a comprehensive Markdown report for a project

Returns plain Markdown text (Content-Type: text/markdown), NOT JSON. Includes rankings, traffic, competitors, and performance data in a single document — designed for feeding to LLMs.

**Parameters:**

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `projectId` | query | string | yes | Project ID |

**Success response:** HTTP 200 (`text/markdown`)

```
# Acme Corp — SEO Report

Domain: acme.com

## Rankings
...
```

**Example:**

```bash
curl -H "Authorization: Bearer sd_your_key_here" \
  "https://serpdino.com/api/projects/export-agent?projectId=PROJECT_ID"
```

### `GET /api/projects/export`

CSV export of ranking data

Returns CSV with UTF-8 BOM and semicolon (`;`) separator — opens correctly in Excel without conversion. `Content-Disposition` header forces download with a generated filename. `full` format: one row per keyword with a date column per checked day. `summary` format: one row per keyword with aggregated stats (current/best/worst/avg position, change). Public when project is shared.

**Parameters:**

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `projectId` | query | string | yes | Project ID |
| `format` | query | enum (full \| summary) | no | full | summary (default: full) |
| `startDate` | query | string | no | YYYY-MM-DD |
| `endDate` | query | string | no | YYYY-MM-DD |

**Success response:** HTTP 200 (`text/csv; charset=utf-8`)

```
Keyword;SERP;Volume;URL;Change;2025-01-16;2025-01-15
seo tools;en-US;8100;https://example.com/seo-tools;-3;9;12

```

**Example:**

```bash
curl -H "Authorization: Bearer sd_your_key_here" \
  "https://serpdino.com/api/projects/export?projectId=PROJECT_ID&format=full" -o report.csv
```

## API Keys

Create and revoke API keys programmatically.

### `GET /api/user/api-keys`

List your API keys

Returns metadata only — secrets are never returned after creation. Each entry includes _id, name, keyPrefix (masked, first 4 chars only), lastUsedAt, createdAt.

**Success response:** HTTP 200

```json
{
  "success": true,
  "apiKeys": [
    {
      "_id": "KEY_ID",
      "name": "My Integration",
      "keyPrefix": "sd_a••••",
      "lastUsedAt": "2025-01-16T10:00:00.000Z",
      "createdAt": "2025-01-10T08:00:00.000Z"
    }
  ]
}
```

**Example:**

```bash
curl -H "Authorization: Bearer sd_your_key_here" \
  https://serpdino.com/api/user/api-keys
```

### `POST /api/user/api-keys`

Create a new API key

`key` is the full secret — shown only once, store it immediately. `apiKey` is metadata. Max 5 active keys per user. Names limited to 100 chars.

**Parameters:**

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `name` | body | string | yes | Key name (max 100 chars) |

**Success response:** HTTP 201

```json
{
  "success": true,
  "key": "sd_abcd1234567890abcdef1234567890abcdef1234",
  "apiKey": {
    "_id": "KEY_ID",
    "name": "My Integration",
    "keyPrefix": "sd_a••••",
    "createdAt": "2025-01-16T10:00:00.000Z"
  }
}
```

**Example:**

```bash
curl -X POST \
  -H "Authorization: Bearer sd_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"name":"My Integration"}' \
  https://serpdino.com/api/user/api-keys
```

### `DELETE /api/user/api-keys`

Revoke an API key

Soft-revokes by setting `revokedAt`. Accepts `id` from either body or query string. Returns 404 if the key does not exist or already revoked.

**Parameters:**

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | body | string | no | API key ID (one of body or query is required) |
| `id` | query | string | no | API key ID (one of body or query is required) |

**Success response:** HTTP 200

```json
{
  "success": true
}
```

**Example:**

```bash
curl -X DELETE \
  -H "Authorization: Bearer sd_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"id":"KEY_ID"}' \
  https://serpdino.com/api/user/api-keys
```