Developer Resources

Authority Engine™ API

RESTful API for building AI authority automation, integrations, and custom workflows. Production-ready with authentication, rate limiting, and comprehensive error handling.

REST

JSON API

OAuth

Clerk Auth

Webhooks

Real-time

Zapier

No-code

Quick Start

Base URL

https://api.authorityengine.ai/v1

Authentication

Authorization: Bearer YOUR_API_KEY

Example Request

curl -X POST https://api.authorityengine.ai/v1/audit/run \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "businessId": "biz_123",
    "fullAudit": true
  }'

Authentication

Authority Engine™ uses API keys for authentication. All requests must include your API key in the Authorization header using Bearer authentication.

Role-Based Access Control

ADMIN Full access to all endpoints, user management, billing

OWNER Manage businesses, run audits, configure integrations

MANAGER Edit content, run campaigns, view reports

CONTRIBUTOR Create assets, submit for review

VIEWER Read-only access to reports and dashboards

Get Your API Key: Navigate to Settings → Integration Hub → API Keys to generate your key.

Core Endpoints

POST /audit/run

Trigger a full authority audit

Async

Request Body

{
  "businessId": "biz_123",
  "fullAudit": true,
  "modules": ["visibility", "trust", "performance", "growth"]
}

Response (202 Accepted)

{
  "success": true,
  "data": {
    "auditId": "audit_456",
    "status": "processing",
    "estimatedCompletion": "2026-02-11T15:45:00Z"
  },
  "metadata": {
    "queuePosition": 3,
    "requestId": "req_789"
  }
}

Parameters

businessId (required) - Business identifier

fullAudit (optional) - Run complete audit

modules (optional) - Specific pillars to audit

Required Permissions

OWNER MANAGER

GET /audit/:auditId

Retrieve audit results and scores

Response (200 OK)

{
  "success": true,
  "data": {
    "auditId": "audit_456",
    "businessId": "biz_123",
    "status": "completed",
    "completedAt": "2026-02-11T15:43:22Z",
    "scores": {
      "overall": 84,
      "visibility": 88,
      "trust": 82,
      "performance": 79,
      "growth": 87
    },
    "issues": [
      {
        "id": "issue_1",
        "type": "schema_missing",
        "severity": "high",
        "pillar": "trust",
        "title": "Missing LocalBusiness Schema",
        "description": "Homepage missing structured data",
        "impact": 8,
        "effort": 30,
        "recommendation": "Add JSON-LD schema markup..."
      }
    ],
    "aiModels": {
      "chatgpt": { "visible": true, "ranking": 2 },
      "gemini": { "visible": true, "ranking": 1 },
      "claude": { "visible": true, "ranking": 3 }
    }
  }
}

POST /shadow-test

Run multi-LLM shadow testing

Real-time

Request Body

{
  "businessId": "biz_123",
  "prompts": [
    "best plumber in Seattle",
    "top-rated HVAC company Seattle"
  ],
  "models": ["chatgpt", "gemini", "claude", "perplexity"]
}

Response (200 OK)

{
  "success": true,
  "data": {
    "testId": "test_789",
    "results": {
      "chatgpt": {
        "mentioned": true,
        "ranking": 2,
        "context": "...ABC Plumbing is highly rated...",
        "sentiment": "positive",
        "hallucinations": []
      },
      "gemini": {
        "mentioned": true,
        "ranking": 1,
        "context": "...Top choice: ABC Plumbing...",
        "sentiment": "positive",
        "hallucinations": []
      }
    },
    "coverage": 0.75,
    "averageRanking": 1.5
  }
}

Entity & Data Endpoints

GET /entities

List all entities for a business

Query: businessId, type, page, limit

Returns: Entity list with pagination

POST /entities

Create a new entity

Body: type, name, canonicalData

Returns: Created entity with ID

PUT /entities/:id

Update entity (creates version)

Body: canonicalData updates

Returns: Updated entity

DELETE /entities/:id

Delete an entity

Params: Entity ID

Returns: Deletion confirmation

GET /entities/:id/drift

Detect entity drift across web

{
  "driftScore": 12,
  "inconsistencies": [
    {
      "field": "phone",
      "canonical": "+1-206-555-0100",
      "found": "+1-206-555-0199",
      "source": "yelp.com"
    }
  ]
}

GET /entities/:id/schema

Generate schema markup preview

{
  "schemaType": "LocalBusiness",
  "jsonLd": {
    "@context": "https://schema.org",
    "@type": "LocalBusiness",
    "name": "ABC Plumbing"
  }
}

Citation Endpoints

GET /citations

List citations with filtering by business, status, value score

POST /citations

Add a new citation manually or import from scan

