Quickstart
Get your first API response in 30 seconds. No API key required for demo mode.
1. Try the demo (no key needed)
curl "https://api.ko.io/api/v1/institutions?search=berkshire&demo=true"2. Get your free API key
Sign up at ko.io/auth → go to Console → API Keys → create a key.
3. Make authenticated requests
curl "https://api.ko.io/api/v1/holdings/102909" \
-H "Authorization: Bearer ko_live_your_key_here"Base URL: https://api.ko.io · All endpoints return JSON · Pagination via page and per_page params
Authentication
Include your API key as a Bearer token in the Authorization header. Keys use the format ko_live_*.
curl https://api.ko.io/api/v1/institutions \
-H "Authorization: Bearer ko_live_a1b2c3d4e5f6..."Demo Mode
Add ?demo=true to any endpoint for keyless access. Limited to 100 requests/day. Great for testing and prototyping.
API Key Format
Keys start with ko_live_ followed by a hex string. Create keys in the Console.
Auth Endpoints (Web App)
The following endpoints are used by the ko.io web app and are not intended for API consumers:
POST /api/auth/google · /api/auth/login · /api/auth/register · /api/auth/logout
GET /api/auth/me · /api/auth/profile
Rate Limits
Requests are rate-limited per API key on a daily rolling window.
| Plan | Price | Daily Limit |
|---|---|---|
| Free (demo) | $0 | 100 / day |
| Developer | $29 / mo | 10,000 / day |
| Team | $99 / mo | 100,000 / day |
| Enterprise | Custom | Custom |
Rate limit headers are included in every response: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset.
Response Format
All responses follow a consistent JSON structure with data and meta fields.
List Response
{
"data": [ ... ],
"meta": {
"page": 1,
"per_page": 50,
"total_count": 1234,
"query_time_ms": 3.1
}
}Object Response
{
"data": { ... },
"meta": {
"query_time_ms": 2.1
}
}Error Codes
| Status | Meaning |
|---|---|
| 400 | Bad Request |
| 401 | Unauthorized |
| 403 | Forbidden |
| 404 | Not Found |
| 429 | Rate Limited |
| 500 | Server Error |
{
"error": "Unauthorized",
"message": "Invalid or missing API key. Use ?demo=true for keyless access.",
"status": 401
}MCP Integration
Connect AI tools like Claude, Cursor, and Windsurf directly to ko.io data via the Model Context Protocol. 19 tools available covering SEC filings, macro data, and market microstructure.
Remote (HTTP transport — Claude.ai, any MCP client)
claude mcp add ko-sec-data --transport http https://mcp.ko.io/mcpLocal (stdio — Claude Code, Cursor)
claude mcp add ko-sec-data -- npx -y @ko-io/mcp-sec-dataEnvironment variables (optional)
KO_API_KEY=ko_live_xxx # Optional: without key, uses demo mode (100/day)
KO_API_URL=https://api.ko.ioAvailable Tools (19)
| Tool | Description |
|---|---|
search | Search across institutions, stocks, and congress members |
get_institution_holdings | 13F institutional holdings with change analytics |
list_institutions | List/search institutional investors |
get_stock_profile | Stock info with ownership summary |
get_stock_holders | Institutional holders for a stock |
get_stock_activity | Stock activity and trading metrics |
get_stock_financials | Company financials from SEC filings |
get_stock_price | Historical daily OHLCV prices |
get_insider_trades | Form 4 insider trades with filters |
list_insider_traders | Top insider traders by volume |
get_congress_trades | Congressional stock trades from STOCK Act |
get_congress_member | Trading history for a congress member |
get_form144_notices | Form 144 proposed sale notices |
get_treasury_yields | US Treasury yield curve data |
get_fed_rates | Federal Reserve interest rates |
get_economic_indicators | BLS CPI, PPI, NFP, unemployment |
get_short_volume | FINRA daily short volume |
get_ftd_data | SEC Failures to Deliver |
get_financial_stress | OFR Financial Stress Index |