BEACON AI API

Run AI visibility audits, validate agent.json files, and retrieve brand intelligence programmatically. All endpoints return JSON. Audits deduct 1 credit from your balance.

Base URL:https://usebeacon.in/api/v1

Authentication

All API requests require an API key passed as a Bearer token. Generate your key in Settings → API Keys.

bash

curl https://usebeacon.in/api/v1/audit \
  -H "Authorization: Bearer bk_live_your_key_here"

Keep your API key secret. Never expose it in client-side code. Rotate it immediately if compromised.

Run Audit

POST/api/v1/audit

Runs a full AI visibility audit across Claude, ChatGPT, Perplexity, and Gemini. Returns scores, insights, and share of voice. Takes 1–4 minutes. Deducts 1 credit.

Request body

brandName

stringrequired

The brand or company name to audit.

domain

stringrequired

Primary domain (no https://). E.g. acmecorp.com

industry

string

Industry/category hint. Improves query relevance. E.g. project management software

queries

string[]

Up to 5 custom queries to include alongside generated ones.

Example

bash

curl -X POST https://usebeacon.in/api/v1/audit \
  -H "Authorization: Bearer bk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "brandName": "Acme Corp",
    "domain": "acmecorp.com",
    "industry": "project management software"
  }'

python

import requests

response = requests.post(
    "https://usebeacon.in/api/v1/audit",
    headers={"Authorization": "Bearer bk_live_your_key_here"},
    json={
        "brandName": "Acme Corp",
        "domain": "acmecorp.com",
        "industry": "project management software",
    },
    timeout=60,
)
data = response.json()
print(f"AI Visibility Score: {data['aiVisibilityScore']}")

Response

json

{
  "ok": true,
  "brand": "Acme Corp",
  "domain": "acmecorp.com",
  "aiVisibilityScore": 42,
  "aeiq": {
    "overall": 42,
    "presence": 35,
    "authority": 58,
    "sentiment": 71,
    "consistency": 28,
    "topPick": 12
  },
  "platformScores": [
    { "platform": "chatgpt", "score": 55, "mentionCount": 8, "avgRank": 2.1 },
    { "platform": "claude",  "score": 38, "mentionCount": 5, "avgRank": 3.0 },
    { "platform": "gemini",  "score": 42, "mentionCount": 6, "avgRank": 2.5 },
    { "platform": "perplexity", "score": 31, "mentionCount": 4, "avgRank": 3.2 }
  ],
  "insights": [
    {
      "type": "opportunity",
      "priority": "high",
      "title": "Low AI Presence",
      "body": "Acme Corp appears in only 35% of AI queries..."
    }
  ],
  "queriesRun": 15,
  "mentionRate": 0.35
}

Get Report

GET/api/v1/report

Returns the most recent audit report for a domain. No credit deducted — reads from your audit history.

bash

curl "https://usebeacon.in/api/v1/report?domain=acmecorp.com" \
  -H "Authorization: Bearer bk_live_your_key_here"

json

{
  "id": "abc123",
  "brand_name": "Acme Corp",
  "domain": "acmecorp.com",
  "audited_at": "2026-10-14T07:00:00Z",
  "overall_score": 42,
  "mention_rate": 35,
  "platforms": [
    { "platform": "chatgpt", "score": 55, "mention_count": 8, "avg_rank": 2.1 },
    { "platform": "claude",  "score": 38, "mention_count": 5, "avg_rank": 3.0 }
  ],
  "share_of_voice": { "target_pct": 18, "total_mentions": 44, "competitors": [] },
  "top_insight": { "priority": "high", "title": "Low AI Presence", "body": "..." }
}

Audit History

GET/api/v1/audits

Lists all audits for your account, optionally filtered by domain. Returns scores and timestamps for charting visibility over time. No credit deducted.

domain

string

Filter to a specific domain. If omitted, returns all domains.

limit

integer

Max results (1–50, default 10).

bash

curl "https://usebeacon.in/api/v1/audits?domain=acmecorp.com&limit=10" \
  -H "Authorization: Bearer bk_live_your_key_here"

json

{
  "audits": [
    {
      "id": "abc123",
      "brand_name": "Acme Corp",
      "domain": "acmecorp.com",
      "audited_at": "2026-10-14T07:00:00Z",
      "overall_score": 42,
      "mention_rate": 35,
      "platforms": [
        { "platform": "chatgpt", "score": 55 },
        { "platform": "claude",  "score": 38 }
      ]
    }
  ],
  "total": 1
}

Category Intelligence

GET/api/v1/category

Returns your brand's category rank and the full AI Share of Voice leaderboard for your domain's category. No credit deducted.

bash

curl "https://usebeacon.in/api/v1/category?domain=acmecorp.com" \
  -H "Authorization: Bearer bk_live_your_key_here"

json

