API
API reference
Version 1, JSON over HTTPS. Every call needs a key; this list matches the OpenAPI document.
Status: live
Authentication
Send the key as the header Authorization: Bearer sd_… (or X-Api-Key). You create keys in your account under “Reports”.
Base address: https://app.serpdash.dev/api/v1 · openapi.json
Calls
| Method | Path | What it does | Plan |
|---|---|---|---|
GET |
/api/v1/usage |
Limits and use: units and answers of this month, the plan's units and rows per answer, when the month starts over. Costs no unit. | from Pro |
GET |
/api/v1/sites |
The sites of your organisation. | from Pro |
GET |
/api/v1/sites/{domain}/keywords |
The keywords a site follows. | from Pro |
GET |
/api/v1/sites/{domain}/keywords.csv |
The same as CSV. | from Pro |
GET |
/api/v1/sites/{domain}/ranks |
Current ranks of a proven site: SERP place, change in 7 days, Search Console figures of 28 days, each with its read date. | from Pro |
GET |
/api/v1/sites/{domain}/ranks.csv |
The same as CSV, with source and day in every row. | from Pro |
GET |
/api/v1/sites/{domain}/audit |
The latest site audit of a proven site: counts and the most important findings. | from Pro |
GET |
/api/v1/sites/{domain}/report |
The report figures of the last complete week or month.?periodweekly (default) or monthly |
from Pro |
GET |
/api/v1/sites/{domain}/report.csv |
The same report as CSV.?periodweekly (default) or monthly |
from Pro |
GET |
/api/v1/sites/{domain}/ai-visibility |
AI visibility in one object: prompts followed, how many AI answers name the site, checks of the month. No answer text is stored. | from Pro |
GET |
/api/v1/sites/{domain}/ai-visibility/prompts |
The prompts with the latest check per engine. | from Pro |
GET |
/api/v1/sites/{domain}/ai-visibility/prompts.csv |
The same as CSV. | from Pro |
GET |
/api/v1/sites/{domain}/ai-visibility/gaps |
Pages cited in AI answers where competitors are named and the site is not. | from Pro |
GET |
/api/v1/sites/{domain}/links |
Links to the site: the first-party count (Bing Webmaster) and the kept provider profile, each with its source and day. Starts no paid read. | from Pro |
GET |
/api/v1/sites/{domain}/links/referring-domains |
The referring domains of the kept provider profile. | from Pro |
GET |
/api/v1/sites/{domain}/links/referring-domains.csv |
The same as CSV. | from Pro |
GET |
/api/v1/sites/{domain}/links/opportunities |
Broken backlinks to win back and domains that link to competitors but not to the site: a list for a person, nothing is sent. | from Pro |
GET |
/api/v1/sites/{domain}/competitors |
The competitors you list and the suggestions made from shared results. | from Pro |
GET |
/api/v1/sites/{domain}/competitors/places |
The competitors' places for your keywords over the last days, from the rank reads made anyway.?dayswindow in days: 7, 28 (default) or 90 |
from Pro |
GET |
/api/v1/sites/{domain}/insights |
Search Console totals of the window with the day it was read.?dayswindow in days: 7, 28 (default) or 90 |
from Pro |
GET |
/api/v1/sites/{domain}/insights/queries |
The site's searches from Search Console, most clicks first.?dayswindow in days: 7, 28 (default) or 90 |
from Pro |
GET |
/api/v1/sites/{domain}/insights/queries.csv |
The same as CSV.?dayswindow in days: 7, 28 (default) or 90 |
from Pro |
GET |
/api/v1/sites/{domain}/easy-wins |
Searches just off page one with their difficulty when known.?maxDifficultyonly searches up to this difficulty |
from Pro |
GET |
/api/v1/sites/{domain}/export.md |
Everything of a site as one Markdown document to give a model ("for AI"); every section names source and day.?partsranks, audit, search, ai, links, comma separated (default all)?langde or en (default en) |
from Pro |
GET |
/api/v1/examples/{name} |
A fixed example answer to try the shapes without a plan or key (sites, ranks, audit, report, ai-visibility, links, usage). Marked as an example in the body and in X-SerpDash-Example; never real data. | from Pro |
POST |
/api/v1/sites/{domain}/keywords |
Follow a keyword; body {"keyword": "…"}. The plan's keyword limit applies. | Team, key that allows writes |
DELETE |
/api/v1/sites/{domain}/keywords |
Stop following a keyword.?keywordthe keyword (required) |
Team, key that allows writes |
{domain} is the domain of a proven website of your organisation, for example example.com.
Error codes
| Code | Meaning |
|---|---|
401 | The key is missing, malformed or revoked. |
403 | The plan has no API (Free, Solo) or the key may not write. |
404 | No such site, or it is not proven yet. |
409 | The plan's keyword limit is reached. |
429 | The limit per key and minute is reached (Pro 60, Team 300), or the month's units are used up (error units-exhausted, starts over with the month); the Retry-After header says when to go on. |
Example
curl -H "Authorization: Bearer sd_…" \
"https://app.serpdash.dev/api/v1/sites/example.com/ranks"
curl -X POST -H "Authorization: Bearer sd_…" \
-H "Content-Type: application/json" \
-d '{"keyword": "kaffeemaschine test"}' \
"https://app.serpdash.dev/api/v1/sites/example.com/keywords"
Every number in the answer carries its read date. A website that is not proven answers 404.