Agent API Overview
The Cited Agent API lets developers build custom integrations that access GEO data programmatically. Use it to embed AI visibility insights into your own applications, dashboards, or automated workflows.
The API follows REST conventions, returns JSON responses, and uses standard HTTP status codes for error handling.
Authentication
Every request must include an authentication credential. The API supports two methods:
API Key (recommended for server-to-server)
X-Agent-API-Key: your-api-key
Bearer Token (for OAuth-based integrations)
Authorization: Bearer your-access-token
Generate API keys from your Cited dashboard under Account > API Tokens. Keep your keys confidential and rotate them periodically. Never expose API keys in client-side code or public repositories.
Base URL
All API endpoints are served from:
https://api.youcited.com
Rate Limits
Rate limits vary by plan. The API returns rate limit headers with every response:
| Header | Description |
|---|---|
X-RateLimit-Limit | Maximum requests per window |
X-RateLimit-Remaining | Requests remaining in the current window |
X-RateLimit-Reset | Unix timestamp when the window resets |
When you exceed the rate limit, the API returns a 429 Too Many Requests response. Back off and retry after the reset time indicated in the headers.
Key Endpoints
Business Facts
GET /agent/v1/business/{id}/facts
Returns structured facts about a business: name, description, categories, locations, contact information, and other entity data that AI systems use when generating responses.
Business Claims
GET /agent/v1/business/{id}/claims
Returns claims and assertions found across AI platforms about the business. Each claim includes the source platform, the exact text, and a confidence score.
Competitor Comparison
GET /agent/v1/business/{id}/comparison
Returns a side-by-side comparison of your AI visibility metrics against tracked competitors. Includes share of voice, citation rates, and coverage differences.
Buyer Fit Query
POST /agent/v1/query/buyer-fit
Evaluates how well a business matches a specific buyer intent query. Send a natural-language question and receive a fit score with an explanation of how AI platforms would likely respond.
Response Format
All responses return JSON with a consistent structure:
{
"status": "success",
"data": {
...
},
"meta": {
"request_id": "req_abc123",
"timestamp": "2026-04-23T12:00:00Z"
}
}
The data field contains the endpoint-specific payload. The meta field includes a unique request ID for support inquiries and a server timestamp.
Error Handling
The API uses standard HTTP status codes:
| Code | Meaning |
|---|---|
200 | Success |
400 | Bad request -- check your parameters |
401 | Unauthorized -- invalid or missing credentials |
403 | Forbidden -- valid credentials but insufficient permissions |
404 | Not found -- the resource does not exist |
429 | Rate limited -- slow down and retry |
500 | Server error -- retry with exponential backoff |
Error responses include a message field with details:
{
"status": "error",
"error": {
"code": "INVALID_BUSINESS_ID",
"message": "No business found with ID 'xyz'. Verify the ID in your dashboard."
}
}
Discovery + Operational Endpoints
Outside the agent API, Cited publishes a handful of endpoints for service discovery, deploy verification, and AI-agent ergonomics:
| Endpoint | Purpose |
|---|---|
GET /version | Returns the running app version, environment, commit SHA, and build timestamp. Useful for confirming what's live without checking GitHub Actions. |
GET /ai.txt | Site-wide AI content usage preferences (parallel to robots.txt, specifically for AI training and inference). |
GET /.well-known/ai-plugin.json | OpenAI plugin manifest pointing at the MCP endpoint. |
GET /.well-known/agent-card.json | Agent2Agent (A2A) discovery card. |
GET /.well-known/api-catalog | RFC 9727 API catalog (link-set JSON). |
GET /.well-known/mcp/server-card.json | MCP server discovery card. |
GET /.well-known/oauth-protected-resource | OAuth 2.0 protected resource metadata (RFC 9728). |
GET /.well-known/oauth-authorization-server | OAuth 2.0 authorization server metadata (RFC 8414). |
Audit response shaping
GET /audit/{job_id}/result accepts an optional ?fields=summary query parameter that omits the large arrays (citations_pulled, questions, keyword_clusters, top_25_prompts) and returns aggregate KPIs + competitor leaderboard plus question_ids for follow-up detail queries via GET /audit/{job_id}/question/{question_id}. Use summary mode for agent contexts where the full response would blow the token budget.
Bulk solution generation
POST /solutions/request-batch accepts up to 10 items in a single request as long as they share the same recommendation_job_id. Each item is processed independently and failed items return inline errors without blocking the rest of the batch.
Dev-only Swagger UI
In the dev environment (https://dev.youcited.com), Cited exposes interactive API documentation under the /api-* namespace (/docs itself is reserved for the user-facing documentation site you're reading right now):
/api-docs— Swagger UI/api-redoc— ReDoc alternative/api-openapi.json— full OpenAPI 3.1 schema
These are disabled in UAT and production. Set PUBLIC_API_DOCS_ENABLED=true in your local environment to enable them locally.
Next Steps
- Browse the full API reference in your Cited dashboard under Developer > API Docs.
- Use the MCP integration for interactive workflows in Claude Desktop. See the Claude Desktop MCP Setup guide.
- Use the in-app chat for the same operations without leaving the dashboard. See the In-App GEO Assistant guide.
- Contact support at [email protected] for enterprise API access or custom integration needs.