{"openapi":"3.1.0","info":{"title":"Aback Audit API","version":"2.0.0","summary":"Server side website audits for SEO, AI search readiness, performance, accessibility and security.","description":"Aback Audit reads a public website the way a crawler would and reports what it finds.\n\nThere is no account, no API key and no cookie. The limits are per client address and per audited domain.\n\nEvery response carries `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset`.\n\nErrors use `application/problem+json` and carry a stable `code`.","license":{"name":"Aback","url":"https://abackaudit.com/terms"},"contact":{"name":"Aback","url":"https://abackaudit.com/contact"}},"servers":[{"url":"https://abackaudit.com/api/v1","description":"The production api."}],"tags":[{"name":"audits","description":"Run audits and read reports."},{"name":"checks","description":"The catalog of checks."},{"name":"ai-bots","description":"The AI crawlers the audit knows about."},{"name":"monitors","description":"Scheduled re-audits with alerts."}],"paths":{"/audits":{"get":{"tags":["audits"],"operationId":"listAudits","summary":"List the audits this client started.","description":"The list is bound to the address of the client, so it only ever contains the audits that the same client started.","parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":200,"default":20}}],"responses":{"200":{"description":"The recent audits of the client."}}},"post":{"tags":["audits"],"operationId":"createAudit","summary":"Run an audit of a public website.","description":"Starts an audit and returns immediately with its id. Add `?wait=25` to hold the connection until the audit finishes or the time runs out. Repeating the same request within 15 minutes returns the existing report with `cached: true`.","parameters":[{"name":"wait","in":"query","required":false,"description":"Seconds to wait for the audit to finish. Maximum 25.","schema":{"type":"integer","minimum":0,"maximum":25}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Makes a retried request safe. The same key within 24 hours returns the same audit.","schema":{"type":"string","maxLength":64}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateAuditRequest"},"examples":{"quick":{"summary":"A quick audit","value":{"url":"https://example.com","mode":"quick"}},"standard":{"summary":"A standard audit that samples pages","value":{"url":"https://example.com","mode":"standard"}}}}}},"responses":{"200":{"description":"A cached report was returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuditCreated"}}}},"202":{"description":"The audit was queued.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuditCreated"}}}},"400":{"description":"The request is not valid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"The target does not allow the audit.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"A rate limit was reached.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/audits/{id}":{"get":{"tags":["audits"],"operationId":"getAudit","summary":"Read the report of an audit.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"format","in":"query","required":false,"schema":{"type":"string","enum":["json","md","summary","csv"],"default":"json"}},{"name":"wait","in":"query","required":false,"description":"Seconds to wait for a running audit. Maximum 25.","schema":{"type":"integer","minimum":0,"maximum":25}}],"responses":{"200":{"description":"The report.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuditReport"}},"text/markdown":{"schema":{"type":"string"}}}},"404":{"description":"There is no audit with that id.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"410":{"description":"The report has passed its retention date.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"delete":{"tags":["audits"],"operationId":"deleteAudit","summary":"Delete a report before its retention date.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"X-Delete-Token","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"The report was deleted."},"400":{"description":"The token does not match.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/audits/{id}/findings":{"get":{"tags":["audits"],"operationId":"listFindings","summary":"List the findings of an audit with filters.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"severity","in":"query","schema":{"type":"string","enum":["critical","high","medium","low","info"]}},{"name":"category","in":"query","schema":{"type":"string","enum":["crawl","ai","page","schema","perf","a11y","sec"]}},{"name":"status","in":"query","schema":{"type":"string","enum":["pass","warn","fail","info","skipped","error"]}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":200,"default":50}},{"name":"cursor","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"The filtered findings."},"404":{"description":"There is no audit with that id.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/audits/{id}/diff":{"get":{"tags":["audits"],"operationId":"diffAudits","summary":"Compare two audits of the same site.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"against","in":"query","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"What was fixed, what regressed and what is new."}}}},"/audits/{id}/badge.svg":{"get":{"tags":["audits"],"operationId":"getAuditBadge","summary":"An SVG badge with the score of the audit.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"The badge.","content":{"image/svg+xml":{"schema":{"type":"string"}}}}}}},"/monitors":{"get":{"tags":["monitors"],"operationId":"listMonitors","summary":"List the monitors of a Pro license key.","parameters":[{"name":"X-Aback-Pro-Key","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"The monitors of the key."},"403":{"description":"No active Pro key was sent.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"post":{"tags":["monitors"],"operationId":"createMonitor","summary":"Re-audit a site on a schedule and alert on regressions.","description":"Creates a monitor and starts its first audit. The answer carries a `manage_token`, shown once, which reads, changes and deletes the monitor through the `X-Monitor-Token` header. A monitor created with a Pro key is also managed with the key.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateMonitorRequest"}}}},"responses":{"201":{"description":"The monitor, with its manage token."},"400":{"description":"The request is not valid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"The plan does not allow it: `monitor_limit` or `plan_required`.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"You already monitor this url: `monitor_exists`.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Too many monitors created in the last hour.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/monitors/{id}":{"get":{"tags":["monitors"],"operationId":"getMonitor","summary":"Read a monitor and the history of its runs.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"runs","in":"query","schema":{"type":"integer","minimum":1,"maximum":180,"default":60}},{"name":"X-Monitor-Token","in":"header","schema":{"type":"string"}}],"responses":{"200":{"description":"The monitor."},"403":{"description":"The token does not own the monitor.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"There is no monitor with that id.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"patch":{"tags":["monitors"],"operationId":"updateMonitor","summary":"Change the schedule or the alerts, or pause the monitor.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"X-Monitor-Token","in":"header","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateMonitorRequest"}}}},"responses":{"200":{"description":"The updated monitor."},"403":{"description":"Not allowed by the token or the plan.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"delete":{"tags":["monitors"],"operationId":"deleteMonitor","summary":"Delete a monitor and its run history.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"X-Monitor-Token","in":"header","schema":{"type":"string"}}],"responses":{"200":{"description":"The monitor was deleted."}}}},"/monitors/{id}/run":{"post":{"tags":["monitors"],"operationId":"runMonitor","summary":"Run the monitor now, outside its schedule. At most once every 15 minutes.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"X-Monitor-Token","in":"header","schema":{"type":"string"}}],"responses":{"202":{"description":"The audit was started."},"409":{"description":"An audit of the monitor is already running.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"The monitor ran by hand too recently.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/monitors/{id}/test-alert":{"post":{"tags":["monitors"],"operationId":"testMonitorAlert","summary":"Send a test alert to the channels of the monitor.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"X-Monitor-Token","in":"header","schema":{"type":"string"}}],"responses":{"200":{"description":"The result of each delivery."}}}},"/monitors/{id}/badge.svg":{"get":{"tags":["monitors"],"operationId":"getMonitorBadge","summary":"An SVG badge with the latest score of the monitor.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"The badge.","content":{"image/svg+xml":{"schema":{"type":"string"}}}}}}},"/checks":{"get":{"tags":["checks"],"operationId":"listChecks","summary":"List every check.","parameters":[{"name":"category","in":"query","schema":{"type":"string","enum":["crawl","ai","page","schema","perf","a11y","sec"]}}],"responses":{"200":{"description":"The check catalog."}}}},"/checks/{id}":{"get":{"tags":["checks"],"operationId":"getCheck","summary":"Read one check.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"The check."},"404":{"description":"There is no check with that id."}}}},"/ai-bots":{"get":{"tags":["ai-bots"],"operationId":"listAiBots","summary":"List the AI crawlers the audit knows about.","responses":{"200":{"description":"The AI crawler registry."}}}}},"components":{"schemas":{"CreateMonitorRequest":{"type":"object","required":["url"],"additionalProperties":false,"properties":{"url":{"type":"string","description":"The public url to monitor."},"label":{"type":["string","null"],"maxLength":80},"frequency":{"type":"string","enum":["daily","weekly"],"default":"weekly","description":"Daily needs a Pro key."},"mode":{"type":"string","enum":["quick","standard"],"default":"quick","description":"Standard needs a Pro key."},"alert_email":{"type":["string","null"],"format":"email","description":"Confirmed by a link before any alert is sent."},"alert_webhook":{"type":["string","null"],"format":"uri","description":"An https url. Slack and Discord webhooks get their own message format."},"alert_threshold":{"type":"integer","minimum":1,"maximum":50,"default":5,"description":"The score drop, in points, that sends an alert."},"alert_on_regression":{"type":"boolean","default":true},"alert_on_unreachable":{"type":"boolean","default":true}}},"UpdateMonitorRequest":{"type":"object","additionalProperties":false,"properties":{"label":{"type":["string","null"],"maxLength":80},"frequency":{"type":"string","enum":["daily","weekly"]},"mode":{"type":"string","enum":["quick","standard"]},"status":{"type":"string","enum":["active","paused"]},"alert_email":{"type":["string","null"],"format":"email","description":"Confirmed by a link before any alert is sent."},"alert_webhook":{"type":["string","null"],"format":"uri","description":"An https url. Slack and Discord webhooks get their own message format."},"alert_threshold":{"type":"integer","minimum":1,"maximum":50,"default":5,"description":"The score drop, in points, that sends an alert."},"alert_on_regression":{"type":"boolean","default":true},"alert_on_unreachable":{"type":"boolean","default":true}}},"CreateAuditRequest":{"type":"object","required":["url"],"properties":{"url":{"type":"string","description":"A public http or https url."},"mode":{"type":"string","enum":["quick","standard","deep"],"default":"quick"},"categories":{"type":"array","items":{"type":"string","enum":["crawl","ai","page","schema","perf","a11y","sec"]}},"checks":{"type":"array","items":{"type":"string"}},"exclude_checks":{"type":"array","items":{"type":"string"}},"fresh":{"type":"boolean","description":"Bypass the 15 minute result cache."}}},"AuditCreated":{"type":"object","required":["id","status","url","mode","created_at","expires_at","links"],"properties":{"id":{"type":"string"},"status":{"type":"string","enum":["queued","running","completed","failed"]},"url":{"type":"string"},"mode":{"type":"string","enum":["quick","standard","deep"]},"cached":{"type":"boolean"},"created_at":{"type":"string","format":"date-time"},"expires_at":{"type":"string","format":"date-time"},"delete_token":{"type":"string","description":"Shown once. Use it with the X-Delete-Token header to delete the report."},"progress":{"type":"object","properties":{"pages_done":{"type":"integer"},"pages_total":{"type":"integer"},"checks_done":{"type":"integer"},"checks_total":{"type":"integer"}}},"score":{"$ref":"#/components/schemas/Score"},"summary":{"$ref":"#/components/schemas/Summary"},"links":{"type":"object","properties":{"self":{"type":"string"},"report":{"type":"string"},"markdown":{"type":"string"}}}}},"Score":{"type":"object","properties":{"overall":{"type":"integer","minimum":0,"maximum":100},"rating":{"type":"string","enum":["good","fair","poor"]},"capped":{"type":"boolean"},"categories":{"type":"object","additionalProperties":{"type":["integer","null"]}}}},"Summary":{"type":"object","properties":{"pass":{"type":"integer"},"warn":{"type":"integer"},"fail":{"type":"integer"},"info":{"type":"integer"},"skipped":{"type":"integer"},"error":{"type":"integer"}}},"Finding":{"type":"object","required":["check_id","category","status","severity","confidence","title","message"],"properties":{"check_id":{"type":"string"},"category":{"type":"string","enum":["crawl","ai","page","schema","perf","a11y","sec"]},"status":{"type":"string","enum":["pass","warn","fail","info","skipped","error"]},"severity":{"type":"string","enum":["critical","high","medium","low","info"]},"confidence":{"type":"string","enum":["high","medium","low"]},"title":{"type":"string"},"message":{"type":"string"},"evidence":{"type":"object","additionalProperties":true},"affected":{"type":"object","properties":{"count":{"type":"integer"},"urls":{"type":"array","items":{"type":"string"}}}},"fix":{"type":"object","properties":{"summary":{"type":"string"},"docs_url":{"type":"string"}}}}},"AuditReport":{"type":"object","required":["id","status","url","mode","score","summary","findings","limits"],"properties":{"id":{"type":"string"},"status":{"type":"string","enum":["queued","running","completed","failed","expired"]},"url":{"type":"string"},"final_url":{"type":["string","null"]},"mode":{"type":"string","enum":["quick","standard","deep"]},"region":{"type":["string","null"]},"created_at":{"type":"string","format":"date-time"},"completed_at":{"type":["string","null"],"format":"date-time"},"engine_version":{"type":"string","example":"2.0.0"},"scoring_version":{"type":"string","example":"2.0"},"pages_audited":{"type":"integer"},"score":{"$ref":"#/components/schemas/Score"},"summary":{"$ref":"#/components/schemas/Summary"},"findings":{"type":"array","items":{"$ref":"#/components/schemas/Finding"}},"action_plan":{"$ref":"#/components/schemas/ActionPlan"},"limits":{"type":"array","items":{"type":"string"}}}},"ActionPlan":{"type":"object","description":"The ordered plan of what to do next.","required":["steps","projected_score","current_score","raw_score","capped","finding_count","empty"],"properties":{"steps":{"type":"array","items":{"type":"object","required":["id","rank","title","summary","severity","score_impact","effort","check_ids","actions"],"properties":{"id":{"type":"string"},"rank":{"type":"integer","minimum":1},"title":{"type":"string"},"summary":{"type":"string"},"severity":{"type":"string","enum":["critical","high","medium","low","info"]},"score_impact":{"type":"integer","description":"The points the overall score gains when the step is done."},"effort":{"type":"string","enum":["low","medium","high"]},"check_ids":{"type":"array","items":{"type":"string"}},"actions":{"type":"array","items":{"type":"object","required":["check_id","title","detail","docs_url"],"properties":{"check_id":{"type":"string"},"title":{"type":"string"},"detail":{"type":"string"},"docs_url":{"type":"string"}}}}}}},"projected_score":{"type":"integer","minimum":0,"maximum":100},"current_score":{"type":"integer","minimum":0,"maximum":100},"raw_score":{"type":"integer","minimum":0,"maximum":100,"description":"The score without the critical failure cap."},"capped":{"type":"boolean"},"finding_count":{"type":"integer","minimum":0},"empty":{"type":"boolean"}}},"Problem":{"type":"object","required":["type","title","status","code","detail"],"properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"code":{"type":"string"},"detail":{"type":"string"}}}}},"x-checks":55}