API documentation

Start an audit

curl -s -X POST https://abackaudit.com/api/v1/audits \
  -H 'Content-Type: application/json' \
  -H 'User-Agent: my-agent/1.0 (+https://example.com/agent)' \
  -d '{"url":"https://example.com","mode":"quick"}'

The answer carries the id of the audit, the links to the report and a delete token that is shown once. Add ?wait=25 to hold the connection until the audit finishes.

Read the report

curl -s https://abackaudit.com/api/v1/audits/<id>
curl -s "https://abackaudit.com/api/v1/audits/<id>?format=md"
curl -s "https://abackaudit.com/api/v1/audits/<id>?format=summary"

The default format is JSON and matches the report schema. The Markdown format is the one to paste into a model. The summary format keeps the scores and the ten findings that matter.

A report

A finished report looks like this. The findings come with the evidence behind them, and the action plan carries the order in which to fix them.

{
  "id": "aud_2f8k3m1p9q0r7s6t5u4v3w2x1y0z",
  "status": "completed",
  "url": "https://example.com/",
  "final_url": "https://www.example.com/",
  "mode": "quick",
  "engine_version": "2.0.0",
  "scoring_version": "2.0",
  "pages_audited": 1,
  "score": {
    "overall": 72,
    "rating": "fair",
    "capped": false,
    "categories": {
      "crawl": 85, "ai": 55, "page": 78, "schema": 40,
      "perf": 66, "a11y": 90, "sec": 70
    }
  },
  "summary": { "pass": 31, "warn": 9, "fail": 7, "info": 4, "skipped": 3, "error": 1 },
  "action_plan": {
    "current_score": 72,
    "projected_score": 91,
    "capped": false,
    "finding_count": 16,
    "empty": false,
    "steps": [
      {
        "id": "ai",
        "rank": 1,
        "title": "AI assistants cannot read this site",
        "severity": "high",
        "score_impact": 10,
        "effort": "medium",
        "unblocks": false,
        "check_ids": ["ai.bot-fetch-parity"],
        "actions": [
          {
            "check_id": "ai.bot-fetch-parity",
            "title": "AI crawlers receive a block page",
            "detail": "Check the WAF rules that match the AI crawler user agents.",
            "docs_url": "https://abackaudit.com/checks/bot-fetch-parity"
          }
        ]
      }
    ]
  },
  "findings": [
    {
      "check_id": "ai.bot-fetch-parity",
      "category": "ai",
      "status": "fail",
      "severity": "high",
      "confidence": "high",
      "title": "AI crawlers receive a block page",
      "message": "Requests with the OAI-SearchBot user agent received HTTP 403, while the default user agent received HTTP 200.",
      "evidence": {
        "baseline": { "status": 200 },
        "variants": [{ "ua": "OAI-SearchBot", "status": 403 }]
      },
      "affected": { "count": 1, "urls": ["https://www.example.com/"] },
      "fix": {
        "summary": "Check the WAF rules that match the AI crawler user agents.",
        "docs_url": "https://abackaudit.com/checks/bot-fetch-parity"
      }
    }
  ],
  "limits": [
    "Performance numbers are lab measurements from one region, not field data."
  ]
}

What a report holds

A report carries the score of every category, the counts of every status, the findings with the evidence behind them, and an action plan: the findings grouped into themes, ordered by the score each theme recovers. The impact of a step is computed with the scoring formula, so it is never an estimate.

GET /api/v1/audits/<id>?format=md

The Markdown format leads with the plan, so an agent reads the recommended order before the list of findings. The JSON format carries the same plan in the action_plan field.

The endpoints

The MCP server

The server speaks the Model Context Protocol over streamable HTTP and is stateless. Point an agent at it and it can run audits and read reports.

{"mcpServers":{"aback-audit":{"url":"https://abackaudit.com/api/mcp"}}}

It exposes seven tools: run_audit, get_audit, diff_audits, list_checks, get_check, create_monitor and get_monitor.

Monitors

A monitor re-audits a url on a schedule, keeps the history of its runs, and alerts a Slack, Discord or JSON webhook, or a confirmed email address, when the score drops, a check regresses, a critical check starts failing or the site cannot be reached. The free plan allows 3 weekly monitors, Pro 50 daily or weekly ones, in standard mode too.

curl -s -X POST https://abackaudit.com/api/v1/monitors \
  -H 'Content-Type: application/json' \
  -d '{"url":"https://example.com","frequency":"weekly",
       "alert_webhook":"https://hooks.slack.com/services/...",
       "alert_threshold":5,"alert_on_regression":true}'

The answer carries a manage_token, shown once. Send it as X-Monitor-Token to read, change or delete the monitor. A monitor created with a Pro key is also managed with that key.

Badges and exports

Every audit and every monitor has an SVG badge with its score, to put in a README or a status page. A report can also be read as CSV, one row per finding.

![Aback Audit score](https://abackaudit.com/api/v1/monitors/<id>/badge.svg)

Limits

Every response carries RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset. A refusal also carries Retry-After.

Errors

Errors use application/problem+json and carry a stable code.

Discovery files

• /openapi.json - The OpenAPI description of the api.
• /checks.json - Every check with its severity and description.
• /agents/report.schema.json - The JSON schema of a report.
• /llms.txt - The short index of the service.
• /llms-full.txt - Every check, in full.
• /auth.md - How authentication works.
• /.well-known/mcp/server-card.json - The MCP server card.
• /.well-known/api-catalog - The api catalog.