REST API & Integrations

What Can You Build with the SEOdiag API?

The SEOdiag REST API lets you integrate our technical SEO crawler and GEO citability engine directly into your internal workflows, CI/CD deployment gates, CRMs, or B2B sales prospecting pipelines.

Through the API you can trigger on-demand crawls, poll real-time progress, and retrieve the SEO Health Score, GEO AI Citability Score, severity breakdowns, and prioritized developer tasks (dev_tasks).

---

Plan Requirements & Eligibility

Exclusive to Higher Tiers: Programmatic API access via Bearer tokens is enabled exclusively for accounts with an active Workspace on the Agency ($99) or Enterprise ($159) tiers. API requests targeting Workspaces on lower tiers (Freelance or Growth) will return HTTP 403 Forbidden.

Plan (Tier)	Web Dashboard Access	Programmatic REST API Access	Workspace Concurrency
Freelance ($9)	Included	Not included	1 concurrent audit
Growth ($29)	Included	Not included	1 concurrent audit
Agency ($99)	Included	Enabled	Up to 2 concurrent
Enterprise ($159)	Included	Enabled	Up to 5 concurrent

---

1. Authentication (Bearer JWT)

To authenticate against https://seodiag.com, send a POST /auth/login request formatted as application/x-www-form-urlencoded with your account email (username) and password.

• When your account belongs to an Agency or Enterprise Workspace, the response returns access_token both in the JSON payload and in the access_token cookie.
• Each token is valid for 12 hours. Cache and reuse the token across requests rather than logging in on every call.

curl -X POST "https://seodiag.com/auth/login" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "username=you@agency.com&password=YourSecurePassword"

JSON Response (Agency and Enterprise plans):

{
  "message": "Login successful",
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "bearer"
}

Include these headers on all subsequent API requests: - Authorization: Bearer <access_token> - X-Workspace-ID: <workspace_id> (required when your account belongs to multiple Workspaces)

---

2. Inspect Workspaces & Credits (GET /workspaces/me)

Before launching crawls, query GET /workspaces/me to list your Workspaces, check their numeric id, active subscription_tier, and remaining available_credits:

curl -s "https://seodiag.com/workspaces/me" \
  -H "Authorization: Bearer $TOKEN"

---

3. Launch an Audit (POST /audit)

Start an asynchronous crawl by specifying the target url and max_pages cap. The ledger reserves max_pages credits upfront and automatically refunds unused credits if the site has fewer internal URLs, or refunds 100% if the target site blocks the crawler.

curl -X POST "https://seodiag.com/audit" \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Workspace-ID: 23" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "max_pages": 100,
    "lang": "en",
    "industry": "saas",
    "slow_mode": false
  }'

Response:

{
  "message": "Auditoría iniciada correctamente en entorno seguro",
  "task_id": "3de6f41a-2170-49e0-9047-8263ad05f1fb"
}

---

4. Poll Status & Retrieve Results

Check task status (GET /tasks/{task_id})

Poll every 10–15 seconds until status transitions to SUCCESS, ERROR, or CANCELED:

curl -s "https://seodiag.com/tasks/3de6f41a-2170-49e0-9047-8263ad05f1fb" \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Workspace-ID: 23"

List audits and fetch the report (GET /audits & GET /audits/{id})

1. List Workspace audits via GET /audits (and match task_id to obtain the numeric id).
2. Fetch executive metrics, scores, and issue counts via GET /audits/{audit_id}?include_urls=false.
3. Fetch prioritized developer tasks via GET /audits/{audit_id}/dev_tasks?limit=50.

Endpoint	Method	Description
/auth/login	POST	Issues a 12-hour access_token JWT
/workspaces/me	GET	Lists your Workspaces, id, tier, and credit balance
/audit	POST	Enqueues a new technical SEO + GEO audit
/tasks/{task_id}	GET	Returns live task status (PENDING, RUNNING, SUCCESS, ERROR)
/audits	GET	Lists audit history for the active Workspace
/audits/{id}	GET	Returns full audit summary (score, geo_score_avg, issues)
/audits/{id}/dev_tasks	GET	Returns paginated actionable tasks for developers

Need help with your custom integration? Contact us