Run GEO scans from your workflow.
Create an API key from your dashboard, send a scan request and receive the same evidence-first GEO result as the web app.
Authentication
Send your key as a Bearer token. Keys are shown only once and can be revoked from the dashboard.
Authorization: Bearer gc_live_...
Run a scan
POST /api/v1/scans accepts url and optional mode (lite or full). A fast one-page scan returns 201 with data. A deeper paid full scan returns 202 with job.id; poll GET /api/v1/scans?jobId=... until job.status is completed.
Send a unique Idempotency-Key when a client may retry after a timeout. The same key and request replay the original response for 24 hours; reusing it with another URL or mode returns 409.
curl -X POST https://geoupp.com/api/v1/scans -H "Authorization: Bearer gc_live_..." -H "Idempotency-Key: project-audit-2026-08-15" -H "Content-Type: application/json" -d '{"url":"https://example.com","mode":"full"}'Progress contract
Queued full scans expose job.progress and job.stage. Poll using the returned pollAfter value and render the stage as user-facing progress. The scanner has a total 120-second budget; if it is reached, a partial result is returned with a scan-time-budget finding and an explicit limitation.
stage typical progress queued 0% starting 5% fetching 12% robots 16% sitemaps 22% guidance 28% crawling 28–83% analyzing 88% saving 92% completed 100%
Live benchmark jobs
Premium and Plus accounts can send POST /api/benchmark. Prompt sets are queued and return 202 with a benchmark job.id and Retry-After: 5; poll GET /api/benchmark?jobId=... until the response includes run. Provider calls run in the worker, or in the protected in-process fallback when no database worker is configured. With PostgreSQL, a missing or stale worker returns 503 with Retry-After: 30 instead of creating a job that could remain queued. To stop an unnecessary job, call DELETE /api/benchmark?jobId=....
Recurring GEO jobs
Premium and Plus accounts can schedule a daily or weekly AI benchmark or GEO readiness scan with POST /api/schedules. Send kind=benchmark or kind=scan; scan jobs use the normal full-scan quota and worker queue. GET lists the owned schedule and DELETE disables it. Responses expose lastStatus and a safe lastError when a run is paused, skipped or failed.
curl -X POST https://geoupp.com/api/schedules -H "Cookie: ..." -H "Content-Type: application/json" -d '{"origin":"https://example.com","kind":"scan","frequency":"weekly"}'Read and cancel jobs
GET /api/v1/scans lists your latest scans. Add ?origin=https://example.com to retrieve the latest result for one site. Use ?jobId=... to poll an asynchronous scan and wait at least 10 seconds between checks while it is queued or running. If a long scan is no longer needed, call DELETE /api/v1/scans?jobId=...; cancellation fences the worker and releases the reserved quota, slot and one-time scan credit. Every authenticated response includes X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset; queued responses include Retry-After. Rate limits are 5, 20 or 60 requests per minute for Free, Premium and Plus, with a maximum of 2 simultaneous scans per account. Limit errors return 429 and Retry-After.
curl https://geoupp.com/api/v1/scans?jobId=JOB_ID -H "Authorization: Bearer gc_live_..."
Authentication errors & abuse protection
Requests without a valid API key return 401 and expose X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset. Invalid or missing-key requests are limited to 10 attempts per minute per client address when the deployment trusts its reverse proxy; otherwise a conservative deployment-wide bucket is used. Exceeding that limit returns 429 with Retry-After. This protection is separate from scan credits and account quotas.
Save an anonymous report
After a GEO Lite scan, the web report can be imported into the signed-in account with POST /api/scan/import. The request must include the report origin and one-time browser-bound token from the report URL. Importing a cached report does not consume a new scan credit; repeating the same import is idempotent for that account.
Premium intelligence
GET /api/premium/insights?origin=https://example.com is available to Premium and Plus accounts. It returns benchmark monitoring, citation gaps, crawler analytics, the latest readiness trend and pageOpportunities — URL-level priorities derived from measured scan findings. These are site-readiness measurements, not search-ranking or guaranteed AI-visibility predictions.
curl "https://geoupp.com/api/premium/insights?origin=https%3A%2F%2Fexample.com" -H "Authorization: Bearer gc_live_..."
CI/CD GEO quality gate
Premium and Plus accounts can call GET /api/v1/quality-gate?origin=https://example.com&minScore=70&maxCritical=0. It returns 200 when the latest authenticated scan meets both thresholds, or 422 when it fails. This gate measures site readiness only; it does not claim live AI visibility.
curl -i "https://geoupp.com/api/v1/quality-gate?origin=https%3A%2F%2Fexample.com&minScore=70&maxCritical=0" -H "Authorization: Bearer gc_live_..."