GET /citations/opportunities

Find potential citation opportunities based on industry

Competitor Endpoints

GET /competitors

List tracked competitors

GET /competitors/:id/compare

Authority comparison & gap analysis

Asset Endpoints

GET /assets

List assets with workflow status

POST /assets/:id/transition

Move asset through workflow stages

Scoring Engine Models

Authority Engine™ uses weighted scoring models to compute pillar and overall authority scores. All inputs are normalized to a 0–100 scale.

Overall Authority Score Formula

Overall Authority Score = 0.3 × Visibility + 0.3 × Trust + 0.2 × Performance + 0.2 × Growth

30%

Visibility Weight

30%

Trust Weight

20%

Performance Weight

20%

Growth Weight

Example: If Visibility = 88, Trust = 82, Performance = 79, Growth = 87, then:

Overall = (0.3 × 88) + (0.3 × 82) + (0.2 × 79) + (0.2 × 87) =
            84.2

Visibility Score

Visibility =
  0.4 × Model Coverage +
  0.4 × Ranking Position +
  0.2 × Query Breadth

Model Coverage:

% of AI models where business appears for key queries

7/8 models = 87.5

Ranking Position:

Average ranking across models (normalized inverse)

Avg rank 2 = 100 - (rank × 10)

Query Breadth:

Number of distinct relevant queries triggering mentions

15/20 queries = 75

Trust Score

Trust =
  0.3 × NAP Consistency +
  0.3 × Schema Quality +
  0.25 × Citation Health +
  0.15 × Author Authority

NAP Consistency:

Alignment of Name, Address, Phone across sources

95% match = 95

Schema Quality:

Presence, correctness, completeness of structured data

80% complete = 80

Citation Health:

Volume, value, recency of citations

247 citations, avg value 85 = 85

Performance Score

Performance =
  0.4 × (100 - Risk) +
  0.4 × Velocity +
  0.2 × Stability

Risk (inverted):

Severity & quantity of issues (inverted for scoring)

Risk 15 → Score 85

Velocity:

Slope of authority score over time (momentum)

+6 points/week = 75

Stability:

Volatility of authority signals (inverse variance)

Low volatility = 90

Growth Score

Growth =
  0.4 × Assets +
  0.3 × Outreach +
  0.3 × Integrations

Assets:

Quantity & quality of authority-building content

89 published assets = 85

Outreach:

Campaign activity & response rates

12 campaigns, 40% response = 80

Integrations:

Connected systems & automation depth

5 active integrations = 90

Scoring Model Versioning

The scoring engine stores both raw inputs and computed outputs for transparency. Scoring logic is versioned, allowing formulas to evolve without breaking historical audits. Each audit includes a scoringVersion field.

Current Version: v2.1.0
Released: 2026-01-15

Webhooks & Integrations

Webhooks

Receive real-time notifications when events occur in your Authority Engine account.

audit.completed

Triggered when an audit finishes processing

issue.detected

Triggered when a high-severity issue is found

visibility.changed

Triggered when AI model visibility changes

asset.published

Triggered when an asset moves to published

Example Webhook Payload:

{
  "event": "audit.completed",
  "timestamp": "2026-02-11T15:43:22Z",
  "data": {
    "auditId": "audit_456",
    "businessId": "biz_123",
    "overallScore": 84,
    "changes": {
      "visibility": +5,
      "trust": +3
    }
  }
}

Zapier Integration

Connect Authority Engine to 5,000+ apps with no-code automation.

Triggers

New Audit Completed, Issue Detected, Score Changed, Asset Published

Actions

Run Audit, Create Asset, Update Entity, Create Citation

Popular Zaps:

• Audit completed → Slack notification
• Issue detected → Create Asana task
• Asset published → Add to Google Sheets
• Score increased → Send email via Gmail

Rate Limits

Starter Plan: 100 req/hour

Professional Plan: 1,000 req/hour

Enterprise Plan: Custom limits

Rate limit headers included in all responses:
X-RateLimit-Limit
X-RateLimit-Remaining
X-RateLimit-Reset

Error Responses

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid businessId format",
    "field": "businessId",
    "details": "Must be prefixed with 'biz_'"
  },
  "metadata": {
    "requestId": "req_789",
    "timestamp": "2026-02-11T15:43:22Z"
  }
}

400 - Bad Request (validation error)

401 - Unauthorized (invalid API key)

403 - Forbidden (insufficient permissions)

404 - Not Found

429 - Rate Limit Exceeded

500 - Internal Server Error

SDKs & Client Libraries

JavaScript/Node

npm install @authorityengine/sdk

Python

pip install authorityengine

PHP

composer require authorityengine/sdk

Ruby

gem install authorityengine