{
  "domain": "acmecorp.com",
  "brand_name": "Acme Corp",
  "audited_at": "2026-10-14T07:00:00Z",
  "category_rank": 3,
  "total_brands_tracked": 8,
  "target_share_pct": 18,
  "total_mentions_in_category": 44,
  "leaderboard": [
    { "name": "Competitor A", "mention_count": 18, "share_pct": 41, "is_target": false },
    { "name": "Competitor B", "mention_count": 10, "share_pct": 23, "is_target": false },
    { "name": "Acme Corp",    "mention_count": 8,  "share_pct": 18, "is_target": true  }
  ]
}

Validate agent.json

POST/api/v1/agent-json/validate

Validates a brand's agent.json file against the BEACON AI schema. Returns errors, warnings, and a completeness score. No credit deducted. API key optional.

bash

curl -X POST https://usebeacon.in/api/v1/agent-json/validate \
  -H "Content-Type: application/json" \
  -d '{
    "schema": "https://usebeacon.in/agent-schema/v1",
    "brand": "Acme Corp",
    "domain": "acmecorp.com",
    "description": "Project management for modern teams.",
    "category": "SaaS / Software",
    "use_cases": ["Task tracking", "Team collaboration"],
    "pricing_model": "Freemium"
  }'

json

{
  "valid": true,
  "score": 75,
  "errors": [],
  "warnings": [],
  "suggestions": [
    "Add \"target_audience\" to help AI match your brand to buyer queries",
    "Add \"key_features\" to differentiate from competitors in AI responses"
  ]
}

API Key Management

GET/api/v1/keysRequires session cookie (dashboard only)

Lists all active API keys for the authenticated user.

POST/api/v1/keys

Creates a new API key. The raw key is returned once — store it immediately.

DELETE/api/v1/keys/:id

Revokes a key immediately. Irreversible.

Errors & Limits

400

Bad Request

Missing required fields or invalid JSON body.

401

Unauthorized

Missing, invalid, or revoked API key.

402

Payment Required

No audit credits. Purchase at usebeacon.in/pricing.

429

Too Many Requests

An audit is already running for this account. Wait for it to complete.

500

Server Error

Audit failed (platform timeout, API outage). Safe to retry once.

Rate limits

Concurrent audits1 per account (wait for it to finish)

Key creation5 active keys per account

Report / history / categoryNo limit (no credit cost)

Validate requestsNo limit (no auth required)

BEACON AI API

Run AI visibility audits, validate agent.json files, and retrieve brand intelligence programmatically. All endpoints return JSON. Audits deduct 1 credit from your balance.

Base URL:https://usebeacon.in/api/v1

Authentication

All API requests require an API key passed as a Bearer token. Generate your key in Settings → API Keys.

bash

curl https://usebeacon.in/api/v1/audit \
  -H "Authorization: Bearer bk_live_your_key_here"

Keep your API key secret. Never expose it in client-side code. Rotate it immediately if compromised.

Run Audit

POST/api/v1/audit

Runs a full AI visibility audit across Claude, ChatGPT, Perplexity, and Gemini. Returns scores, insights, and share of voice. Takes 1–4 minutes. Deducts 1 credit.

Request body

brandName

stringrequired

The brand or company name to audit.

domain

stringrequired

Primary domain (no https://). E.g. acmecorp.com

industry

string

Industry/category hint. Improves query relevance. E.g. project management software

queries

string[]

Up to 5 custom queries to include alongside generated ones.

Example

bash

curl -X POST https://usebeacon.in/api/v1/audit \
  -H "Authorization: Bearer bk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "brandName": "Acme Corp",
    "domain": "acmecorp.com",
    "industry": "project management software"
  }'

python

import requests

response = requests.post(
    "https://usebeacon.in/api/v1/audit",
    headers={"Authorization": "Bearer bk_live_your_key_here"},
    json={
        "brandName": "Acme Corp",
        "domain": "acmecorp.com",
        "industry": "project management software",
    },
    timeout=60,
)
data = response.json()
print(f"AI Visibility Score: {data['aiVisibilityScore']}")

Response

json

{
  "ok": true,
  "brand": "Acme Corp",
  "domain": "acmecorp.com",
  "aiVisibilityScore": 42,
  "aeiq": {
    "overall": 42,
    "presence": 35,
    "authority": 58,
    "sentiment": 71,
    "consistency": 28,
    "topPick": 12
  },
  "platformScores": [
    { "platform": "chatgpt", "score": 55, "mentionCount": 8, "avgRank": 2.1 },
    { "platform": "claude",  "score": 38, "mentionCount": 5, "avgRank": 3.0 },
    { "platform": "gemini",  "score": 42, "mentionCount": 6, "avgRank": 2.5 },
    { "platform": "perplexity", "score": 31, "mentionCount": 4, "avgRank": 3.2 }
  ],
  "insights": [
    {
      "type": "opportunity",
      "priority": "high",
      "title": "Low AI Presence",
      "body": "Acme Corp appears in only 35% of AI queries..."
    }
  ],
  "queriesRun": 15,
  "mentionRate": 0.35
}

