Authentication
The Divv API uses API keys to authenticate requests. You can create and manage your API keys from your Dashboard.
Getting an API Key
Keep your API key secure
Your API key grants access to your account. Never share it publicly, commit it to version control, or expose it in client-side code. Use environment variables to store your key.
Making Authenticated Requests
Include your API key in the Authorization header using the Bearer scheme:
curl https://api.divv.com/v1/stocks/AAPL \ -H "Authorization: Bearer sk_live_your_api_key_here"
Example in Different Languages
Python
import requests
response = requests.get(
"https://api.divv.com/v1/stocks/AAPL",
headers={"Authorization": "Bearer sk_live_your_api_key"}
)
data = response.json()JavaScript
const response = await fetch("https://api.divv.com/v1/stocks/AAPL", {
headers: {
"Authorization": "Bearer sk_live_your_api_key"
}
});
const data = await response.json();Rate Limits
Rate limits are applied per user account (not per API key). If you have multiple API keys, they share the same rate limit.
| Tier | Rate Limit | Burst Limit | Monthly Quota |
|---|---|---|---|
| Free | 10/minute | 20 | 5,000 |
| Starter | 30/minute | 60 | 50,000 |
| Premium | 100/minute | 200 | 250,000 |
| Professional | 300/minute | 600 | 1,000,000 |
Rate Limit Headers
Every API response includes headers to help you track your rate limit status:
| Header | Description |
|---|---|
| X-RateLimit-Limit | Your rate limit per minute |
| X-RateLimit-Remaining | Remaining requests in current window |
| X-RateLimit-Reset | Unix timestamp when limit resets |
Feature Access by Tier
Some endpoints and features require a paid subscription:
| Feature | Free | Starter | Premium | Pro |
|---|---|---|---|---|
| Stock quotes & prices | ✓ | ✓ | ✓ | ✓ |
| Current dividend yield | ✓ | ✓ | ✓ | ✓ |
Fundamentals (P/E, market cap, sector)/v1/stocks/{symbol}/fundamentals | ✗ | ✓ | ✓ | ✓ |
Dividend history/v1/stocks/{symbol}/dividends | ✗ | ✓ | ✓ | ✓ |
| Historical data years | 1 year | 5 years | 30 years | 100 years |
Bulk operations/v1/bulk/* | ✗ | ✗ | ✗ | ✓ (1,000) |
View pricing for full tier comparison.
Error Responses
The API returns standard HTTP status codes and structured error responses:
Returned when the API key is missing, invalid, or expired.
{
"error": "Invalid API key.",
"code": "INVALID_API_KEY"
}Returned when your subscription tier doesn't include access to the requested feature.
{
"error": "Fundamentals data is not available on your current plan",
"code": "FEATURE_NOT_AVAILABLE",
"current_tier": "free",
"required_feature": "fundamentals",
"upgrade_url": "/pricing"
}Returned when you exceed your rate limit or monthly quota.
Rate limit exceeded:
{
"error": "Rate limit exceeded",
"code": "RATE_LIMIT_EXCEEDED",
"retry_after": 60
}Monthly quota exceeded:
{
"error": "Monthly quota exceeded",
"code": "QUOTA_EXCEEDED",
"current_usage": 5000,
"quota_limit": 5000,
"usage_percentage": 100,
"upgrade_url": "/pricing"
}Returned when the requested resource doesn't exist.
{
"error": "Stock 'INVALID' not found"
}Best Practices
Use environment variables
Store your API key in environment variables (DIVV_API_KEY) rather than hardcoding it in your application.
Handle rate limits gracefully
Check the X-RateLimit-Remaining header and implement exponential backoff when you receive a 429 response.
Use bulk endpoints for multiple symbols
If you're on the Professional tier, use /v1/bulk/* endpoints instead of making individual requests. This uses fewer API calls and is faster.
Rotate keys periodically
Create new API keys and delete old ones periodically. You can set expiration dates when creating keys.
Managing Your Subscription
Upgrading: Visit the Pricing page to upgrade your plan. Changes take effect immediately.
Managing billing: Click "Manage Subscription" in your Dashboard to access the billing portal where you can update payment methods, view invoices, or cancel.
Cancellation: You can cancel anytime. You'll retain access to paid features until the end of your billing period.