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).
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"
{
"status": "active",
"authenticated": true,
"message": "Vaatify GEO Engine API is ready."
}Verifies API key validity and returns engine health status. Use this endpoint for readiness checks in your internal orchestrators.
Triggers an automated evaluation scan across specified target prompt queries and AI search engines. Returns real-time citations, rankings, and mention sentiment.
| Field | Type | Required | Description |
|---|---|---|---|
| prompt_ids | string[] | Optional | Array of query IDs to execute. If omitted, evaluates all active tracked queries. |
| engines | string[] | Optional | Engines 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"]}'{
"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
}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"
{
"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"
}
]
}Returns paginated historical evaluation records, including the synthesized answer text, cited URLs, and engine response timestamps.
Configure your tracked brand name, primary website domain, and named competitor domains for Share of Voice comparisons.
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 Code | Description |
|---|---|
| 200 OK | Request succeeded. Response body contains requested resource or execution results. |
| 401 Unauthorized | Missing or invalid x-api-key request header. |
| 422 Unprocessable | Validation error in JSON request payload. Check field types and required properties. |
| 500 Server Error | Internal engine error. Automated alerting notifies our engineering on-call. |