AI1stSEO — API Documentation

Overview

The AI1stSEO API provides programmatic access to our 236-point SEO audit engine, GEO visibility scanner, AEO optimizer, and content brief generator. Use it to automate audits, build integrations, or power your own dashboards.

Base URLs

Auth API:    https://api.ai1stseo.com
App Runner:  https://sgnmqxb2sw.us-east-1.awsapprunner.com

Authentication

Most endpoints require a Bearer token obtained from Cognito login. Include it in the Authorization header.

Authorization: Bearer eyJraWQiOiJ...

Public endpoints (analyze, collect-email, subscribe) do not require authentication.

Rate Limits

API requests are rate-limited per API key. Default limits:

Tier	Requests/min	Daily Limit
Free	10	100
Pro	60	5,000
Enterprise	300	50,000

POST Analyze URL

POST /api/analyze

Run a full 236-point SEO audit on any URL. Returns scores across 10 categories: technical, on-page, content, mobile, performance, security, social, local, GEO, and citation gap.

Request Body

Parameter	Type	Required	Description
url	string	Required	Full URL to analyze (include https://)
categories	string	Optional	Comma-separated category list. Default: all 10

Example Response

{
  "url": "https://example.com",
  "overall_score": 72,
  "categories": {
    "technical": { "score": 85, "passed": 17, "total": 20 },
    "onpage": { "score": 68, "passed": 19, "total": 28 }
  },
  "checks": [ ... ]
}

⚡ Try It

GET Audit Results

GET /api/admin/audit-history?url={url}&limit=50 🔒 Auth Required

Retrieve historical audit results with optional filters.

Parameter	Type	Required	Description
url	string	Optional	Filter by URL (partial match)
min_score	integer	Optional	Minimum score filter (0-100)
max_score	integer	Optional	Maximum score filter (0-100)
limit	integer	Optional	Max results (default 50)

POST Content Brief

POST /api/content-brief 🔒 Auth Required

Generate an AI-powered content brief with SERP analysis, keyword clustering, heading structure, and AI citation signals.

Parameter	Type	Required	Description
url	string	Required	Target URL for brief generation
keyword	string	Optional	Primary keyword to target
content_type	string	Optional	blog_post, landing_page, product_page, faq

POST GEO Probe

POST /api/geo-probe/scan 🔒 Auth Required

Scan how AI models (ChatGPT, Gemini, Claude, Perplexity) reference your brand. Returns citation frequency and visibility scores.

Parameter	Type	Required	Description
brand	string	Required	Brand name to scan
url	string	Optional	Brand website URL
queries	array	Optional	Custom queries to test

GET AI Visibility

GET /api/ai/visibility?brand={brand} 🔒 Auth Required

Get AI visibility scores across ChatGPT, Gemini, Claude, Perplexity, and Copilot.

POST Collect Email

POST /api/collect-email

Collect email from PDF download gate. No auth required.

Parameter	Type	Required	Description
email	string	Required	User email address
url	string	Optional	Audited URL
score	integer	Optional	Audit score

POST Subscribe

POST /api/growth/subscribe

Subscribe to the AI visibility newsletter. No auth required.

Parameter	Type	Required	Description
email	string	Required	Subscriber email
source	string	Optional	Signup source (e.g. website_main)

GET Admin Overview

GET /api/admin/overview 🔒 Auth Required

Dashboard overview with user counts, scan totals, error counts, and monitoring stats.

GET Users

GET /api/admin/users?limit=25&offset=0 🔒 Auth Required

List registered users with scan counts, roles, and last login timestamps.

GET System Status

GET /api/admin/system-status 🔒 Auth Required

Real-time health check of DynamoDB, Cognito, SES, and S3 with latency in milliseconds.