AnswerBeacon API

Versioned REST API under /v1. Machine-readable spec: /openapi.json (OpenAPI 3.1). Using an AI agent? Start at /docs/agents.

Quickstart

curl -s -X POST https://brandrank.eliteaiempire.com/v1/signup -H 'content-type: application/json' -d '{"email":"you@example.com"}'
# returns {"key":"abk_..."} once; the free key has the read and billing scopes
curl -s "https://brandrank.eliteaiempire.com/v1/audit?url=example.com" -H "Authorization: Bearer $ANSWERBEACON_KEY"

Authentication and scopes

Send Authorization: Bearer <key>. Keys are stored only as SHA-256 hashes. Scopes: read (audits, usage, export), write (alerts, fix pull requests; paid plans), billing (list, create, rotate and revoke keys; delete the account). A key can mint keys only with scopes it holds. Missing, wrong or revoked key: 401. Missing scope: 403.

Endpoints

MCP tool	REST	Scope	confirm	What it does
`answerbeacon_audit_page`	`GET /v1/audit`	read	no	Run the 20-element on-page AI-readiness audit on one public page
`answerbeacon_check_schema`	`GET /v1/audit/schema`	read	no	Schema.org / JSON-LD subset of the audit
`answerbeacon_get_fixes`	`GET /v1/fixes`	read	no	Copy-paste fixes for every missed check
`answerbeacon_visibility_snapshot`	`GET /v1/visibility`	read	no	Instant AI-visibility snapshot (same as the free homepage audit)
`answerbeacon_explain_check`	`GET /v1/checks/{check_id}`	read	no	Explain what one of the 20 checks looks for
`answerbeacon_list_alerts`	`GET /v1/alerts`	read	no	List scheduled snapshot alerts on this account
`answerbeacon_create_alert`	`POST /v1/alerts`	write	yes	Schedule a recurring snapshot email (requires confirm=true; paid plan)
`answerbeacon_open_fix_pr`	`POST /v1/fix-prs`	write	yes	Open a pull request with the fixes on the connected repository (requires confirm=true; Agency plan)
`answerbeacon_get_usage`	`GET /v1/usage`	read	no	Usage, quota and recent metering events for this account
`answerbeacon_export_data`	`GET /v1/export`	read	no	Export every object held for this account (JSON or CSV)
`(REST only)`	`GET /v1/keys`	billing	no	List API keys on this account
`(REST only)`	`POST /v1/keys`	billing	no	Create an API key with a subset of your scopes
`(REST only)`	`DELETE /v1/keys/{key_id}`	billing	no	Revoke an API key
`(REST only)`	`POST /v1/keys/{key_id}/rotate`	billing	no	Replace a key: returns a new key and revokes the old one
`(REST only)`	`DELETE /v1/account`	billing	yes	Delete all keys, usage records and alerts for this account (requires confirm=true)
`(REST only)`	`POST /v1/signup`	public	no	Get a free read-only API key (no card)

Errors

Every error is {"error":{"code","message","request_id"}}. Codes: unauthorized 401, insufficient_scope 403, quota_exceeded and paid_plan_required 402, confirmation_required 409, page_unreadable and invalid_request 422, rate_limited 429. A page that cannot be read never returns a guessed score.

Rate limits

60 requests per minute per key. Every response carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset; a 429 adds Retry-After (seconds).

Writes, confirmation and idempotency

Actions that change state or send email require "confirm": true; without it the call is refused with 409 and describes what would happen. Send an Idempotency-Key header on POST to make retries safe.

Usage, export, deletion

GET /v1/usage shows your monthly usage and quota. GET /v1/export returns everything held for the account (?format=csv for the usage log). DELETE /v1/account?confirm=true deletes keys, usage and alerts.

Prices

See /pricing. Audit calls: 100 free per month without a paid plan; included in every paid plan.