API Reference

The CrawlSage API allows you to programmatically trigger audits, retrieve reports, and manage projects.

Authentication

All API requests must be authenticated using a Bearer token. You can generate an API key in your account settings.

Authorization: Bearer YOUR_API_KEY

Audits endpoint

POST /v1/audits

Trigger a new audit for a specific project.

{
  "project_id": "proj_123",
  "mode": "technical_seo",
  "depth": 3
}

Issues endpoint

GET /v1/issues

Retrieve a list of issues found in the latest audit.

Query Parameters:

• project_id (required)
• severity (optional: critical, warning, notice)
• limit (optional, default: 20)

Reports endpoint

GET /v1/reports/{report_id}

Get a summary report of a completed audit.

{
  "report_id": "rep_987",
  "health_score": 88,
  "pages_crawled": 450,
  "issues_found": {
    "critical": 2,
    "warning": 15,
    "notice": 40
  }
}

Error responses

CrawlSage uses standard HTTP response codes for errors:

• 401 Unauthorized: Missing or invalid API key.
• 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 (100 requests per minute).