API Documentation

Access Harvey AI's dividend intelligence programmatically. Build custom integrations, automate research, and create powerful financial tools.

Quick Navigation

Authentication Chat Completions Ticker Search Ticker Details Watchlists Rate Limits Error Codes

Authentication

All API requests require authentication using an API key. Include your API key in the Authorization header as a Bearer token.

Authorization: Bearer hvai_xxxxxxxxxxxxxxxxxxxx

API access is available exclusively to Pro subscribers. Generate API keys from your profile settings. Each account can have up to 5 active API keys.

Base URL

https://api.heydividend.com

Chat Completions

Send messages to Harvey AI and receive intelligent responses about dividends, stocks, and financial topics.

POST /v1/chat/completions

Create a chat completion with Harvey AI. Supports both streaming and non-streaming responses.

Request Body

Parameter Type Description
messagesrequired array Array of message objects with role and content fields
model string Model to use. Default: harvey-dividend
stream boolean Enable streaming responses. Default: false
include_videos boolean Include related video content. Default: false 
curl -X POST https://api.heydividend.com/v1/chat/completions \
  -H "Authorization: Bearer hvai_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "harvey-dividend",
    "messages": [
      {"role": "user", "content": "What are the best dividend ETFs for monthly income?"}
    ]
  }'
import requests

response = requests.post(
    "https://api.heydividend.com/v1/chat/completions",
    headers={
        "Authorization": "Bearer hvai_your_api_key",
        "Content-Type": "application/json"
    },
    json={
        "model": "harvey-dividend",
        "messages": [
            {"role": "user", "content": "What are the best dividend ETFs?"}
        ]
    }
)

print(response.json())
const response = await fetch('https://api.heydividend.com/v1/chat/completions', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer hvai_your_api_key',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    model: 'harvey-dividend',
    messages: [
      { role: 'user', content: 'What are the best dividend ETFs?' }
    ]
  })
});

const data = await response.json();
console.log(data);

Response

{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "created": 1705347200,
  "model": "harvey-dividend",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "For monthly dividend income, here are some top ETFs to consider..."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 15,
    "completion_tokens": 250,
    "total_tokens": 265
  }
}

Ticker Search

Search for stocks, ETFs, and other securities by symbol or name.

GET /api/tickers/search

Search for securities by symbol or company name. Returns matching tickers with basic information.

Query Parameters

Parameter Type Description
qrequired string Search query (symbol or company name)
limit integer Maximum results to return. Default: 10, Max: 50 
curl "https://api.heydividend.com/api/tickers/search?q=SCHD" \
  -H "Authorization: Bearer hvai_your_api_key"

Response

{
  "results": [
    {
      "symbol": "SCHD",
      "name": "Schwab U.S. Dividend Equity ETF",
      "type": "ETF",
      "exchange": "NYSE"
    }
  ]
}

Ticker Details

Get comprehensive information about a specific security including price, dividend data, and key metrics.

GET /api/tickers/{symbol}

Retrieve detailed information about a ticker including current price, dividend yield, payout ratio, ex-dividend dates, and historical data.

Path Parameters

Parameter Type Description
symbolrequired string Stock or ETF ticker symbol (e.g., SCHD, AAPL) 
curl "https://api.heydividend.com/api/tickers/SCHD" \
  -H "Authorization: Bearer hvai_your_api_key"

Response

{
  "symbol": "SCHD",
  "name": "Schwab U.S. Dividend Equity ETF",
  "price": 79.45,
  "change": 0.82,
  "changePercent": 1.04,
  "dividendYield": 3.42,
  "dividendAmount": 0.68,
  "dividendFrequency": "Quarterly",
  "exDividendDate": "2026-03-15",
  "paymentDate": "2026-03-25",
  "marketCap": "52.3B",
  "52weekHigh": 84.20,
  "52weekLow": 68.55
}

Watchlists

Manage your watchlists programmatically. Create, update, and retrieve your tracked securities.

GET /api/watchlists

Retrieve all watchlists for the authenticated user.

curl "https://api.heydividend.com/api/watchlists" \
  -H "Authorization: Bearer hvai_your_api_key"
POST /api/watchlists

Create a new watchlist.

Parameter Type Description
namerequired string Name for the watchlist
POST /api/watchlists/{id}/assets

Add a security to a watchlist.

Parameter Type Description
symbolrequired string Ticker symbol to add
name string Company/ETF name
DELETE /api/watchlists/{id}/assets/{symbol}

Remove a security from a watchlist.

Rate Limits

API requests are subject to rate limits based on your subscription tier.

Tier Requests/Minute Requests/Day
Pro 60 1,000

Rate limit headers are included in all responses: X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset.

Error Codes

The API uses standard HTTP status codes to indicate success or failure.

Code Status Description
200 OK Request successful
400 Bad Request Invalid request parameters
401 Unauthorized Invalid or missing API key
403 Forbidden API access not enabled for your account
404 Not Found Requested resource not found
429 Too Many Requests Rate limit exceeded
500 Internal Server Error Something went wrong on our end

Error Response Format

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "You have exceeded the rate limit. Please try again later."
  }
}

Disclaimer: Harvey AI provides information for educational purposes only. API responses should not be considered financial advice. Always consult with a qualified financial advisor before making investment decisions.