API Documentation for AI Discovery
Why API Docs Matter for AI Search
AI coding assistants like GitHub Copilot, ChatGPT Code Interpreter, and Claude increasingly recommend APIs. Well-documented APIs receive 8.2x more AI recommendations.
OpenAPI/Swagger Specification
Implement OpenAPI 3.0+ spec:
openapi: 3.0.0
info:
title: Rankad.ai API
description: Track your AI search visibility across ChatGPT, Perplexity, and Gemini
version: 1.0.0
contact:
name: API Support
email: api@rankad.ai
url: https://rankad.ai/api/support
license:
name: Apache 2.0
url: https://www.apache.org/licenses/LICENSE-2.0.html
servers:
- url: https://api.rankad.ai/v1
description: Production server
- url: https://api-staging.rankad.ai/v1
description: Staging server
paths:
/citations:
get:
summary: Get AI citations for your brand
description: Retrieve all AI citations for your tracked keywords across supported AI platforms
operationId: getCitations
tags:
- Citations
parameters:
- name: platform
in: query
description: Filter by AI platform (chatgpt, perplexity, gemini, copilot)
schema:
type: string
enum: [chatgpt, perplexity, gemini, copilot, all]
- name: date_from
in: query
description: Start date (YYYY-MM-DD)
schema:
type: string
format: date
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: object
properties:
citations:
type: array
items:
$ref: '#/components/schemas/Citation'
components:
schemas:
Citation:
type: object
required:
- id
- url
- platform
- prompt
- position
- date
properties:
id:
type: string
description: Unique citation identifier
url:
type: string
format: uri
description: URL of cited content
platform:
type: string
enum: [chatgpt, perplexity, gemini, copilot]
description: AI platform where citation appeared
prompt:
type: string
description: User query that generated citation
position:
type: integer
minimum: 1
description: Citation position in response
date:
type: string
format: date-time
description: Citation timestamp
Documentation Structure
1. Getting Started Guide
# Getting Started with Rankad.ai API
## Quick Start (5 minutes)
### 1. Get Your API Key
Sign up at [rankad.ai/api](https://rankad.ai/api) and generate your API key from the dashboard.
### 2. Make Your First Request
```bash
curl -X GET "https://api.rankad.ai/v1/citations" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json"
3. Parse the Response
{
"citations": [
{
"id": "cit_123abc",
"url": "https://yoursite.com/article",
"platform": "chatgpt",
"prompt": "What is AI search optimization?",
"position": 2,
"date": "2025-10-15T10:30:00Z"
}
],
"total": 1,
"page": 1
}
Next Steps
### 2. Code Examples in Multiple Languages
Provide examples in popular languages:
**Python**:
```python
import requests
api_key = "your_api_key"
headers = {
"Authorization": f"Bearer {api_key}",
"Content-Type": "application/json"
}
response = requests.get(
"https://api.rankad.ai/v1/citations",
headers=headers,
params={"platform": "chatgpt"}
)
citations = response.json()
print(f"Found {len(citations['citations'])} citations")
JavaScript/Node.js:
const axios = require('axios');
const apiKey = 'your_api_key';
const config = {
headers: {
'Authorization': `Bearer ${apiKey}`,
'Content-Type': 'application/json'
}
};
axios.get('https://api.rankad.ai/v1/citations', config)
.then(response => {
console.log(`Found ${response.data.citations.length} citations`);
})
.catch(error => console.error(error));
cURL:
curl -X GET "https://api.rankad.ai/v1/citations?platform=chatgpt" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json"
3. Interactive API Explorer
Embed interactive documentation:
- Swagger UI
- Redoc
- Postman Collections
- GraphQL Playground (if applicable)
4. Error Documentation
Document all error responses:
## Error Handling
### Standard Error Response
```json
{
"error": {
"code": "invalid_request",
"message": "The 'platform' parameter must be one of: chatgpt, perplexity, gemini, copilot, all",
"details": {
"parameter": "platform",
"provided_value": "bing",
"allowed_values": ["chatgpt", "perplexity", "gemini", "copilot", "all"]
},
"documentation_url": "https://rankad.ai/api/errors#invalid_request"
}
}
Common Error Codes
| Code | HTTP Status | Description | Solution | |------|-------------|-------------|----------| | invalid_request | 400 | Request parameters invalid | Check parameter format | | unauthorized | 401 | Invalid API key | Verify API key is correct | | forbidden | 403 | Insufficient permissions | Upgrade plan or request access | | not_found | 404 | Resource doesn't exist | Check resource ID | | rate_limit_exceeded | 429 | Too many requests | Implement backoff strategy | | server_error | 500 | Internal server error | Retry with exponential backoff | ```
AI-Optimized Documentation Elements
1. Use Cases Section
## Common Use Cases
### 1. Daily Citation Monitoring
Track new citations every 24 hours:
```python
def monitor_daily_citations():
today = datetime.now().strftime("%Y-%m-%d")
citations = get_citations(date_from=today)
if len(citations) > 0:
send_alert(f"New citations: {len(citations)}")
2. Competitive Analysis
Compare your citations with competitors:
your_citations = get_citations(domain="yoursite.com")
competitor_citations = get_citations(domain="competitor.com")
visibility_gap = len(competitor_citations) - len(your_citations)
### 2. Detailed Response Schemas
Document every field:
```markdown
### Citation Object
| Field | Type | Description | Example |
|-------|------|-------------|---------|
| id | string | Unique citation identifier | "cit_123abc" |
| url | string | Full URL of cited page | "https://site.com/page" |
| platform | string | AI platform name | "chatgpt" |
| prompt | string | User query (truncated if >200 chars) | "What is AIO?" |
| position | integer | Citation position (1-indexed) | 2 |
| context | string | Surrounding text from AI response | "According to..." |
| date | string | ISO 8601 timestamp | "2025-10-15T10:30:00Z" |
3. Versioning Strategy
Document API versions clearly:
## API Versioning
Current version: **v1**
### Version History
- **v1** (Current) - Released October 2025
- Initial release
- Endpoints: /citations, /keywords, /analytics
### Deprecation Policy
- 12 months notice before deprecation
- 6 months of parallel v1/v2 support
- Migration guides provided
### Version Specification
Specify version in URL:
https://api.rankad.ai/v1/citations
Technical SEO for API Docs
1. Software Application Schema
{
"@context": "https://schema.org",
"@type": "SoftwareApplication",
"name": "Rankad.ai API",
"applicationCategory": "DeveloperApplication",
"description": "REST API for tracking AI search citations across ChatGPT, Perplexity, and Gemini",
"operatingSystem": "Any",
"offers": {
"@type": "Offer",
"price": "0",
"priceCurrency": "USD"
},
"documentation": "https://rankad.ai/api/docs"
}
2. TechArticle Schema
For tutorials and guides:
{
"@context": "https://schema.org",
"@type": "TechArticle",
"headline": "Getting Started with Rankad.ai API",
"description": "Complete guide to integrating AI citation tracking",
"dependencies": "Python 3.8+, requests library",
"proficiencyLevel": "Beginner"
}
SDK Development
Create official SDKs:
Python SDK
from rankad import Client
client = Client(api_key="your_key")
citations = client.citations.list(platform="chatgpt")
JavaScript SDK
import { RankadClient } from '@rankad/sdk';
const client = new RankadClient({ apiKey: 'your_key' });
const citations = await client.citations.list({ platform: 'chatgpt' });
Document SDK installation and usage prominently.
Measuring API Documentation Success
Track:
- API adoption rate
- Documentation page views
- Code example copy rates
- Support ticket volume (lower is better)
- AI assistant API recommendations
Monitor with Rankad.ai's developer tracking tools.
