{ "openapi": "3.0.3", "info": { "title": "bengarrard data API", "version": "1.0.0", "description": "Public-records + market-intelligence data API. One key, twelve endpoints: vehicle VIN history, county property/deed/lien records, and a congressional-trades / SEC-insider / lobbying / patents / federal-contracts / PAC-donor market-intelligence suite, plus in-house strategy backtest rows and 5-year daily price series.\n\nAuthenticate with `X-API-Key: bg_live_…` (header) or `?api_key=` (query param). Keys are issued by the operator — email b2gdevs@gmail.com or subscribe via the RapidAPI listing.\n\n**Honesty note:** `property`, `deeds`, and `liens` are BETA — the county-record backfill is in progress and results may be sparse or empty for many counties. `congress-trades` reflects U.S. House member stock-trade (PTR) disclosures, not voting records or policy positions.", "contact": { "name": "Ben Garrard", "email": "b2gdevs@gmail.com", "url": "https://api.bengarrard.com" }, "license": { "name": "Proprietary — commercial use requires a paid key" } }, "servers": [ { "url": "https://api.bengarrard.com", "description": "Production" } ], "tags": [ { "name": "Vehicle", "description": "VIN decode, recalls, complaints, theft flag" }, { "name": "Property", "description": "County assessor + clerk records (beta)" }, { "name": "Government", "description": "Congressional trades, SEC insiders, lobbying, patents, federal contracts, PAC donors" }, { "name": "Markets", "description": "In-house strategy predictions + daily price series" }, { "name": "Meta", "description": "Service health + spec" } ], "security": [ { "ApiKeyAuth": [] } ], "components": { "securitySchemes": { "ApiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "Your bengarrard data API key, e.g. `bg_live_3f9a...`. May also be passed as `?api_key=` query param, or an `Authorization: Bearer ` header. RapidAPI-proxied requests instead carry `X-RapidAPI-Proxy-Secret` and skip this header entirely." } }, "responses": { "Unauthorized": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": "Missing API key. Pass it as `X-API-Key: bg_live_…` header or `?api_key=`. Get one at https://api.bengarrard.com/.", "code": 401, "docs": "https://api.bengarrard.com/" } } } }, "RateLimited": { "description": "Rate limit exceeded for the key's tier.", "headers": { "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Requests/minute ceiling for this tier." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests remaining in the current window." }, "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds until the window resets." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": "Rate limit exceeded (60/min for tier free).", "code": 429, "docs": "https://api.bengarrard.com/", "retryAfterSec": 12 } } } } }, "schemas": { "ErrorEnvelope": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "integer" }, "docs": { "type": "string" }, "retryAfterSec": { "type": "integer" } }, "required": ["error", "code"] } }, "parameters": { "TickerParam": { "name": "ticker", "in": "query", "required": false, "description": "Stock ticker symbol, case-insensitive (e.g. NVDA).", "schema": { "type": "string", "example": "NVDA" } } } }, "paths": { "/health": { "get": { "tags": ["Meta"], "summary": "Service health check", "description": "Unauthenticated. Reports service status, loaded dataset slugs, and the configured records-engine URL.", "security": [], "responses": { "200": { "description": "Service is up.", "content": { "application/json": { "example": { "ok": true, "service": "data-api", "datasets": ["congress-trades", "insiders", "donors", "contracts", "lobbying", "patents", "predictions", "prices"], "recordsEngine": "http://127.0.0.1:8787" } } } } } } }, "/v1/vin": { "get": { "tags": ["Vehicle"], "summary": "Decode a VIN + open recalls + complaint count", "description": "NHTSA vPIC decode, open recall campaigns, complaint count, and a theft flag (NICB VINCheck). Stable.", "parameters": [ { "name": "vin", "in": "query", "required": true, "description": "17-character Vehicle Identification Number.", "schema": { "type": "string", "example": "1HGCM82633A004352" } } ], "responses": { "200": { "description": "Decoded VIN history.", "content": { "application/json": { "example": { "vin": "1HGCM82633A004352", "decode": { "make": "HONDA", "model": "Accord", "year": 2003, "trim": "EX", "bodyClass": "Sedan/Saloon", "engine": "2.4L I4", "plant": "MARYSVILLE, OH, US", "gvwr": null }, "openRecalls": [ { "campaignNumber": "03V293000", "component": "AIR BAGS", "summary": "Front air bag inflator may rupture.", "remedy": "Dealer will replace the driver/passenger air bag inflator free of charge.", "reportDate": "2003-07-01" } ], "complaintsCount": 12, "theftFlag": false, "titleBrand": null } } } }, "400": { "description": "Missing `vin` param.", "content": { "application/json": { "example": { "error": "vin query param required" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/property": { "get": { "tags": ["Property"], "summary": "Property / assessor record", "description": "County-assessor (CAD roll) + clerk record for a parcel. BETA — county backfill in progress; many addresses will return an empty record until the county is onboarded.", "parameters": [ { "name": "address", "in": "query", "required": true, "description": "Street address to look up.", "schema": { "type": "string", "example": "123 Main St, Dallas, TX 75201" } }, { "name": "county", "in": "query", "required": false, "description": "County slug to scope the lookup (e.g. `dallas`, `tarrant`). Improves match accuracy.", "schema": { "type": "string", "example": "dallas" } } ], "responses": { "200": { "description": "Property record (or null record if not yet backfilled).", "content": { "application/json": { "example": { "address": "123 Main St, Dallas, TX 75201", "county": "dallas", "record": { "yearBuilt": 1998, "bedrooms": 3, "bathrooms": 2, "squareFootage": 1850, "lotSize": 0.19, "assessorId": "00123456000000000", "legalDescription": "LOT 12 BLK A OAK LAWN ADDITION", "subdivision": "OAK LAWN", "zoning": "R-1", "lastSaleDate": "2019-06-14", "hoaFee": null, "architectureType": "Traditional", "exteriorType": "Brick", "county": "dallas", "propertyType": "Single Family", "ownerName": "SMITH JOHN & JANE", "landValue": 45000, "improvementValue": 210000, "marketValue": 255000, "sourceId": "dallas_cad", "sourceUrl": "https://www.dallascad.org/", "fetchedAt": "2026-07-01T00:00:00Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/deeds": { "get": { "tags": ["Property"], "summary": "County deed index", "description": "Recorded deeds/instruments from a county clerk's grantor/grantee index. BETA.", "parameters": [ { "name": "county", "in": "query", "required": true, "description": "County slug (e.g. `dallas`).", "schema": { "type": "string", "example": "dallas" } }, { "name": "query", "in": "query", "required": true, "description": "Grantor/grantee name or address to search.", "schema": { "type": "string", "example": "123 Main St" } } ], "responses": { "200": { "description": "Matching deed records.", "content": { "application/json": { "example": { "county": "dallas", "query": "123 Main St", "count": 1, "deeds": [ { "instrumentNumber": "202100123456", "docType": "Warranty Deed", "recordedDate": "2019-06-14", "grantor": "DOE JANE", "grantee": "SMITH JOHN & JANE", "legalDescription": "LOT 12 BLK A OAK LAWN ADDITION", "county": "dallas", "sourceUrl": "https://dallas.tx.publicsearch.us/doc/202100123456" } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/liens": { "get": { "tags": ["Property"], "summary": "County lien index", "description": "Recorded liens (mechanic's, tax, judgment) from the same county clerk index as `/v1/deeds`. BETA.", "parameters": [ { "name": "county", "in": "query", "required": true, "description": "County slug (e.g. `dallas`).", "schema": { "type": "string", "example": "dallas" } }, { "name": "query", "in": "query", "required": true, "description": "Claimant name or address to search.", "schema": { "type": "string", "example": "123 Main St" } } ], "responses": { "200": { "description": "Matching lien records.", "content": { "application/json": { "example": { "county": "dallas", "query": "123 Main St", "count": 1, "liens": [ { "instrumentNumber": "202100987654", "lienType": "Mechanic's Lien", "filedDate": "2020-02-01", "amount": 4200.0, "claimant": "ACME ROOFING LLC", "released": true, "releaseInstrument": "202100991200", "county": "dallas" } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/congress-trades": { "get": { "tags": ["Government"], "summary": "U.S. House member stock-trade disclosures", "description": "Periodic Transaction Report (PTR) filings from U.S. House members. Note: these are stock-trade disclosures, not voting records or policy positions. Stable.", "parameters": [ { "$ref": "#/components/parameters/TickerParam" }, { "name": "member", "in": "query", "required": false, "description": "Case-insensitive substring match on member name.", "schema": { "type": "string", "example": "Pelosi" } }, { "name": "limit", "in": "query", "required": false, "description": "Cap the number of filings returned.", "schema": { "type": "integer", "example": 50 } } ], "responses": { "200": { "description": "Matching PTR filings.", "content": { "application/json": { "example": { "meta": { "source": "House Clerk / Periodic Transaction Reports", "sourceUrl": "https://disclosures-clerk.house.gov/", "method": "PDF-parsed PTR filings, normalized per-trade", "caveat": "Filed on a delay (up to 45 days); disclosure ranges are bucketed, not exact amounts.", "filingsScanned": 412, "filingsWithTrades": 96, "generatedAt": "2026-07-07T20:31:00.178Z" }, "count": 1, "filings": [ { "member": "Nancy Pelosi", "docId": "20026412", "year": 2026, "filedDate": "2026-06-20", "trades": [ { "ticker": "NVDA", "asset": "NVIDIA Corp", "type": "purchase", "date": "2026-05-30", "amountRange": "$1,000,001 - $5,000,000", "bundled": false } ] } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/insiders": { "get": { "tags": ["Government"], "summary": "SEC Form 4 insider transactions", "description": "Company-officer/director open-market buys and sells reported on SEC Form 4. Stable.", "parameters": [ { "$ref": "#/components/parameters/TickerParam" } ], "responses": { "200": { "description": "Insider filings for the ticker (or all covered companies if omitted).", "content": { "application/json": { "example": { "meta": { "generatedAt": "2026-07-07T20:31:00.178Z", "sourceUrl": "https://www.sec.gov/cgi-bin/browse-edgar?action=getcompany&type=4&owner=include", "caveat": "Open-market SELLS (code S) by executives are routinely driven by pre-scheduled 10b5-1 plans, tax withholding, and diversification, not a bearish view." }, "count": 1, "companies": [ { "ticker": "AAPL", "company": "Apple Inc.", "ceo": "Tim Cook", "filings": [ { "owner": "COOK TIMOTHY D", "title": "Chief Executive Officer", "date": "2026-04-02", "code": "S", "acquiredDisposed": "D", "shares": 4566, "price": 256, "value": 1168896, "accessionNumber": "0001140361-26-013190", "sourceUrl": "https://www.sec.gov/Archives/edgar/data/320193/000114036126013190/" } ] } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/donors": { "get": { "tags": ["Government"], "summary": "Corporate PAC → candidate contributions", "description": "Corporate PAC receipts/disbursements to federal candidates (FEC / cross-checked against OpenSecrets). NOT the same as company financials and not predictive of stock performance — a civic-transparency lane. Stable.", "parameters": [ { "$ref": "#/components/parameters/TickerParam" } ], "responses": { "200": { "description": "PAC contribution summary for the ticker (or all covered companies if omitted).", "content": { "application/json": { "example": { "meta": { "generatedAt": "2026-07-07", "sourceUrl": "https://api.open.fec.gov/v1/", "caveat": "PAC receipts/disbursements are NOT the same thing as company financials and are NOT predictive of stock performance." }, "count": 1, "companies": [ { "name": "Microsoft Corporation", "ticker": "MSFT", "pacName": "Microsoft Corporation Stakeholders Voluntary PAC (MSVPAC)", "committeeId": "C00227546", "cycle": "2024", "totalContributionsUsd": 2061317, "demPct": 50, "repPct": 48.8, "note": "demPct/repPct = split of contributions to federal candidates." } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/contracts": { "get": { "tags": ["Government"], "summary": "Federal contract obligations", "description": "Federal contract award obligations from USASpending.gov (FY2024-present window). Stable.", "parameters": [ { "$ref": "#/components/parameters/TickerParam" } ], "responses": { "200": { "description": "Contract obligation summary for the ticker (or all covered companies if omitted).", "content": { "application/json": { "example": { "meta": { "generatedAt": "2026-07-07T21:12:04.550Z", "sourceUrl": "https://api.usaspending.gov/api/v2/search/spending_by_award/", "caveat": "award_type_codes A/B/C/D (definitive contract, BPA call, purchase order, delivery order), FY2024-FY2026-YTD window." }, "count": 1, "companies": [ { "name": "Apple", "ticker": "AAPL", "totalObligatedUsd": 73651.3, "awardCount": 18, "topAwards": [ { "amount": 127387.15, "agency": "Department of the Interior", "description": "IPADS AND ACCESSORIES FOR PINE RIDGE SCHOOL", "date": "2020-09-11" } ] } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/lobbying": { "get": { "tags": ["Government"], "summary": "Senate LDA lobbying disclosures", "description": "Quarterly Lobbying Disclosure Act filings pulled from lda.senate.gov. Stable.", "parameters": [ { "$ref": "#/components/parameters/TickerParam" } ], "responses": { "200": { "description": "Lobbying spend summary for the ticker (or all covered companies if omitted).", "content": { "application/json": { "example": { "meta": { "generatedAt": "2026-07-07T21:16:27.264Z", "sourceUrl": "https://lda.senate.gov/api/v1/filings/", "caveat": "totalSpendUsd/quarters sum every LDA quarterly filing found for client_name, filing_year 2025/2026." }, "count": 1, "companies": [ { "name": "Apple", "ticker": "AAPL", "year": 2025, "totalSpendUsd": 13630000, "filingCount": 40, "quarters": [ { "period": "2025-Q1", "amount": 3210000 }, { "period": "2025-Q2", "amount": 3100000 } ] } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/patents": { "get": { "tags": ["Government"], "summary": "Patent grants", "description": "Granted-patent counts from the USPTO Open Data Portal, matched on first-applicant name. Stable.", "parameters": [ { "$ref": "#/components/parameters/TickerParam" } ], "responses": { "200": { "description": "Patent grant summary for the ticker (or all covered companies if omitted).", "content": { "application/json": { "example": { "meta": { "generatedAt": "2026-07-07T00:00:00Z", "sourceUrl": "https://api.uspto.gov/api/v1/patent/applications/search", "caveat": "firstApplicantName single-entity counts — a company filing through subsidiaries under different names may be undercounted." }, "count": 1, "companies": [ { "name": "Apple", "ticker": "AAPL", "assigneeMatched": "Apple Inc.", "grantedLast12mo": 3471, "grantedPrior12mo": 3491, "note": "Live USPTO Open Data Portal count, single-entity match." } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/edgar-search": { "get": { "tags": ["Government"], "summary": "SEC EDGAR full-text search", "description": "Full-text search across every SEC filing indexed since 2001 (EDGAR FTS). Stable.", "parameters": [ { "name": "q", "in": "query", "required": true, "description": "Full-text search query.", "schema": { "type": "string", "example": "data breach" } }, { "name": "forms", "in": "query", "required": false, "description": "Comma-separated form types to filter (e.g. `10-K,8-K`).", "schema": { "type": "string", "example": "10-K,8-K" } }, { "name": "from", "in": "query", "required": false, "description": "ISO date lower bound (inclusive), `YYYY-MM-DD`.", "schema": { "type": "string", "format": "date", "example": "2025-01-01" } }, { "name": "to", "in": "query", "required": false, "description": "ISO date upper bound (inclusive), `YYYY-MM-DD`.", "schema": { "type": "string", "format": "date", "example": "2026-07-07" } }, { "name": "limit", "in": "query", "required": false, "description": "Cap the number of hits returned. Max 100.", "schema": { "type": "integer", "example": 20 } } ], "responses": { "200": { "description": "Matching filings.", "content": { "application/json": { "example": { "query": "data breach", "total": 3841, "count": 1, "hits": [ { "form": "8-K", "filedDate": "2026-05-14", "entity": "Acme Corp", "cik": "0000123456", "accession": "0001234567-26-000123", "url": "https://www.sec.gov/Archives/edgar/data/123456/000123456726000123/" } ] } } } }, "400": { "description": "Missing `q` param.", "content": { "application/json": { "example": { "error": "q query param required" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/sam-entities": { "get": { "tags": ["Government"], "summary": "SAM.gov federal contractor registrations", "description": "Active/inactive federal contractor entity registrations from SAM.gov. Stable.", "parameters": [ { "name": "q", "in": "query", "required": false, "description": "Legal business name to search.", "schema": { "type": "string", "example": "Acme Corp" } }, { "name": "uei", "in": "query", "required": false, "description": "Unique Entity Identifier (SAM.gov, replaces DUNS).", "schema": { "type": "string", "example": "ZQGGHJH74DW7" } }, { "name": "limit", "in": "query", "required": false, "description": "Cap the number of entities returned. Max 50.", "schema": { "type": "integer", "example": 20 } } ], "responses": { "200": { "description": "Matching entity registrations.", "content": { "application/json": { "example": { "query": "Acme Corp", "total": 1, "count": 1, "entities": [ { "name": "ACME CORP", "uei": "ZQGGHJH74DW7", "cageCode": "1ABC2", "status": "Active", "registrationDate": "2019-03-11", "expirationDate": "2027-03-11", "city": "Dallas", "state": "TX", "country": "USA", "businessTypes": ["Small Business", "Corporate Entity (Not Tax Exempt)"] } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/senate-trades": { "get": { "tags": ["Government"], "summary": "U.S. Senate member stock-trade disclosures", "description": "Periodic Transaction Report (PTR) filings from U.S. Senate members (eFD). BETA — OCR pipeline pending; coverage and field accuracy are still being validated.", "parameters": [ { "$ref": "#/components/parameters/TickerParam" }, { "name": "member", "in": "query", "required": false, "description": "Case-insensitive substring match on member name.", "schema": { "type": "string", "example": "Warner" } }, { "name": "limit", "in": "query", "required": false, "description": "Cap the number of filings returned.", "schema": { "type": "integer", "example": 50 } } ], "responses": { "200": { "description": "Matching PTR filings.", "content": { "application/json": { "example": { "meta": { "source": "U.S. Senate eFD / Periodic Transaction Reports", "sourceUrl": "https://efdsearch.senate.gov/search/", "method": "OCR-parsed PTR filings, normalized per-trade", "caveat": "BETA — OCR pipeline pending; disclosure ranges are bucketed, not exact amounts.", "generatedAt": "2026-07-07T20:31:00.178Z" }, "count": 1, "filings": [ { "member": "Mark Warner", "chamber": "Senate", "docId": "20026488", "year": 2026, "filedDate": "2026-06-22", "trades": [ { "ticker": "NVDA", "asset": "NVIDIA Corp", "type": "sale", "date": "2026-06-02", "amountRange": "$15,001 - $50,000" } ] } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/predictions": { "get": { "tags": ["Markets"], "summary": "In-house strategy backtest rows", "description": "Rolling-window strategy predictions vs. realized returns and SPY benchmark, from the bengarrard trading strategy engine. Stable.", "parameters": [ { "name": "open", "in": "query", "required": false, "description": "Filter to open (`true`) or closed (`false`) windows.", "schema": { "type": "boolean" } }, { "name": "limit", "in": "query", "required": false, "description": "Cap the number of rows returned.", "schema": { "type": "integer", "example": 25 } } ], "responses": { "200": { "description": "Strategy prediction rows + aggregate score.", "content": { "application/json": { "example": { "asOf": "2026-07-07", "dataEnd": "2026-07-07", "rows": [ { "windowStart": "2026-06-18", "windowEnd": "2026-07-07", "chosenId": "opus-tsmom-xle", "chosenLabel": "Claude Opus (Macro) — Time-series momentum (12-1) — energy sector", "pool": "trend-preferred", "trailingScore": 1.44422, "predictedLong": true, "realizedReturnPct": -2.11619, "spyReturnPct": 1.654, "open": true, "firstLoggedAt": "2026-07-07", "backfilled": false } ], "score": { "totalWindows": 87, "liveClosed": 0, "liveOpen": 1, "backfilled": 86, "hitRate": null, "beatSpyRate": null, "cumulativeReturnPct": null, "cumulativeSpyPct": null } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/prices": { "get": { "tags": ["Markets"], "summary": "Daily close price series", "description": "5-year daily close series for the covered ticker universe (equities, sector ETFs, majors, and top crypto). Stable.", "parameters": [ { "name": "ticker", "in": "query", "required": false, "description": "Ticker symbol. Omit to list all covered tickers.", "schema": { "type": "string", "example": "NVDA" } }, { "name": "from", "in": "query", "required": false, "description": "ISO date lower bound (inclusive).", "schema": { "type": "string", "format": "date", "example": "2025-01-01" } }, { "name": "to", "in": "query", "required": false, "description": "ISO date upper bound (inclusive).", "schema": { "type": "string", "format": "date", "example": "2026-07-07" } } ], "responses": { "200": { "description": "Ticker list (no `ticker` param) or a close-price series (`ticker` given).", "content": { "application/json": { "examples": { "tickerList": { "summary": "No ticker given", "value": { "tickers": ["SPY", "QQQ", "AAPL", "NVDA", "BTC-USD", "MSFT", "GOOGL", "AMZN", "META", "TSLA"], "note": "Pass ?ticker= for a daily close series." } }, "series": { "summary": "ticker=NVDA", "value": { "ticker": "NVDA", "count": 1254, "series": [ { "date": "2021-07-07", "close": 20.3252 }, { "date": "2021-07-08", "close": 20.41 } ] } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/institutional-holdings": { "get": { "tags": ["Markets"], "summary": "SEC 13F institutional filer holdings", "description": "Quarterly Form 13F holdings for an institutional investment manager — hedge funds, RIAs, and other filers with $100M+ in qualifying assets. Stable.", "parameters": [ { "name": "cik", "in": "query", "required": false, "description": "Filer CIK (10-digit, zero-padded).", "schema": { "type": "string", "example": "0001067983" } }, { "name": "q", "in": "query", "required": false, "description": "Filer name to search (used when `cik` is omitted).", "schema": { "type": "string", "example": "Berkshire Hathaway" } } ], "responses": { "200": { "description": "Latest 13F holdings for the matched filer.", "content": { "application/json": { "example": { "cik": "0001067983", "filer": "BERKSHIRE HATHAWAY INC", "filedDate": "2026-05-15", "accession": "0000950123-26-005678", "form": "13F-HR", "count": 1, "totalValueUsd": 312450000000, "truncated": false, "holdings": [ { "nameOfIssuer": "APPLE INC", "cusip": "037833100", "valueUsd": 174200000000, "shares": 915560382, "putCall": null } ] } } } }, "400": { "description": "Missing `cik` or `q` param.", "content": { "application/json": { "example": { "error": "cik or q query param required" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/execs": { "get": { "tags": ["Markets"], "summary": "Corporate executive + board rosters", "description": "Officer/director rosters derived from SEC Form 4 reporting-owner metadata — name, titles, and filing recency per company. Stable.", "parameters": [ { "$ref": "#/components/parameters/TickerParam" }, { "name": "limit", "in": "query", "required": false, "description": "Cap the number of companies returned.", "schema": { "type": "integer", "example": 25 } } ], "responses": { "200": { "description": "Executive/board roster for the ticker (or all covered companies if omitted).", "content": { "application/json": { "example": { "count": 1, "companies": [ { "ticker": "AAPL", "company": "Apple Inc.", "ceo": "Tim Cook", "execs": [ { "name": "COOK TIMOTHY D", "titles": "Chief Executive Officer, Director", "filingCount": 42, "lastFilingDate": "2026-04-02", "lastCode": "S" } ] } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" } } } } } }