# Perplexity API Documentation
## Authentication
- Bearer token authentication required
- Header: `Authorization: Bearer <token>`
- Base URL: `https://api.perplexity.ai`
## Models
| Model | Context Length | Model Type | Price (per million tokens) |
|-------|----------------|------------|----------------------------|
| `sonar-deep-research` | 128k | Chat Completion | $2 input / $3 reasoning / $8 output |
| `sonar-reasoning-pro` | 128k | Chat Completion | $2 input / $8 output |
| `sonar-reasoning` | 128k | Chat Completion | $1 input / $5 output |
| `sonar-pro` | 200k | Chat Completion | $3 input / $15 output |
| `sonar` | 128k | Chat Completion | $1 input / $1 output |
| `r1-1776` | 128k | Chat Completion | $2 input / $8 output |
*Notes:*
- `sonar-reasoning-pro` and `sonar-pro` have a max output token limit of 8k
- The reasoning models output Chain-of-Thought reasoning in their responses
- `r1-1776` is an offline chat model that does not use the search subsystem
- Search queries cost $5 per 1000 searches across models
## Chat Completions Endpoint
### Request Details
- **Method**: POST
- **Endpoint**: `/chat/completions`
- **Content-Type**: application/json
### Parameters
#### Required Parameters
- `model`: Model name (e.g., "llama-3.1-sonar-small-128k-online")
- `messages`: Array of message objects:
```json
{
"role": "system" | "user" | "assistant",
"content": "message text"
}
```
#### Optional Parameters
| Parameter | Description | Range/Values |
|-----------|-------------|--------------|
| `max_tokens` | Maximum response tokens | Model dependent |
| `temperature` | Randomness | 0-2 (default: 0.2) |
| `top_p` | Nucleus sampling | 0-1 (default: 0.9) |
| `top_k` | Token filtering | 0-2048 (default: 0) |
| `stream` | Enable streaming | boolean (default: false) |
| `presence_penalty` | Topic diversity | -2 to 2 |
| `frequency_penalty` | Repetition penalty | >0 |
| `search_domain_filter` | Domain whitelist/blacklist | Array (beta) |
| `return_images` | Include images | boolean (beta) |
| `return_related_questions` | Get related questions | boolean (beta) |
| `search_recency_filter` | Time filter | "month", "week", "day", "hour" |
### Response Format
```json
{
"id": "uuid",
"model": "model-name",
"object": "chat.completion",
"created": timestamp,
"citations": ["url1", "url2"],
"choices": [{
"index": 0,
"finish_reason": "stop",
"message": {
"role": "assistant",
"content": "response"
}
}],
"usage": {
"prompt_tokens": 123,
"completion_tokens": 456,
"total_tokens": 579
}
}
```
## Code Examples
### cURL
```bash
curl --request POST \
--url https://api.perplexity.ai/chat/completions \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{
"model": "llama-3.1-sonar-small-128k-online",
"messages": [
{
"role": "system",
"content": "Be precise and concise."
},
{
"role": "user",
"content": "How many stars are there in our galaxy?"
}
],
"temperature": 0.2,
"top_p": 0.9
}'
```
### Python
```python
import requests
url = "https://api.perplexity.ai/chat/completions"
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
payload = {
"model": "llama-3.1-sonar-small-128k-online",
"messages": [
{
"role": "system",
"content": "Be precise and concise."
},
{
"role": "user",
"content": "How many stars are there in our galaxy?"
}
],
"temperature": 0.2,
"top_p": 0.9
}
response = requests.post(url, json=payload, headers=headers)
print(response.json())
```
### JavaScript
```javascript
const options = {
method: 'POST',
headers: {
'Authorization': 'Bearer <token>',
'Content-Type': 'application/json'
},
body: JSON.stringify({
"model": "llama-3.1-sonar-small-128k-online",
"messages": [
{
"role": "system",
"content": "Be precise and concise."
},
{
"role": "user",
"content": "How many stars are there in our galaxy?"
}
],
"temperature": 0.2,
"top_p": 0.9
})
};
fetch('https://api.perplexity.ai/chat/completions', options)
.then(response => response.json())
.then(console.log)
.catch(console.error);
```
## Beta Features & Rate Limits
- Request elevated rate limits via [access form](https://perplexity.typeform.com/apiaccessform)
- Beta features requiring approval:
- Image support (`return_images`)
- Related questions (`return_related_questions`)
- Domain filtering (`search_domain_filter`) - limit 3 domains