API Reference

Getting Started

Generate an API key from your dashboard under Settings → API Keys. Keys start with dys_ and are shown only once on creation - store it somewhere safe.

Then make your first request:

curl https://didyouseo.com/api/v1/ping \
  -H "Authorization: Bearer dys_your_key_here"

Authentication

Pass your API key in the Authorization header as a Bearer token on every request (except /ping):

Authorization: Bearer dys_a1b2c3d4e5f6...

Invalid or missing keys return 401 Unauthorized.

Rate Limits

Rate limits are applied per API key. When you exceed a limit the API returns 429 Too Many Requests with a Retry-After header (seconds to wait).

Endpoints

All endpoints are prefixed with https://didyouseo.com/api/v1.

Ping

{ "ok": true, "version": "1.0" }

Sites

{
  "sites": [
    {
      "id": "abc123",
      "url": "https://example.com",
      "label": "My Blog",
      "created_at": "2026-05-11T10:00:00Z"
    }
  ]
}

{
  "url": "https://example.com",
  "label": "My Blog"
}

{
  "id": "abc123",
  "url": "https://example.com",
  "label": "My Blog",
  "created_at": "2026-05-11T10:00:00Z"
}

Audits

{
  "url": "https://example.com/blog/my-post",
  "site_id": "abc123",
  "webhook_url": "https://example.com/wp-json/didyouseo/v1/webhook"
}

{
  "audit_id": "audit_a1b2c3d4",
  "status": "queued",
  "url": "https://example.com/blog/my-post"
}

// While running:
{ "audit_id": "audit_a1b2c3d4", "status": "running", "url": "..." }

// When complete:
{
  "audit_id": "audit_a1b2c3d4",
  "status": "complete",
  "url": "https://example.com/blog/my-post",
  "score": 74,
  "critical_count": 3,
  "warning_count": 5,
  "good_count": 12,
  "completed_at": "2026-05-11T10:05:00Z",
  "checks": [ ... ]
}

Scores

{
  "site_id": "abc123",
  "url": "https://example.com",
  "score": 81,
  "total_pages": 24,
  "total_criticals": 8,
  "total_warnings": 15,
  "last_audited_at": "2026-05-11T08:00:00Z",
  "top_issues": [
    {
      "check_name": "Missing meta description",
      "status": "critical",
      "affected_pages": 6
    }
  ]
}

{
  "url": "https://example.com/blog/my-post",
  "score": 68,
  "critical_count": 2,
  "warning_count": 3,
  "last_audited_at": "2026-05-11T08:00:00Z",
  "report_url": "https://didyouseo.com/dashboard/site-audit"
}

Bot Traffic

Report AI-crawler and bot visits from your server so they appear in your Track → Bot Traffic dashboard. The easiest way is our npm package - install @didyouseo/bot-traffic and add one line to your middleware (Next.js, Cloudflare, Express, and Hono examples are in the package README). The endpoint below is what the package calls - use it directly from any other stack.

{
  "token": "your_tracking_token",
  "path": "/pricing",
  "userAgent": "GPTBot/1.2",
  "ip": "203.0.113.7",      // optional
  "status": 200             // optional
}

// 204 No Content on success (also for non-bot user-agents)
// 400 { "error": "token, path, and userAgent are required." }
// 401 { "error": "Unknown tracking token." }

Webhooks

Supply a webhook_url when triggering an audit and we will POST the result to your endpoint once complete - no polling needed.

{
  "event": "audit.complete",
  "audit_id": "audit_a1b2c3d4",
  "url": "https://example.com/blog/my-post",
  "score": 74,
  "critical_count": 3,
  "warning_count": 5,
  "good_count": 12,
  "completed_at": "2026-05-11T10:05:00Z"
}

// PHP example
$body      = file_get_contents('php://input');
$expected  = 'sha256=' . hash_hmac('sha256', $body, YOUR_API_KEY_PREFIX);
$received  = $_SERVER['HTTP_X_DIDYOUSEO_SIGNATURE'];

if (!hash_equals($expected, $received)) {
    http_response_code(401);
    exit;
}

Error Codes

All error responses include a JSON body: { "error": "description" }

MCP Server (Claude, ChatGPT, Cursor)

DidYouSEO runs a remote Model Context Protocol server, so AI assistants can run SEO audits and use the site tools directly in chat. It exposes audit and site tools (account-scoped) plus free SEO tools - meta tags, robots.txt, schema, SERP preview, Core Web Vitals, Open Graph and hreflang.

Connect the remote server and sign in with your DidYouSEO account when prompted - no API key to copy. Authentication uses OAuth 2.1 (PKCE, dynamic client registration).

https://didyouseo.com/mcp

For clients that only support local (stdio) servers, use the bridge package:

{
  "mcpServers": {
    "didyouseo": {
      "command": "npx",
      "args": ["-y", "@didyouseo/mcp"]
    }
  }
}