BEACON API Reference

Beacon API

A simple, key-authenticated REST API for pulling your Beacon audit scores, AI-visibility data and latest audit summaries into your own dashboards, data warehouse or client reports. The API is read-only and returns only data for projects you own.

Enterprise planREST · JSONBearer-key auth60 req / min

Plan requirement. The Beacon API is available on the Enterprise plan. Generate your key in Settings → API. Calls from accounts whose plan does not include API access return 402 Payment Required.

Authentication

Every request must include your secret API key as a Bearer token. Keys are issued in Settings → API and have the format bcn_ followed by 40 hex characters. Treat the key like a password — it grants read access to all of your projects. You can rotate it at any time (rotating immediately revokes the previous key).

Authorization: Bearer bcn_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

For quick tests you may instead pass the key as a ?key= query parameter, but the Authorization header is strongly preferred (query strings are easily logged).

Base URL

https://ibeacon.ai/api/v1

Endpoint

`GET /api/v1/audit`

Returns the latest completed audit summary and rollup scores for every projectowned by the key's account. No parameters are required.

Request

curl -s "https://ibeacon.ai/api/v1/audit" \
  -H "Authorization: Bearer bcn_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

JavaScript (fetch):

const res = await fetch("https://ibeacon.ai/api/v1/audit", {
  headers: { Authorization: `Bearer ${process.env.BEACON_API_KEY}` },
});
if (!res.ok) throw new Error(`Beacon API ${res.status}`);
const { projects, count } = await res.json();

Response · 200 OK

scores are 0–100 (higher is better). latestAudit.summary mirrors the dashboard audit summary (crawled page count, error/warning counts, Core Web Vitals, etc.). Fields are null when a project has not been audited yet. Every value is measured — Beacon never returns fabricated numbers.

{
  "projects": [
    {
      "id": "6a40...430d",
      "name": "Plagly",
      "domain": "plagly.ai",
      "scores": {
        "visibility": 69,
        "seo": 72,
        "geo": 76,
        "technical": 92,
        "content": 0
      },
      "lastAuditAt": "2026-06-27T22:06:00.000Z",
      "latestAudit": {
        "finishedAt": "2026-06-27T22:06:00.000Z",
        "summary": {
          "crawled": 400,
          "errors": 1,
          "warnings": 2,
          "cwv": { "lcp": 2.9, "cls": 0.027, "tbt": 319 }
        }
      }
    }
  ],
  "count": 1
}

Rate limits

Each key may make up to 60 requests per minute. Exceeding the limit returns 429 Too Many Requests; back off and retry after a short pause. For higher volumes or scheduled syncs, pull once and cache — audit data only changes when an audit re-runs (daily/weekly on your schedule).

Errors

Status	Meaning
`401`	Missing, malformed, or invalid API key.
`402`	Your plan no longer includes API access (Enterprise required).
`429`	Rate limit exceeded (60 req/min per key).

Error bodies are JSON: { "error": "Invalid API key." }

Managing keys

Generate / rotate: Settings → API. The full key is shown once on creation — store it securely.
Revoke: rotating issues a new key and immediately invalidates the old one.
Scope: a key can read only the projects owned by its account.

Versioning & stability

The API is versioned in the path (/api/v1). Additive changes (new fields) may ship without a version bump; breaking changes will be released under a new version. Questions or need more endpoints? Email support@ibeacon.ai.