Home/API Documentation

Vaatify GEO API Reference

Programmatically trigger multi-engine search evaluations, retrieve deterministic Share of Voice metrics, and monitor citation flips.

Overview & Base URL

The Vaatify GEO Engine provides predictable, deterministic REST APIs for evaluating brand citations across major AI search providers (OpenAI ChatGPT Search, Google AI Overviews, Perplexity Sonar, Anthropic Claude, and Google Gemini).

Production Base URL: https://vaatify-geo-engine.fly.dev
HTTPS Only

Authentication

All protected endpoints require an API key passed in the x-api-key HTTP request header. Your API key can be provisioned in your workspace settings.

curl -X GET "https://vaatify-geo-engine.fly.dev/api/v1/status" \
  -H "x-api-key: geo_your_api_key_here"
Response 200 OKapplication/json
{
  "status": "active",
  "authenticated": true,
  "message": "Vaatify GEO Engine API is ready."
}
GET/api/v1/status
Status Check

Verifies API key validity and returns engine health status. Use this endpoint for readiness checks in your internal orchestrators.

POST/api/v1/pipeline/run
Execute Audit

Triggers an automated evaluation scan across specified target prompt queries and AI search engines. Returns real-time citations, rankings, and mention sentiment.

FieldTypeRequiredDescription
prompt_idsstring[]OptionalArray of query IDs to execute. If omitted, evaluates all active tracked queries.
enginesstring[]OptionalEngines to query: "chatgpt", "perplexity", "google_ai", "claude".
curl -X POST "https://vaatify-geo-engine.fly.dev/api/v1/pipeline/run" \
  -H "x-api-key: geo_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"engines": ["chatgpt", "perplexity", "google_ai"]}'
Response 200 OKapplication/json
{
  "status": "completed",
  "run_id": "run_9824f1ac",
  "evaluated_queries": 15,
  "engines_scanned": ["chatgpt", "perplexity", "google_ai"],
  "brand_cited_count": 12,
  "share_of_voice": 0.80,
  "competitor_flips_detected": 0
}
GET/api/v1/metrics/overview
Analytics

Calculates aggregate Share of Voice (SoV), overall citation volume, competitor displacement flips, and average recommendation rank depth.

curl -X GET "https://vaatify-geo-engine.fly.dev/api/v1/metrics/overview" \
  -H "x-api-key: geo_your_api_key_here"
Response 200 OKapplication/json
{
  "overall_sov": 0.648,
  "total_runs": 1248,
  "brand_citations": 809,
  "competitor_citations": 439,
  "recent_flips": [
    {
      "prompt": "best crm for sales automation",
      "engine": "chatgpt",
      "previous_winner": "yourcompany.com",
      "new_winner": "competitoralpha.com",
      "detected_at": "2026-10-24T08:30:00Z"
    }
  ]
}
GET/api/v1/runs
Historical Audits

Returns paginated historical evaluation records, including the synthesized answer text, cited URLs, and engine response timestamps.

GET & POST/api/v1/profile
Workspace Settings

Configure your tracked brand name, primary website domain, and named competitor domains for Share of Voice comparisons.

POST/api/v1/agent/chat
AI Copilot

Send prompts to the Vaatify GEO Copilot to diagnose why specific buyer queries omit your brand and generate targeted content optimization recommendations.

HTTP Status Codes & Errors

Standard HTTP response codes indicate whether an API request succeeded or failed.

Status CodeDescription
200 OKRequest succeeded. Response body contains requested resource or execution results.
401 UnauthorizedMissing or invalid x-api-key request header.
422 UnprocessableValidation error in JSON request payload. Check field types and required properties.
500 Server ErrorInternal engine error. Automated alerting notifies our engineering on-call.