API Endpoint Reference
Complete reference for all available Surva.ai API endpoints. All endpoints require authentication via API key.
Keywords Endpoints
List Keywords
GET /v1/keywords
Returns all tracked keywords for your account.
Parameters:
- page (optional) - Page number
- per_page (optional) - Results per page
- sort (optional) - Sort field (volume, cpc, position, trend)
- order (optional) - Sort order (asc, desc)
Get Keyword
GET /v1/keywords/{keyword_id}
Returns detailed data for a specific keyword.
Add Keyword
POST /v1/keywords
Add a new keyword to track.
Body:
{
"keyword": "your keyword phrase"
}
Delete Keyword
DELETE /v1/keywords/{keyword_id}
Remove a keyword from tracking.
Get Keyword Rankings
GET /v1/keywords/{keyword_id}/rankings
Returns ranking history for a keyword.
Parameters:
- start_date (optional) - Start of date range
- end_date (optional) - End of date range
Competitors Endpoints
List Competitors
GET /v1/competitors
Returns all tracked competitors.
Get Competitor
GET /v1/competitors/{competitor_id}
Returns detailed competitor data.
Add Competitor
POST /v1/competitors
Body:
{
"domain": "competitor.com",
"name": "Competitor Name"
}
Delete Competitor
DELETE /v1/competitors/{competitor_id}
Get Competitor Ads
GET /v1/competitors/{competitor_id}/ads
Returns all ads for a competitor.
Parameters:
- status (optional) - Filter by active/inactive
- start_date (optional) - Ads first seen after date
AI Visibility Endpoints
Get AI Visibility Summary
GET /v1/ai-visibility
Returns overall AI visibility metrics.
List AI Mentions
GET /v1/ai-visibility/mentions
Returns all AI mentions across platforms.
Parameters:
- platform (optional) - Filter by platform (chatgpt, perplexity, google_ai, claude, gemini)
- keyword_id (optional) - Filter by keyword
- start_date (optional) - Mentions after date
Get AI Mention Detail
GET /v1/ai-visibility/mentions/{mention_id}
Returns full AI response text and metadata.
Rankings Endpoints
Get SERP Matrix
GET /v1/rankings/matrix
Returns ranking positions for all keywords and competitors.
Get Ranking Changes
GET /v1/rankings/changes
Returns recent ranking movements.
Parameters:
- min_change (optional) - Minimum position change to include
- days (optional) - Look back period (default: 7)
Reports Endpoints
Generate Report
POST /v1/reports
Body:
{
"type": "weekly_summary",
"format": "pdf",
"date_range": {
"start": "2026-01-01",
"end": "2026-01-07"
}
}
Get Report Status
GET /v1/reports/{report_id}
Check if report generation is complete.
Download Report
GET /v1/reports/{report_id}/download
Download the generated report file.
Account Endpoints
Get Account Info
GET /v1/account
Returns account details and usage stats.
Get Usage
GET /v1/account/usage
Returns current API and feature usage against limits.
Webhooks
List Webhooks
GET /v1/webhooks
Create Webhook
POST /v1/webhooks
Body:
{
"url": "https://your-site.com/webhook",
"events": ["keyword.ranking_changed", "competitor.new_ad"]
}
Delete Webhook
DELETE /v1/webhooks/{webhook_id}
Webhook Events
Available webhook event types:
- keyword.ranking_changed
- keyword.surge_detected
- competitor.new_ad
- competitor.ad_stopped
- ai_visibility.new_mention
- ai_visibility.mention_lost