# SerpDino REST API

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

Authentication: send `Authorization: Bearer sd_your_key_here` on every request. Create keys in Dashboard → Settings → API Keys.

## Key resources

- [Human-readable API docs](https://serpdino.com/api-docs)
- [OpenAPI 3.1 spec (JSON)](https://serpdino.com/api/openapi.json) — import into Postman, generate clients, feed to LLMs
- [Full API reference for LLMs](https://serpdino.com/api/llms-full.txt) — machine-readable Markdown spec
- Remote MCP endpoint: `https://serpdino.com/api/mcp` — works with Claude, ChatGPT, Cursor, and any MCP client

## Endpoints by category

### Projects
Create and manage SEO tracking projects.

- `GET /api/projects` — List all projects
- `GET /api/projects/:id` — Get project details
- `POST /api/projects` — Create a new project
- `PUT /api/projects` — Update project settings
- `DELETE /api/projects` — Delete a project and all its data

### Folders
Organise projects into folders.

- `GET /api/projects/folders` — List folders
- `POST /api/projects/folders` — Create folder
- `PUT /api/projects/folders` — Rename folder
- `DELETE /api/projects/folders` — Delete folder

### Keywords
Track keywords inside a project.

- `POST /api/projects/keywords` — Add keywords to track in a project
- `DELETE /api/projects/keywords` — Remove tracked keywords
- `POST /api/scrape/new-keywords` — Trigger a fresh SERP check for keywords

### Ranking Data
Read keyword positions, SERP snapshots, and volume data.

- `GET /api/projects/keyword-updates` — Get keyword position history
- `GET /api/projects/position-history` — Get full SERP snapshot for a keyword check
- `GET /api/projects/keyword-volumes` — Get search volume, CPC, and competition data

### 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
- `POST /api/tools/serp-check` — Live SERP check — returns top results and search volume for a keyword
- `POST /api/tools/traffic-check` — Domain traffic check — returns SimilarWeb stats and PageSpeed data
- `GET /api/projects/keyword-suggestions` — AI-generated keyword suggestions for a project
- `POST /api/projects/keyword-ideas` — Keyword ideas based on a project's domain

### Competitors
Compare competitor rankings and traffic.

- `GET /api/projects/competitor-positions` — Get a competitor's ranking positions across all tracked keywords
- `GET /api/projects/competitors-filtered` — Compare traffic and performance across a domain and its competitors

### Performance
Page-level rankings and Core Web Vitals.

- `GET /api/projects/pages` — Page-level ranking data: which URLs rank, average position, trend sparklines
- `GET /api/projects/pagespeed` — PageSpeed Insights (Core Web Vitals) for a domain
- `GET /api/projects/pages-pagespeed` — Per-page Lighthouse lab metrics for all tracked pages in a project
- `GET /api/projects/crux-history` — Chrome UX Report (CrUX) real-user performance history for a domain
- `GET /api/projects/similarweb` — SimilarWeb traffic stats and monthly visit history for a domain

### Notes
Timeline annotations for a project.

- `GET /api/projects/notes` — List timeline notes for a project
- `POST /api/projects/notes` — Add or update a note on a project timeline
- `DELETE /api/projects/notes` — Delete a note

### Account
Check usage and limits.

- `GET /api/user/capacity` — Check account usage and limits

### Export
Export project data as Markdown or CSV.

- `GET /api/projects/export-agent` — Generate a comprehensive Markdown report for a project
- `GET /api/projects/export` — CSV export of ranking data

### API Keys
Create and revoke API keys programmatically.

- `GET /api/user/api-keys` — List your API keys
- `POST /api/user/api-keys` — Create a new API key
- `DELETE /api/user/api-keys` — Revoke an API key

## Notes
- Base URL: `https://serpdino.com`
- Errors use the `message` field (not `error`). Always check `success` in the response body in addition to HTTP status.
- Some endpoints (`/api/tools/keyword-research`, `/api/projects/keyword-ideas`) return 200 with `{ success: false, message }` on failure.
- `/api/tools/serp-check` and `/api/tools/traffic-check` are rate-limited to 5 requests / 60s per API key; `/api/tools/keyword-research` and `/api/projects/keyword-ideas` to 10 requests / min (100 / hour) per account.
- Public endpoints (`/api/projects/competitors-filtered`, `pagespeed`, `crux-history`, `similarweb`) are rate-limited to 60 requests / min (600 / hour) per IP; `competitors-filtered` accepts at most 50 competitor domains per request.