AI 1st SEO Developer API

Integrate SEO analysis, GEO visibility, backlink intelligence, and AI citation data into your applications.

Base URL: https://api.ai1stseo.com
Auth: Authorization: Bearer ai1st_YOUR_KEY or X-API-Key: ai1st_YOUR_KEY
Format: JSON request/response. All responses include "status": "success" or "status": "error".

Authentication

All API endpoints require either a Cognito JWT token (from login) or a developer API key. API keys are prefixed with ai1st_ and support scoped access (read, write, admin).

Get an API Key

POST /api/keys

{ "label": "My Integration", "scopes": ["read", "write"], "rate_limit_per_hour": 100 }

Rate Limits

Default

100 requests/hour per key

Custom

Set per key at creation (up to 1000/hr)

Burst

10 requests/second max

SEO Analysis

POST /api/analyze auth

Run 200+ SEO checks across 10 categories. Returns scores, passed/failed checks, and recommendations.

Request:  { "url": "https://example.com" }
Response: { "status": "success", "overallScore": 75, "categories": {...}, "checks": [...] }

POST /api/content-score auth

Score a URL for readability (Flesch), SEO (on-page), and AEO (AI-extractable content).

POST /api/content-brief auth

Generate an AI content brief for a target keyword with SERP analysis.

GET /api/health public

Service health check. Returns available categories and check counts.

GEO / AI Citation Probing

POST /api/geo-probe auth

Probe an AI model (ChatGPT, Gemini, Perplexity) to check if it cites a brand for a keyword.

Request:  { "keyword": "best seo tools", "ai_model": "chatgpt", "url": "https://example.com", "brand_name": "Example" }
Response: { "status": "success", "probe": { "cited": true, "position": 3, ... } }

POST /api/geo-probe/batch auth

Probe multiple AI models simultaneously for the same keyword.

GET /api/geo-probe/models public

List available AI models for probing.

GET /api/geo-probe/history auth

Get probe history. Filter by keyword, model, date range.

POST /api/aeo/analyze auth

Run Answer Engine Optimization analysis on a URL.

Backlink Intelligence

POST /api/backlinks/score auth

Score a domain's authority (0-100) using 10+ real-time signals.

Request:  { "domain": "example.com" }
Response: { "status": "success", "da_score": 72, "signals": { "https": true, "response_time_ms": 340, ... } }

POST /api/backlinks/analyze-toxic auth

Classify backlinks as potentially toxic using heuristic signals.

POST /api/backlinks/link-gap auth

Compare your domain against competitors to find backlink gaps.

POST /api/backlinks/citation-authority auth

Probe AI models to discover which domains they cite for a topic. No competitor offers this.

POST /api/backlinks/broken-links auth

Scan a page for broken outbound links — reclaim opportunities.

POST /api/backlinks/wikipedia-gaps auth

Find dead citations in Wikipedia articles as replacement opportunities.

POST /api/backlinks/competitor-alerts auth

Detect when a competitor gains or loses significant domain authority.

GET /api/backlinks/priority-queue auth

Unified opportunity queue ranked by composite priority score.

POST /api/backlinks/report/download auth

Generate a white-label HTML report with presigned S3 download URL.

Data API

Method	Endpoint	Description
POST	`/api/data/audits`	Store an audit result
GET	`/api/data/audits`	List audits (filter by URL)
POST	`/api/data/geo-probes`	Store a GEO probe result
GET	`/api/data/geo-probes`	List GEO probes
POST	`/api/data/content-briefs`	Store a content brief
GET	`/api/data/content-briefs`	List content briefs
POST	`/api/data/competitors`	Add a tracked competitor
GET	`/api/data/competitors`	List tracked competitors
POST	`/api/data/reports`	Store a report
GET	`/api/data/reports`	List reports

Webhooks & Notifications

POST /api/webhooks auth

{ "url": "https://your-server.com/hook", "events": ["audit.created", "*"], "secret": "your-hmac-secret" }

POST /api/notifications/subscribe auth

Subscribe to events via Slack webhook or email.

{ "channel": "slack", "target": "https://hooks.slack.com/services/...", "events": ["*"] }

GET /api/webhooks/events public

List all available event types.

Public Endpoints (No Auth)

Method	Endpoint	Description
POST	`/api/contact`	Contact form (sends via SES)
POST	`/api/invest`	Investor inquiry form
POST	`/api/collect-email`	Email lead collection
POST	`/api/content-freshness`	Record content update timestamp
GET	`/api/content-freshness`	Get freshness history

Error Handling

All errors return JSON with "status": "error" and a "message" field.

Code	Meaning
400	Bad request — missing or invalid parameters
401	Unauthorized — missing or expired token/key
403	Forbidden — insufficient role (admin required)
404	Not found — resource or endpoint doesn't exist
429	Rate limited — exceeded requests per hour
500	Server error — check the message field