Public API

Every request needs a bearer token in the Authorization header.

Authorization: Bearer ngn_xxxxxxxxxxxx

API keys can only be generated by platform administrators at /settings/api-keys. The full key is shown once at creation, store it securely. Revoked keys are rejected immediately.

Each key has scopes: audits:read for GET endpoints, audits:trigger for POST trigger.

Returns the most recent audit owned by the authenticated user for a given URL or hostname. Match order: exact url, then final_url, then hostname. Strictly scoped to the calling key’s user, audits owned by other users are never returned.

Query params: url (preferred) or hostname.

curl -H "Authorization: Bearer ngn_xxxxxxxxxxxx" \
  "https://seo.nxtgencreative.io/api/public/audits/latest?url=https://example.com"

Response 200:

{
  "audit_id": "...",
  "user_id": "...",
  "url": "https://example.com",
  "final_url": "https://example.com/",
  "hostname": "example.com",
  "overall_score": 78,
  "has_ai": true,
  "created_at": "2026-05-25T12:34:56Z",
  "share_url": "https://seo.nxtgencreative.io/share/<token>",
  "categories": [
    { "name": "Meta & Indexability", "weight": 18, "score": 85, "issues": [...] }
  ],
  "fix_first": [...],
  "ai_insights": {...} | null,
  "performance": { "lcp": 2.4, "cls": 0.08, "inp": 180, "ttfb": 0.6, "fcp": 1.2, "mobile_score": 82, "desktop_score": 91 }
}

404 if no audit found, 401 if key invalid.

Triggers a new audit. Returns immediately with a job_id; poll the status URL to track progress.

Body: { "url": "...", "use_credit": false }

curl -X POST \
  -H "Authorization: Bearer ngn_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com","use_credit":false}' \
  "https://seo.nxtgencreative.io/api/public/audits"

Response 202:

{
  "job_id": "...",
  "status": "pending",
  "status_url": "https://seo.nxtgencreative.io/api/public/audits/jobs/<job_id>",
  "created_at": "..."
}

402 if use_credit=true and balance is zero. 429 if free monthly quota or daily API cap exceeded.

Poll for job status. audit_url is set when the job completes, pointing back to /api/public/audits/latest for that URL.

curl -H "Authorization: Bearer ngn_xxxxxxxxxxxx" \
  "https://seo.nxtgencreative.io/api/public/audits/jobs/<job_id>"

Response 200:

{
  "job_id": "...",
  "status": "pending" | "running" | "completed" | "failed" | "cancelled",
  "progress": 0,
  "current_url": "...",
  "audit_id": "..." | null,
  "audit_url": "https://seo.nxtgencreative.io/api/public/audits/latest?url=..." | null,
  "error": null,
  "created_at": "...",
  "started_at": "..." | null,
  "finished_at": "..." | null
}

Per-minute: 60 requests/minute per key on GET endpoints, 10/minute on POST trigger. On 429, see the Retry-After header.

Daily cap: 50 POST audits per user per rolling 24h window, counted across all keys owned by the same user. Applies to all users, including administrators. Exceeding it returns:

{
  "error": "Daily audit limit exceeded",
  "limit": 50,
  "reset_at": "2026-05-28T12:00:00.000Z"
}

Every response includes X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset (unix seconds) for the per-minute window.

POST audits consume real resources: PageSpeed Insights calls, Firecrawl crawl credits, and Lovable AI Gateway tokens for AI insights. With use_credit=true the audit deducts a Premium credit from the calling user’s balance. Without use_credit, free-tier users count against the monthly free quota (5/30d) and Premium/Pro/Agency users have no per-audit charge. The daily 50/24h cap above applies on top of either path as a circuit breaker.

Critical security findings are visible only to the audit owner in the UI. The API applies the same redaction: any finding with severity: "critical" has its detail, fix, and evidence replaced with a placeholder message. This protects sensitive site details from being exfiltrated through third-party integrations.

POST to trigger an audit, poll status_url every 5-10s until status=completed, then GET audit_url (or call /audits/latest directly) for the full audit data.