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 (with Retry-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}'
EndpointDescription
GET /meYour plan, its limits and today’s usage.
POST /scansStart 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 /scansYour scans, newest first, 50 per ?page=.
GET /scans/{id}Status, steps, scores and finding counts; site structure for completed crawls.
GET /scans/{id}/findingsEvery finding with severity, category, affected URL, explanation, recommendation and evidence.
GET /scans/{id}/pagesCrawled URLs of a site crawl (status, depth, inlinks, title, words, issues), 200 per ?page=.
GET /websitesYour saved websites with schedule, availability and latest score.
GET /websites/{id}/scansInvestigation 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"}'
EndpointDescription
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.