Developer Docs

API Reference

Integrate Aeranko into your workflow. Run audits, track keywords, and monitor AI search visibility programmatically.

Getting started

All authenticated endpoints require a Bearer token in the Authorization header. Get your token from Dashboard → Settings → API.

curl https://aeranko.com/api/visibility/summary \
  -H "Authorization: Bearer YOUR_API_TOKEN"

API access is available on the Growth plan and above. The base URL for all endpoints is https://aeranko.com.

POST/api/auditAuth optional

Run an AI visibility audit for any domain. Returns an overall score, per-factor breakdown, platform-level scores, keyword results, competitor benchmarks, and actionable recommendations.

Anonymous audits are allowed. Authenticated audits are stored to your account for historical tracking.

Request body

{
  "url": "https://example.com",
  "email": "user@example.com",
  "keywords": ["project management", "task tracking"],
  "industry": "B2B SaaS"
}

Response

{
  "domain": "example.com",
  "overallScore": 64,
  "factorScores": {
    "contentStructure": 72,
    "schemaMarkup": 45,
    "topicalAuthority": 68,
    "citationSignals": 55
  },
  "visibility": {
    "platformScores": {
      "chatgpt": 58,
      "perplexity": 71,
      "gemini": 63,
      "aiOverviews": 49
    },
    "keywordResults": [ ... ],
    "competitorBenchmark": [ ... ],
    "recommendations": [ ... ]
  }
}

GET/api/dashboard/statsAuth required

Retrieve aggregated dashboard statistics including visibility score, total audits, AI mentions, citation frequency, recent audits, score trend, and platform status.

Response

{
  "metrics": {
    "visibilityScore": 64,
    "totalAudits": 12,
    "aiMentions": 87,
    "citationFrequency": 0.34
  },
  "recentAudits": [ ... ],
  "scoreTrend": [ ... ],
  "platformStatus": {
    "chatgpt": "active",
    "perplexity": "active",
    "gemini": "active"
  }
}

GET/api/visibility/summaryAuth required

Get a comprehensive visibility summary for your tracked domain, including per-platform scores, keyword rankings, competitor comparison, and recommendations.

Response

{
  "data": {
    "domain": "example.com",
    "score": 64,
    "factorScores": { ... },
    "platforms": { ... },
    "keywords": [ ... ],
    "recommendations": [ ... ],
    "competitors": [ ... ],
    "scoreTrend": [ ... ]
  }
}

POST/api/visibility/runAuth required

Trigger a full visibility tracking run. Returns the complete audit result with platform scores, keyword rankings, and tailored recommendations.

Response

{
  "domain": "example.com",
  "overallScore": 64,
  "platformScores": { ... },
  "keywords": [ ... ],
  "recommendations": [ ... ]
}

GET/api/keywordsAuth required

List all tracked keywords for your account with the latest score and per-platform position data.

Response

{
  "data": [
    {
      "id": "kw_abc123",
      "keyword": "project management software",
      "latest_score": 72,
      "chatgpt_position": 3,
      "perplexity_position": 1,
      "gemini_position": 5,
      "ai_overviews_position": null
    }
  ]
}

POST/api/keywordsAuth required

Add one or more keywords to track. You can send a single keyword string or an array of keywords.

Request body

// Multiple keywords
{
  "keywords": ["project management", "task tracking", "team collaboration"]
}

// Single keyword
{
  "keyword": "project management"
}

Response

{
  "added": 3,
  "keywords": [
    "project management",
    "task tracking",
    "team collaboration"
  ]
}

GET/api/healthPublic

Public health check endpoint. Returns the status of the application and connectivity to upstream AI providers.

Response

{
  "status": "ok",
  "checks": {
    "app": "ok",
    "openai": "ok",
    "perplexity": "ok",
    "gemini": "ok",
    "serpapi": "ok"
  }
}

Rate limits

API access is available on Growth and Dominator plans. Requests are rate-limited per account — contact support if you need higher limits. If you exceed the limit you will receive a 429 response. Contact us if you need higher limits.

Error codes

Code	Meaning
200	Success
400	Bad request — check your request body
401	Unauthorized — missing or invalid Bearer token
403	Forbidden — your plan does not include API access
429	Rate limit exceeded
500	Internal server error