The Citationly AI Search API
Pull AI visibility, citation, and Share of Voice data into your own systems. This is a REST API that returns JSON, uses standard authentication, and follows predictable conventions.
What the AI Search API does
The Citationly AI Search API gives developers programmatic access to the data the platform collects: brand mentions, citations, visibility scores, and Share of Voice across the supported engines. It is a REST API: requests use standard HTTP methods, responses return JSON, and resources follow consistent naming.
API authentication
The API uses key-based authentication. Every request must include your API key in the Authorization header. Keys are issued per workspace and can be scoped. Keep keys server-side; if a key is exposed, revoke and reissue it from platform settings.
Authorization: Bearer ctly_live_••••••••••••API endpoints
| Resource | Purpose |
|---|---|
Mentions /v1/mentions | Retrieve brand and competitor mentions across engines. |
Citations /v1/citations | Retrieve citation records, including the citing engine and source. |
Visibility /v1/visibility | Retrieve visibility scores over time. |
Share of Voice /v1/share-of-voice | Retrieve Share of Voice against your competitor set. |
Questions /v1/questions | Manage the question library a workspace monitors. |
Reports /v1/reports | Retrieve report data for export. |
Each endpoint supports filtering by engine, date range, and competitor where relevant.
Request examples
A request retrieves a resource with your key in the header and optional filters as query parameters. Requests that create or update data send a JSON body describing the resource.
# Retrieve a resource
GET /v1/mentions?engine=chatgpt&start_date=2026-06-01
Authorization: Bearer ctly_live_••••••••••••
# Create a resource
POST /v1/questions
Authorization: Bearer ctly_live_••••••••••••
Content-Type: application/json
{
"text": "Best AI visibility platforms",
"engines": ["chatgpt", "perplexity"]
}{
"data": [
{
"id": "mnt_8f2a1c",
"engine": "chatgpt",
"sentiment": "positive"
}
],
"meta": {
"total": 214,
"next_cursor": "eyJvZmZzZXQiOjI1fQ"
}
}Response examples
Responses return JSON with a consistent structure: a data object containing the requested records and meta describing the result, such as the total count and pagination cursors.
Rate limits
Requests are rate limited per API key. Each response includes headers showing your current limit, remaining requests, and reset time. High-volume use cases are better served by the reporting endpoints and, where available, webhooks.
X-RateLimit-LimitThe total number of requests allowed in the current window.
X-RateLimit-RemainingHow many requests are left before you hit the limit.
X-RateLimit-ResetWhen the current window resets, as a Unix timestamp.
Error handling
The API uses standard HTTP status codes and returns a JSON error body with a machine-readable code and a human-readable message.
{
"error": {
"code": "invalid_api_key",
"message": "The API key provided is invalid."
}
}200Success400Bad request401Unauthorized404Not found429Rate limited500Server errorBest practices for the AI Search API
Store keys securely and rotate them periodically.
Request only the data you need using filters.
Read the rate-limit headers and pace requests.
Prefer webhooks for event-driven needs.
Handle errors by code rather than by parsing messages.
For details on connecting Citationly to your other tools, see the Integrations guide.
Answers before you write a line of code.
The Citationly AI Search API is a REST API. Requests use standard HTTP methods, resources are addressed by predictable paths, and every response is JSON. If you have used a modern SaaS REST API before, the conventions here will feel familiar.
Start building with the API
Get an API key, make your first authenticated request, and pull your AI visibility data wherever your team already works.