Get Report

GET/api/v1/report

Returns the most recent audit report for a domain. No credit deducted — reads from your audit history.

bash

curl "https://usebeacon.in/api/v1/report?domain=acmecorp.com" \
  -H "Authorization: Bearer bk_live_your_key_here"

json

{
  "id": "abc123",
  "brand_name": "Acme Corp",
  "domain": "acmecorp.com",
  "audited_at": "2026-10-14T07:00:00Z",
  "overall_score": 42,
  "mention_rate": 35,
  "platforms": [
    { "platform": "chatgpt", "score": 55, "mention_count": 8, "avg_rank": 2.1 },
    { "platform": "claude",  "score": 38, "mention_count": 5, "avg_rank": 3.0 }
  ],
  "share_of_voice": { "target_pct": 18, "total_mentions": 44, "competitors": [] },
  "top_insight": { "priority": "high", "title": "Low AI Presence", "body": "..." }
}

Audit History

GET/api/v1/audits

Lists all audits for your account, optionally filtered by domain. Returns scores and timestamps for charting visibility over time. No credit deducted.

domain

string

Filter to a specific domain. If omitted, returns all domains.

limit

integer

Max results (1–50, default 10).

bash

curl "https://usebeacon.in/api/v1/audits?domain=acmecorp.com&limit=10" \
  -H "Authorization: Bearer bk_live_your_key_here"

json

{
  "audits": [
    {
      "id": "abc123",
      "brand_name": "Acme Corp",
      "domain": "acmecorp.com",
      "audited_at": "2026-10-14T07:00:00Z",
      "overall_score": 42,
      "mention_rate": 35,
      "platforms": [
        { "platform": "chatgpt", "score": 55 },
        { "platform": "claude",  "score": 38 }
      ]
    }
  ],
  "total": 1
}

Category Intelligence

GET/api/v1/category

Returns your brand's category rank and the full AI Share of Voice leaderboard for your domain's category. No credit deducted.

bash

curl "https://usebeacon.in/api/v1/category?domain=acmecorp.com" \
  -H "Authorization: Bearer bk_live_your_key_here"

json

{
  "domain": "acmecorp.com",
  "brand_name": "Acme Corp",
  "audited_at": "2026-10-14T07:00:00Z",
  "category_rank": 3,
  "total_brands_tracked": 8,
  "target_share_pct": 18,
  "total_mentions_in_category": 44,
  "leaderboard": [
    { "name": "Competitor A", "mention_count": 18, "share_pct": 41, "is_target": false },
    { "name": "Competitor B", "mention_count": 10, "share_pct": 23, "is_target": false },
    { "name": "Acme Corp",    "mention_count": 8,  "share_pct": 18, "is_target": true  }
  ]
}

Validate agent.json

POST/api/v1/agent-json/validate

Validates a brand's agent.json file against the BEACON AI schema. Returns errors, warnings, and a completeness score. No credit deducted. API key optional.

bash

curl -X POST https://usebeacon.in/api/v1/agent-json/validate \
  -H "Content-Type: application/json" \
  -d '{
    "schema": "https://usebeacon.in/agent-schema/v1",
    "brand": "Acme Corp",
    "domain": "acmecorp.com",
    "description": "Project management for modern teams.",
    "category": "SaaS / Software",
    "use_cases": ["Task tracking", "Team collaboration"],
    "pricing_model": "Freemium"
  }'

json

{
  "valid": true,
  "score": 75,
  "errors": [],
  "warnings": [],
  "suggestions": [
    "Add \"target_audience\" to help AI match your brand to buyer queries",
    "Add \"key_features\" to differentiate from competitors in AI responses"
  ]
}

API Key Management

GET/api/v1/keysRequires session cookie (dashboard only)

Lists all active API keys for the authenticated user.

POST/api/v1/keys

Creates a new API key. The raw key is returned once — store it immediately.

DELETE/api/v1/keys/:id

Revokes a key immediately. Irreversible.

Errors & Limits

400

Bad Request

Missing required fields or invalid JSON body.

401

Unauthorized

Missing, invalid, or revoked API key.

402

Payment Required

No audit credits. Purchase at usebeacon.in/pricing.

429

Too Many Requests

An audit is already running for this account. Wait for it to complete.

500

Server Error

Audit failed (platform timeout, API outage). Safe to retry once.

Rate limits

Concurrent audits1 per account (wait for it to finish)

Key creation5 active keys per account

Report / history / categoryNo limit (no credit cost)

Validate requestsNo limit (no auth required)