API Reference

The backend exposes a REST API at http://localhost:8080 (default). All endpoints return JSON.

Endpoints

GET /api/rules

Returns all available audit rules grouped by category, and all rule presets.

curl http://localhost:8080/api/rules | jq

Response:

{
  "categories": [
    {
      "key": "on-page",
      "label": "On-Page SEO",
      "rules": [
        { "key": "title_exists", "label": "Page has a <title> tag", "severity": "critical" }
      ]
    }
  ],
  "presets": [
    {
      "key": "full_scan",
      "label": "Full Scan",
      "description": "All 130+ checks for maximum coverage",
      "ruleKeys": ["title_exists", "..."]
    }
  ]
}

POST /api/crawl

Start a new crawl job for a domain.

curl -X POST http://localhost:8080/api/crawl \
  -H "Content-Type: application/json" \
  -d '{
    "domain": "example.com",
    "maxPages": 100,
    "selectedRules": ["title_exists", "h1_count"]
  }'

Request body:

Field	Type	Description
`domain`	string	Required. Domain to crawl (e.g. `example.com` or `localhost:3000`)
`maxPages`	number	Optional. Max pages to crawl. `0` = unlimited.
`selectedRules`	string[]	Optional. Rule keys to run. Empty = all rules.

Response:

{
  "id": "uuid-of-the-crawl-job",
  "status": "queued"
}

GET /api/crawl/:id/progress

Server-Sent Events stream for real-time crawl progress.

curl -N http://localhost:8080/api/crawl/<job-id>/progress

Events include page completion, page count, and final result data.

GET /api/report/:id

Get the full audit report for a completed crawl job.

curl http://localhost:8080/api/report/<job-id> | jq

GET /api/report/:id/export/csv

Download the report as a CSV file.

curl -o report.csv http://localhost:8080/api/report/<job-id>/export/csv

Query params: ?exclude=rule_key1,rule_key2 to omit specific rules.

GET /api/report/:id/export/md

Download the report as a Markdown file (AI-agent-friendly format).

curl -o report.md http://localhost:8080/api/report/<job-id>/export/md

Query params: ?exclude=rule_key1,rule_key2 to omit specific rules.

GET /api/health

Health check endpoint.

curl http://localhost:8080/api/health

Response: {"status":"ok"}

Authentication

The API does not require authentication when running locally. All endpoints are accessible without tokens or API keys. If you deploy the server publicly, consider adding authentication middleware or placing it behind a reverse proxy with access controls.

Rate Limiting

There are no built-in rate limits on the API. The worker pool processes one crawl job at a time per worker (default: 2 workers). Additional crawl requests are queued and processed in order. The SSE progress stream is lightweight and suitable for long-polling clients.

Error Responses

All error responses follow this format:

{
  "error": "Human-readable error message"
}

Common HTTP status codes: 400 for invalid input, 404 for unknown job IDs, 500 for internal server errors.

Example: cURL

# Start a crawl
curl -X POST http://localhost:8080/api/crawl \
  -H "Content-Type: application/json" \
  -d '{"domain": "example.com"}'

# Get the report
curl http://localhost:8080/api/report/YOUR_JOB_ID

# Export as markdown
curl http://localhost:8080/api/report/YOUR_JOB_ID/export/md -o report.md