API Overview
The Surva.ai API gives you programmatic access to your AI visibility data, brand mentions, competitor intelligence, and content tools. Use it to pull Surva.ai data into your own dashboards, BI tools, client reports, or automated workflows.
Getting Your API Key
Generate an API key from Settings > API Keys. Each key is scoped to your account and carries the same permissions as your user role. Store keys securely - treat them like passwords and never expose them in client-side code.
Authentication
Include your API key as a Bearer token in the Authorization header of every request:
Authorization: Bearer YOUR_API_KEYRequests without a valid key return HTTP 401. Requests that exceed plan limits return HTTP 403.
Base URL
https://app.surva.ai/api/Core Endpoints
Prompts (Keywords)
| Method | Endpoint | Description |
|---|---|---|
| GET | /api/keywords | List all tracked prompts for your brand |
| POST | /api/keywords | Add a new prompt to tracking |
| DELETE | /api/keywords/{id} | Remove a tracked prompt |
AI Visibility
| Method | Endpoint | Description |
|---|---|---|
| GET | /api/ai-visibility/overview | Overall visibility summary and platform breakdown |
| GET | /api/citations | URLs cited by AI platforms for your brand |
| GET | /api/brand-llm-mentions | Brand mention records from AI scans |
| GET | /api/competitor-llm-mentions | Competitor mentions detected during your scans |
Competitors
| Method | Endpoint | Description |
|---|---|---|
| GET | /api/competitors | List tracked competitors with visibility scores |
| POST | /api/competitors | Add a competitor by domain |
| DELETE | /api/competitors/{id} | Remove a competitor |
| GET | /api/competitor-keywords | Keywords where competitors appear in AI responses |
AI Referrals and Crawlers
| Method | Endpoint | Description |
|---|---|---|
| GET | /api/ai-referral | Traffic arriving from AI platform referrer domains |
| GET | /api/crawler-logs | AI bot visit records for your domain |
| POST | /api/crawler-logs/import | Import web server access logs for AI bot analysis |
Prompt Discovery
| Method | Endpoint | Description |
|---|---|---|
| GET | /api/prompt-discovery/prompts | Discovered prompt suggestions for your brand |
| GET | /api/prompt-discovery/related-questions | Related questions found during scans |
| POST | /api/prompt-discovery/aggregate-questions | Trigger aggregation of new related questions |
Brands
| Method | Endpoint | Description |
|---|---|---|
| GET | /api/brands | List all brands on your account |
| POST | /api/brands | Create a new brand |
Rate Limits
Rate limits are based on your subscription plan:
- Starter - 100 requests per hour
- Growth - 500 requests per hour
- Business - 2,000 requests per hour
Every response includes rate limit headers so you can track usage:
X-RateLimit-Limit: 500
X-RateLimit-Remaining: 498
X-RateLimit-Reset: 1700000000Exceeding your rate limit returns HTTP 429 with a Retry-After header.
Response Format
All endpoints return JSON. Successful responses use HTTP 200:
{
"success": true,
"data": { ... }
}Error responses include a structured error object:
{
"success": false,
"error": {
"code": "UNAUTHORIZED",
"message": "Invalid or missing API key"
}
}Pagination
List endpoints support pagination via query parameters:
GET /api/keywords?page=0&size=50Paginated responses include total count and page metadata alongside the data array.
Brand Scoping
All data endpoints are scoped to a specific brand. If your account has multiple brands, include the brandId as a query parameter:
GET /api/keywords?brandId=YOUR_BRAND_IDRetrieve your brand IDs from GET /api/brands. If you omit brandId, the API defaults to your primary brand.