Developers
REST API
Start investigations, site crawls and SEO tool checks from your own scripts, and read their results as JSON. The API is available on plans that include API access; create a key in your account settings.
Authentication and limits
Send your key in the Authorization header (or X-API-Key). Keys are shown once when created and can be revoked at any time.
curl -H "Authorization: Bearer tsd_…" https://theseodetective.com/api/v1/me
- 60 requests per minute per key, and your plan’s daily request allowance (reset at 00:00 UTC).
- Investigations, crawls and tool checks count against the same allowances as in the dashboard.
- Errors return a JSON body
{"error": {"code": "…", "message": "…"}}with an HTTP status: 400, 401, 403, 404, 409, 422, 429 (withRetry-After) or 503. - Only public http(s) addresses can be investigated; private and reserved networks are refused.
Investigations and crawls
Work is asynchronous: create a scan, then poll it until status is complete or failed (a page takes 10–60 seconds; a crawl minutes).
curl -X POST https://theseodetective.com/api/v1/scans \
-H "Authorization: Bearer tsd_…" -H "Content-Type: application/json" \
-d '{"url": "https://www.example.com/", "mode": "crawl", "pages": 100}'
| Endpoint | Description |
|---|---|
GET /me | Your plan, its limits and today’s usage. |
POST /scans | Start one. Body: url, optional mode (page or crawl), pages (10, 50, 100, 500 or 1000 within your plan), website_id. Returns 202 with the scan. |
GET /scans | Your scans, newest first, 50 per ?page=. |
GET /scans/{id} | Status, steps, scores and finding counts; site structure for completed crawls. |
GET /scans/{id}/findings | Every finding with severity, category, affected URL, explanation, recommendation and evidence. |
GET /scans/{id}/pages | Crawled URLs of a site crawl (status, depth, inlinks, title, words, issues), 200 per ?page=. |
GET /websites | Your saved websites with schedule, availability and latest score. |
GET /websites/{id}/scans | Investigation history of one website. |
SEO tools
curl -X POST https://theseodetective.com/api/v1/tools/robots-txt-checker \
-H "Authorization: Bearer tsd_…" -H "Content-Type: application/json" \
-d '{"url": "https://www.example.com/", "test_path": "/private/", "user_agent": "GPTBot"}'
| Endpoint | Description |
|---|---|
POST /tools/{tool} | Run a tool: meta-tag-checker, robots-txt-checker, sitemap-validator, redirect-checker, http-header-checker, ssl-checker, heading-analyzer, canonical-checker, structured-data-checker, broken-link-checker, keyword-analyzer. Body: url plus the tool’s own fields (test_path, user_agent, keywords). |
GET /tools/runs/{id} | Status and, when complete, the full result: summary, findings and tool data. |
Data you will not find here
The API returns what our crawler measured. It does not return search rankings, traffic, backlinks, search volumes or keyword difficulty, because we do not estimate data we do not have.