API Documentation — REST API Reference

/

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

3 Make authenticated requests

curl "https://api.ko.io/api/v1/holdings/102909" \
  -H "Authorization: Bearer ko_live_your_key_here"

NoteBase 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_*.

terminal

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	Bulk Export
Free (demo)	$0	100 / day	No
Developer	$29 / mo	10,000 / day	Yes
Team	$99 / mo	100,000 / day	Yes
Enterprise	Custom	Custom	Yes

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

200 OK

{
  "data": [ ... ],
  "meta": {
    "page": 1,
    "per_page": 50,
    "total_count": 1234,
    "query_time_ms": 3.1
  }
}

Object Response

200 OK

{
  "data": { ... },
  "meta": {
    "query_time_ms": 2.1
  }
}

Error Codes

Status	Meaning	Resolution
400	Bad Request	Check query parameters and path format
401	Unauthorized	Include valid API key or use ?demo=true
403	Forbidden	Upgrade plan for this endpoint or feature
404	Not Found	Check endpoint path and resource IDs
429	Rate Limited	Wait for reset or upgrade plan
500	Server Error	Retry after a few seconds

Error Response

{
  "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)

terminal

claude mcp add ko-sec-data --transport http https://mcp.ko.io/mcp

Local (stdio — Claude Code, Cursor)

terminal

claude mcp add ko-sec-data -- npx -y @ko-io/mcp-sec-data

Environment variables (optional)

.env

KO_API_KEY=ko_live_xxx    # Optional: without key, uses demo mode (100/day)
KO_API_URL=https://api.ko.io

Available 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

Institutions

4 endpoints

GET/api/v1/institutions#

List institutional investors with portfolio metrics. Returns AUM, holdings count, and top positions.

GET/api/v1/institutions/{cik}#

Get institution details by CIK number. Includes filing history, sector allocation, and recent activity.

GET/api/v1/institutions/aum/{cik}#

Get historical AUM (assets under management) over time. Returns quarterly portfolio values for charting.

GET/api/v1/institutions/{cik}/similar#

Get similar institutional investors based on quarterly 13F holdings, active timing, and portfolio profile signals. Supports CIK or slug.

Holdings

1 endpoint

GET/api/v1/holdings/{cik}#

Get 13F institutional holdings with pre-calculated analytics: quarter-over-quarter changes, action labels (NEW_BUY, ADD, REDUCE, SOLD_ALL), and portfolio weights. Supports slug (e.g., berkshire-hathaway).

Stocks & Companies

7 endpoints

GET/api/v1/stocks#

List stocks with basic information.

GET/api/v1/stocks/{ticker}#

Get stock info with top institutional holders, recent insider activity, and ownership summary.

GET/api/v1/stocks/{ticker}/financials#

Get latest company financials from 10-K and 10-Q filings. 30+ standardized metrics including revenue, margins, EPS, cash flow, and debt ratios.

GET/api/v1/stocks/{ticker}/financials/historical#

Get historical financial data for trend analysis. Returns quarterly or annual periods with all standardized metrics.

GET/api/v1/companies#

List companies with basic information. Search by company name or ticker symbol.

GET/api/v1/companies/{ticker}#

Get detailed company profile including sector, industry, market cap, and description.

GET/api/v1/stock-price/{ticker}#

Get historical daily stock prices with OHLCV data and adjusted close.

Stock Analysis

2 endpoints

GET/api/v1/stock-holders/{ticker}#

Get institutional holders for a stock. Shows ownership percentage, share counts, and quarter-over-quarter changes.

GET/api/v1/stock-transactions/{ticker}/{cik}#

Get the full transaction history between a stock and institution across all quarters.

Insider Trades

2 endpoints

GET/api/v1/insider-trades#

List insider trades from SEC Form 4 filings. Includes officer/director buys and sells with dollar values and role identification.

GET/api/v1/executive-trades/{ticker}#

Get C-suite and director insider trades for a specific stock. Aggregated by executive with total buy/sell volumes.

Congress Trades

4 endpoints

GET/api/v1/congress-trades#

List congressional stock trades from STOCK Act disclosures. Includes transaction type, dollar ranges, and disclosure delays.

GET/api/v1/congress-trades/{member}#

Get all trades for a specific congress member. URL-encode the member name.

GET/api/v1/congress-trades/stock/{ticker}#

Get all congressional trades for a specific stock across all members.

GET/api/v1/congress-trades/dashboard#

Congressional trading dashboard: most active members, most traded stocks, buy/sell ratio, and disclosure delay statistics.

SEC Extensions

6 endpoints

GET/api/v1/form144-notices#

List SEC Form 144 notices of proposed sale of securities.

GET/api/v1/form144-notices/{ticker}#

Get Form 144 notices for a specific stock ticker.

GET/api/v1/form144-notices/insider/{cik}#

Get Form 144 notices filed by a specific insider (by CIK).

GET/api/v1/sec/13dg#

SC 13D/G filings — beneficial ownership disclosures for >5% holders.

GET/api/v1/sec/form-d#

Form D offerings — private placement and Regulation D filings.

GET/api/v1/sec/buybacks#

8-K buyback announcements — share repurchase program disclosures extracted from 8-K filings.

Treasury

3 endpoints

GET/api/v1/treasury/yields#

US Treasury yield curve data from 1990. Includes 1M, 3M, 6M, 1Y, 2Y, 3Y, 5Y, 7Y, 10Y, 20Y, 30Y maturities.

GET/api/v1/treasury/auctions#

Treasury auction records — bid-to-cover ratios, high yields, allotment percentages.

GET/api/v1/treasury/debt#

Daily US public debt outstanding — total, public held, and intragovernmental.

Federal Reserve

3 endpoints

GET/api/v1/fed/rates#

Federal Reserve interest rates — Fed Funds Rate, SOFR, prime rate, discount rate. Data from 1962.

GET/api/v1/fed/balance-sheet#

Federal Reserve balance sheet (H.4.1) — total assets, treasuries, MBS, reserves.

GET/api/v1/fed/bank-credit#

Commercial bank credit (H.8) — loans, leases, securities, deposits at all commercial banks.

Economic

1 endpoint

GET/api/v1/economic/indicators#

BLS economic indicators — CPI, PPI, Non-Farm Payrolls, unemployment rate, JOLTS.

Market Microstructure

3 endpoints

GET/api/v1/finra/short-volume#

FINRA daily short volume data from 2020. Short volume, total volume, and short ratio per ticker per day.

GET/api/v1/sec/ftd#

SEC Failures to Deliver data from 2004. Daily FTD share counts and values by ticker.

GET/api/v1/cftc/positions#

CFTC Commitments of Traders — disaggregated futures positioning from 2006.

Energy

1 endpoint

GET/api/v1/energy/eia#

EIA energy data — crude oil inventory, natural gas storage, WTI/Brent prices, 9 series total.

Banking

3 endpoints

GET/api/v1/fdic/banks#

FDIC bank directory — all US banks with charter info, location, and status.

GET/api/v1/fdic/financials#

FDIC bank quarterly financials — assets, deposits, loans, capital ratios for any US bank.

GET/api/v1/fdic/failures#

FDIC bank failures from 1934. Includes acquiring institution, estimated loss, and assets at failure.

Financial Stress

1 endpoint

GET/api/v1/stress/ofr#

OFR Financial Stress Index — 6 sub-components covering credit, equity, funding, safe assets, volatility, and composite.

Bulk Export

1 endpoint

GET/api/v1/bulk/export#

Bulk data export in CSV or JSON format. Requires Developer ($29/mo) or higher plan. Supports 6 core tables.

Dashboard

2 endpoints

GET/api/v1/dashboard/metrics#

Platform metrics: total institutions, holdings records, insider trades, and congress trades.

GET/api/v1/dashboard/trends#

Trending activity across all data types. Most active institutions, most traded insider stocks, recent congressional activity.

Search

1 endpoint

GET/api/v1/search#

Unified search across institutions, stocks, and congress members. Returns categorized results.