Build with the AI1stSEO API.

Quick start

Get up and running in 60 seconds. Replace YOUR_API_KEY with the key you generated in Account → API.

# Run a free 236-point audit
curl -X POST "https://api.ai1stseo.com/v1/audits" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "categories": ["technical", "aeo", "geo", "content"]
  }'

The response includes the full audit report, an overall score (0-100), and category subscores.

Authentication

All requests require an API key passed via the Authorization header as a bearer token.

Authorization: Bearer YOUR_API_KEY

Keys are scoped to your workspace and inherit your plan's permissions. Rotate any time from Account → API.

Rate limits

Limits depend on your plan tier:

Rate limit headers are returned on every response: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset.

Errors

The API uses standard HTTP status codes. Error responses follow this shape:

{
  "error": {
    "code": "invalid_url",
    "message": "The provided URL is not reachable",
    "request_id": "req_a1b2c3d4"
  }
}

Endpoints overview

The API is organized around five resources. All requests are made to https://api.ai1stseo.com/v1.

Audits

Create a new 236-point audit for a URL. Returns the audit ID immediately and processes asynchronously.

Parameters

Retrieve a completed audit. Returns scores, findings, and a prioritized fix list.

GEO Scans

Run live citation scans across ChatGPT, Gemini, Claude, and Perplexity. Returns per-engine scores.

Parameters

AEO Schema

Generate FAQ, HowTo, Article, Product, or Review schema from a URL or HTML payload.

AI Orchestrator

Run a 5-agent consensus scan ($5 per scan, included on Pro+). Returns ranked action items.

Sites

List all sites in your workspace. Supports pagination and filtering by score.

Webhooks setup

Configure webhook URLs in Account → API → Webhooks. Each event is signed with HMAC-SHA256.

// Verify signature in Node.js
const crypto = require('crypto');
const sig = req.headers['x-ai1stseo-signature'];
const hmac = crypto.createHmac('sha256', WEBHOOK_SECRET)
  .update(JSON.stringify(req.body))
  .digest('hex');
if (sig !== hmac) throw new Error('Invalid signature');

Webhook events

• audit.completed — fired when a 236-point audit finishes
• geo.scan.completed — fired when a GEO scan finishes
• council.scan.completed — fired when an AI Orchestrator scan finishes
• citation.detected — fired when a new citation is detected
• citation.lost — fired when an existing citation drops
• score.threshold — fired when a site crosses a score threshold

Available SDKs

Official SDKs (open source on GitHub):

• Node.js — npm install @ai1stseo/node
• Python — pip install ai1stseo
• Go — go get github.com/ai1stseo/go-sdk

Community SDKs (Ruby, PHP, Rust) on the roadmap — vote on GitHub.