API Endpoints Reference
The Surva.ai REST API provides programmatic access to your visibility data. All endpoints require authentication via API key.
The API is actively expanding. Some endpoints listed below may be in development. Check the Swagger documentation for the most current endpoint availability.
Authentication
Include your API key in the request header:
Authorization: Bearer YOUR_API_KEY
Generate API keys in Settings > API Keys.
Base URL
https://app.surva.ai/api/v1
Keywords / Prompts
| Method | Endpoint | Description |
|---|---|---|
| GET | /keywords | List all tracked keywords |
| POST | /keywords | Add a new keyword |
| GET | /keywords/{id} | Get keyword details |
| DELETE | /keywords/{id} | Remove a keyword |
| GET | /keywords/{id}/visibility | Get AI visibility data for a keyword |
Competitors
| Method | Endpoint | Description |
|---|---|---|
| GET | /competitors | List all competitors |
| POST | /competitors | Add a new competitor |
| GET | /competitors/{id} | Get competitor details |
| DELETE | /competitors/{id} | Remove a competitor |
| GET | /competitors/{id}/ads | Get competitor ad data |
AI Visibility
| Method | Endpoint | Description |
|---|---|---|
| GET | /visibility/overview | Overall AI visibility summary |
| GET | /visibility/mentions | List all AI mentions |
| GET | /visibility/citations | List AI citations |
| GET | /visibility/share-of-voice | Share of voice breakdown |
Content
| Method | Endpoint | Description |
|---|---|---|
| GET | /content/articles | List generated articles |
| POST | /content/generate | Generate a new article |
| GET | /content/articles/{id} | Get article details |
Rankings
| Method | Endpoint | Description |
|---|---|---|
| GET | /rankings | Get organic ranking data |
| GET | /rankings/matrix | Get ranking matrix data |
Rate Limits
API rate limits depend on your plan:
- Starter - 100 requests/hour
- Growth - 500 requests/hour
- Business - 2,000 requests/hour
Rate limit headers are included in every response:
X-RateLimit-Limit: 500 X-RateLimit-Remaining: 498 X-RateLimit-Reset: 1700000000
Response Format
All responses are JSON. Successful responses return:
{
"success": true,
"data": { ... }
}
Error responses return:
{
"success": false,
"error": {
"code": "RATE_LIMIT_EXCEEDED",
"message": "Too many requests"
}
}
Pagination
List endpoints support pagination:
GET /api/v1/keywords?page=1&size=25
Paginated responses include:
{
"data": [...],
"page": 1,
"size": 25,
"totalElements": 150,
"totalPages": 6
}