API Reference

CrawlSage APIs are currently focused on authenticated dashboard workflows for starting audits, reading results, and applying approved SEO fixes.

Authentication

Most endpoints require an authenticated user session or JWT issued by CrawlSage auth. Public report endpoints are read-only and do not require auth.

Authorization: Bearer YOUR_JWT_TOKEN

Audits endpoint

POST /api/v1/audit/start

Start a new audit for a website URL and audit type.

{
  "website": "https://example.com",
  "type": "full-audit"
}

Audit status endpoint

GET /api/v1/audit/{auditId}/audit-status

Check progress, status, and runtime metadata for an audit.

Reports endpoint

GET /api/v1/audit/{auditId}/results

Get full audit results and SEO findings for a completed audit.

{
  "success": true,
  "data": {
    "audit": {
      "id": "audit_123",
      "status": "completed"
    }
  }
}

Optimization endpoints

• GET /api/v1/audit/{auditId}/seo-issues - list optimization issues.
• GET /api/v1/audit/{auditId}/issues/{issueId}/preview-apply - preview a change and receive a short-lived approval token.
• POST /api/v1/audit/{auditId}/issues/{issueId}/apply - apply one approved change (requires approvalToken).
• POST /api/v1/audit/{auditId}/issues/bulk-apply - apply multiple approved changes (requires per-issue approvals map).
• POST /api/v1/audit/{auditId}/applied-changes/{appliedChangeId}/rollback - rollback an applied change.

POST /api/v1/audit/{auditId}/issues/{issueId}/apply
{
  "approvalToken": "token-from-preview",
  "overrideSuggestedValue": "Optional edited value"
}

WordPress endpoint

• GET /api/v1/audit/websites/{websiteId}/wordpress/verify - verify WordPress connection health.
• POST /api/v1/audit/websites/{websiteId}/wordpress/connect - connect/update WordPress credentials.
• POST /api/v1/audit/websites/{websiteId}/wordpress/disconnect - disconnect WordPress credentials.

Error responses

CrawlSage uses standard HTTP response codes for errors:

• 400 Bad Request: Validation failed.
• 401 Unauthorized: Missing or invalid auth.
• 403 Forbidden: You don't have access to the requested project.
• 404 Not Found: The requested resource doesn't exist.
• 429 Too Many Requests: Rate limit exceeded.

Needs verification: dedicated public API keys and long-term third-party API stability are not finalized yet.