Developer

API Reference

Complete reference for the SEAES REST API. All endpoints require authentication via NextAuth session cookies unless otherwise noted.

Authentication

Session-based: Most endpoints require an authenticated NextAuth session. The session cookie is automatically included by the browser.

Cron Secret: Internal cron endpoints require Authorization: Bearer CRON_SECRET header.

Base URL: https://seaes-seo-platform.vercel.app

Example request:

fetch('/api/clients', {
  method: 'GET',
  credentials: 'include',  // includes session cookie
})
  .then(res => res.json())
  .then(data => console.log(data));

// Response: { success: true, data: [...] }

Clients

2 endpoints

GET/api/clientsList all clients for the authenticated userSession

POST/api/clientsCreate a new client (5-step onboarding data)Session

SEO Audits

2 endpoints

GET/api/auditsGet audit history for a clientSession

POST/api/auditsTrigger a new SEO audit for a clientSession

Rankings

1 endpoint

GET/api/rankingsGet keyword rankings for a clientSession

Recommendations

1 endpoint

GET/api/recommendationsGet AI-generated recommendations for a clientSession

Reports

1 endpoint

GET/api/reportsGet generated reports for a clientSession

Alerts

2 endpoints

GET/api/alertsGet alerts for a client (ranking drops, GEO changes, etc.)Session

PATCH/api/alertsMark alerts as readSession

GEO (Generative Engine Optimization)

6 endpoints

GET/api/geo/scoreGet GEO visibility score and historySession

GET/api/geo/mentionsGet AI platform mentions with filtersSession

GET/api/geo/citationsGet citation records from AI platformsSession

GET/api/geo/competitorsGet share of voice / competitor GEO dataSession

GET/api/geo/crawlersGet AI bot visit logs and statsSession

POST/api/geo/scanManually trigger a GEO scan for a clientSession

Automation

2 endpoints

GET/api/automation/configGet automation config for a clientSession

PUT/api/automation/configUpdate automation settings (schedules, toggles)Session

Content Optimization

1 endpoint

POST/api/content/optimizeGenerate AI-optimized meta tags and content suggestionsSession

Legal Documents

1 endpoint

GET/api/legalGenerate Privacy Policy and Terms of Service for a clientSession

Cron Jobs (Internal)

5 endpoints

GET/api/cron/daily-rankingsDaily ranking check + alert generation (6 AM UTC)Cron Secret

GET/api/cron/weekly-auditsWeekly SEO audit + auto-optimization (Mon 2 AM UTC)Cron Secret

GET/api/cron/weekly-geo-scanWeekly GEO visibility scan (Wed 3 AM UTC)Cron Secret

GET/api/cron/monthly-reportsMonthly report generation + email (1st 8 AM UTC)Cron Secret

GET/api/cron/competitor-scanWeekly competitor audit (Sun 4 AM UTC)Cron Secret

Rate Limits

API endpoints: 100 requests per minute per authenticated user

GEO scan trigger: 1 scan per client per hour

Audit trigger: 1 audit per client per 30 minutes

Content optimization: 10 requests per hour per client

Response Format

All API responses follow a consistent format:

// Success
{
  "success": true,
  "data": { ... }
}

// Error
{
  "success": false,
  "error": "Error message description"
}

// Paginated responses include:
{
  "success": true,
  "data": [...],
  "total": 42,
  "page": 1,
  "limit": 20
}