# 3spread > Machine-readable SEC filing data for financial analysis, screening, and research. The 3spread API transforms raw EDGAR filings into typed structured datasets (financial statements, ratios, holdings tables, compensation data) and categorized textual sections (MD&A, risk factors, business descriptions, CD&A). 3spread is built for programmatic and LLM consumption. Every endpoint ships with a typed schema, deterministic JSON responses, and consistent labels across filers — so the same data point gets the same key whether it came from Apple's 10-K or a small-cap shell company's. Coverage spans 15,000+ SEC filers, back to 2012, across 30+ filing types. New filings are processed and available through the API in seconds. ## Key URLs - **Marketing site**: https://3spread.com - **Interactive API reference**: https://3spread.com/docs - **Filings catalog**: https://3spread.com/docs/home - **OpenAPI spec (JSON)**: https://3spread.com/docs/openapi.json - **This file (markdown spec)**: https://3spread.com/llms.txt - **Pricing**: https://3spread.com/pricing - **Sign up**: https://3spread.com/auth/signup - **Contact**: https://3spread.com/contact ## Pricing tiers - **Individual** — Free during beta. All available datasets, standard rate limits. Personal research and analysis. - **Startup** — Free to start, flexible terms as you scale. Internal business use + redistribution, elevated rate limits, bulk exports, priority support. - **Business** — Custom pricing. Internal analytics, compliance, redistribution, or custom integrations. Custom rate limits + delivery formats, SLA-backed support. ## Filings catalog Filing types are organized by release status. **Available** filings are live with stable schemas and production data. **Closed Testing** filings have final schemas in private preview. **Under Development** filings are being designed. ### Available - **Periodic Reports** — Periodic financial filings — annual (10-K) and quarterly (10-Q) reports. - **Filings** — Cross-cutting master filings index. - **Insiders** — Forms 3, 4, 5 — insider beneficial ownership filings. - **Institutional Holdings** — Form 13F — institutional investment manager quarterly holdings reports. - **Private Offerings** — Form D — Regulation D exempt offering notices. - **Fund Portfolios** — Form N-PORT — registered investment company monthly portfolio holdings. - **Money Market Funds** — Form N-MFP2 — money market fund monthly portfolio reports. - **Beneficial Ownership** — Schedule 13D / 13G — 5%+ beneficial ownership reports. - **Proposed Sales** — Form 144 — notice of proposed sale of restricted or control securities under Rule 144. - **Fund Census** — Form N-CEN — annual investment company census reports. - **Proxy Votes** — Form N-PX — annual proxy voting record reports. - **Reg A+ Offerings** — Regulation A+ offerings — Forms 1-A / 1-K / 1-U / 1-Z. - **Narratives** — Registration-statement prospectus textual sections — S-1 / S-3 / S-3ASR / S-4 / S-11 / F-1 / F-3 / F-4 (and amendments). - **Health** — Liveness and readiness probes. - **Entities** — Master CIK directory backed by `vw_api_entities`. - **Securities** — Identifier resolver — accepts CUSIP, ISIN, ticker, or CIK and returns the canonical cross-reference (cik, company_name, tickers, cusip, isin, lei) plus optional registry enrichment when the resolved CIK has metadata on file. - **Coverage** — Trust-and-discovery endpoints answering "what does 3spread know?" — per-issuer coverage matrix, global per-family aggregates, stale-issuer detection, filing-intake histogram, and per-family freshness snapshot. - **Changes** — Per-family changefeed over `accepted_time`. ### Derived Signals - **Insider Signals** — Form 4-derived analytics: cluster detection (≥N insiders / M-day windows), trade classification (discretionary / plan / tax), and a daily-refreshed conviction index per company with a cross-sectional leaderboard. - **13F Analytics** — 13F-derived analytics: amendment-aware manager position resolution, per-security holder concentration with a most-crowded leaderboard, new/exit/resize flows by manager or security, and a manager-stance classifier (passive 13G vs. - **Cross-Holder Views** — Inverse holdings indexes spanning multiple form families. - **Activism & Governance** — Detection products built on Schedule 13D / 13G filings. - **Capital Markets** — Macro-level fundraising and funding indexes derived from exempt-offering and money-market filings. - **Leaderboards** — Pre-computed rankings over the live filing data — top issuers by insider buy/sell volume, largest Form D offerings, most-active and most-amended filers per family, and the composite governance-pressure leaderboard. - **Network** — Graph-flavored aggregations over the filing data: director interlocks (issuer-set per insider) from Form 3/4/5, and recurring co-filer pairs from Schedule 13D/G `reporting_persons`. - **Rollups** — Sector-level aggregations: Form D private-capital money-map by industry, and Form 4 insider sentiment rolled up by SIC. - **Composite Signals** — Cross-signal intersections — the contrarian "insiders buying what funds aren't" view joining bullish insider-conviction leaders to low-end 13F crowding, with more intersections to follow as the signal layer grows. ### Closed Testing - **S-8** — S-8 Employee Benefit Plan Registration Filing types: `S-8`, `S-8 POS` Category: Registration Statements > This dataset is not yet released. ### Under Development - **8-K** — 8-K Current Reports Filing types: `8-K`, `8-K/A` Category: Annual & Periodic Reports > This dataset is not yet released. - **Schedule 14A** — Schedule 14A Proxy Statement (incl. - **Schedule 14C** — Schedule 14C Information Statement Filing types: `DEF 14C`, `PRE 14C` Category: Proxy & Shareholder > This dataset is not yet released. - **Schedule 14D** — Schedule 14D Tender Offer Statement Filing types: `SC 14D9`, `SC TO-I`, `SC TO-T`, `SC TO-C`, `SC 13E3` Category: Proxy & Shareholder > This dataset is not yet released. - **20-F** — 20-F Foreign Issuer Annual Report Filing types: `20-F`, `20-F/A` Category: Foreign Issuers > This dataset is not yet released. - **6-K** — 6-K Foreign Issuer Current Report Filing types: `6-K`, `6-K/A` Category: Foreign Issuers > This dataset is not yet released. - **N-1A** — N-1A Mutual Fund Registration Filing types: `N-1A`, `N-1A/A` Category: Investment Funds > This dataset is not yet released. - **N-CSR** — N-CSR Certified Shareholder Report Filing types: `N-CSR`, `N-CSR/A` Category: Investment Funds > This dataset is not yet released. - **24F-2** — 24F-2 Registration Fee Calculation Filing types: `24F-2` Category: Investment Funds > This dataset is not yet released. - **N-2** — N-2 Closed-End Fund Registration Filing types: `N-2`, `N-2/A` Category: Investment Funds > This dataset is not yet released. - **Form PF** — Form PF Private Fund Adviser Report Filing types: `Form PF` Category: Fund & Adviser > This dataset is not yet released. - **Form ADV** — Form ADV Investment Adviser Registration Filing types: `Form ADV` Category: Fund & Adviser > This dataset is not yet released. - **S-6** — S-6 Unit Investment Trust Registration Filing types: `S-6`, `S-6/A` Category: Fund & Adviser > This dataset is not yet released. - **Form U-4** — Form U-4 Broker-Dealer / Investment Adviser Representative Filing types: `Form U-4` Category: Fund & Adviser > This dataset is not yet released. ## Authentication All API requests require an API key passed in the `apikey` HTTP header. Get your key at https://3spread.com/account after signing up. ```bash curl -H "apikey: YOUR_KEY" https://api.3spread.com/api/v1/statements?ticker=AAPL ``` --- # API Reference The remainder of this file is the full OpenAPI 3.1 spec rendered as markdown. Source of truth: https://3spread.com/docs/openapi.json. Use the operation listings below for parameters, request shapes, and response schemas. # 3spread API - **OpenAPI Version:** `3.1.0` - **API Version:** `0.1.0` Machine-readable SEC filing data for financial analysis, screening, and research. The 3spread API transforms raw EDGAR filings into typed structured datasets (financial statements, ratios, holdings tables, compensation data) and categorized textual sections (MD\&A, risk factors, business descriptions, CD\&A). **New here?** Browse the **Getting Started** section in the sidebar for a quick-start request, authentication details, response conventions, and an explanation of the four release-status tiers (Available, Closed Testing, Under Development). ## Servers - **URL:** `https://api.3spread.com` - **Description:** Production API ## Operations ### Health Check - **Method:** `GET` - **Path:** `/api/v1/health` - **Tags:** Health Enhanced health check with dependency status. Returns overall service health based on critical dependencies: - healthy: All dependencies available - degraded: Service running but some dependencies unavailable - down: Critical dependencies unavailable Returns: { "status": "healthy" | "degraded" | "down", "service": str, "version": str, "timestamp": str, "checks": { "database": bool, "nhost\_database": bool, "apisix\_admin": bool } } #### Responses ##### Status: 200 Successful Response ###### Content-Type: application/json - **`checks` (required)** `object` — Dependency check results - **`service` (required)** `string` — Service name - **`status` (required)** `string`, possible values: `"healthy", "degraded", "down"` — Overall health status - **`timestamp` (required)** `string` — ISO 8601 timestamp (UTC) - **`version` (required)** `string` — Service version - **`data_as_of`** `object` — Latest reporting period present in each major filing family. Null if the freshness probe was skipped (e.g. database unavailable). Helps clients detect ETL staleness without a per-family probe. **Example:** ```json { "checks": { "apisix_admin": true, "database": true, "nhost_database": true }, "data_as_of": { "form_13f_latest_period": "2022-12-31" }, "service": "Tatooine API", "status": "healthy", "timestamp": "2024-10-28T12:00:00Z", "version": "1.0.0" } ``` ##### Status: 401 Authentication failed - missing or invalid API key ###### Content-Type: application/json - **`message`** `string` **Example:** ```json { "message": "Missing API key in request" } ``` ##### Status: 429 Rate limit exceeded for your tier ###### Content-Type: application/json - **`message`** `string` **Example:** ```json { "message": "" } ``` ##### Status: 500 Unhandled server error — file an issue with the request\_id from the error envelope. ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 502 Upstream dependency failed — gateway, key store, or downstream service unavailable. ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 503 Database query error or timeout — retry with backoff ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ### Readiness Check - **Method:** `GET` - **Path:** `/api/v1/health/ready` - **Tags:** Health Readiness check with database connectivity #### Responses ##### Status: 200 Successful Response ###### Content-Type: application/json - **`database` (required)** `string`, possible values: `"connected", "disconnected"` — Database connection status - **`service` (required)** `string` — Service name - **`status` (required)** `string`, possible values: `"ready", "not ready"` — Readiness status - **`version` (required)** `string` — Service version - **`error`** `object` — Error message if not ready **Example:** ```json { "database": "connected", "service": "Tatooine API", "status": "ready", "version": "1.0.0" } ``` ##### Status: 401 Authentication failed - missing or invalid API key ###### Content-Type: application/json - **`message`** `string` **Example:** ```json { "message": "Missing API key in request" } ``` ##### Status: 429 Rate limit exceeded for your tier ###### Content-Type: application/json - **`message`** `string` **Example:** ```json { "message": "" } ``` ##### Status: 500 Unhandled server error — file an issue with the request\_id from the error envelope. ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 502 Upstream dependency failed — gateway, key store, or downstream service unavailable. ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 503 Database query error or timeout — retry with backoff ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ### Get financial statements - **Method:** `GET` - **Path:** `/api/v1/statements` - **Tags:** Periodic Reports Retrieve financial statements with comprehensive filtering options. **Required:** at least one of `cik` or `ticker`. Returns `400 MISSING_PARAMETER` otherwise. **Key Features:** - Auto-filters to latest filing version (handles restatements automatically) - Supports both fiscal period AND date range filtering - Filter by ticker OR CIK - Optional metadata-only mode (exclude statement JSON for faster responses) **Example Uses:** - All Apple statements for 2024: `?cik=0000320193&fiscal_year=2024` - Apple Q1 2024 balance sheets: `?ticker=AAPL&fiscal_year=2024&fiscal_quarter=1&statement_type=bs` - Statements in date range: `?cik=0000320193&start_date=2024-01-01&end_date=2024-06-30` - Metadata only (fast): `?cik=0000320193&include_statement=false` #### Responses ##### Status: 200 Successful Response ###### Content-Type: application/json - **`data` (required)** `array` — Array of statements **Items:** - **`accession_num` (required)** `object` — EDGAR accession number derived from filing\_id (e.g., '0000320193-24-000123') - **`block_id` (required)** `string` — Unique statement identifier (UUID) - **`cik` (required)** `string` — SEC Central Index Key (10 digits) - **`filing_id` (required)** `string` — Unique filing identifier - **`fiscal_quarter` (required)** `integer` — Fiscal quarter: 0=FY, 1-4=quarters - **`fiscal_year` (required)** `integer` — Fiscal year the statement covers - **`source_url` (required)** `object` — Canonical SEC EDGAR Archives URL pointing at the filing's index page - **`statement_type` (required)** `string` — Statement type: 'inc', 'bs', 'cf' - **`company_name`** `object` — Company name - **`is_comparative`** `object` — Whether this is comparative data - **`period_label`** `object` — Human-readable label (e.g., 'Q1', 'FY') - **`period_length`** `object` — Period length in months - **`period_type`** `object` — Period type: 'quarterly' or 'annual' - **`statement`** `object` — Complete financial statement JSON (omitted if include\_statement=false) - **`statement_date`** `object` — Statement period end date - **`tickers`** `object` — Ticker symbols - **`page_size` (required)** `integer` — Results per page - **`page`** `integer`, default: `1` — Current page number (1-indexed) - **`total`** `integer`, default: `0` — Total count of matching statements - **`total_pages`** `integer`, default: `1` — Total number of pages **Example:** ```json { "data": [ { "block_id": "550e8400-e29b-41d4-a716-446655440000", "cik": "0000320193", "company_name": "Apple Inc.", "filing_id": "0000320193_0000320193-24-000123", "fiscal_quarter": 1, "fiscal_year": 2024, "is_comparative": false, "period_label": "Q1", "period_type": "quarterly", "statement": { "Assets": 360836000000, "Liabilities": 279281000000 }, "statement_date": "2024-03-30T00:00:00Z", "statement_type": "bs", "tickers": [ "AAPL" ] } ], "page": 1, "page_size": 50, "total": 45, "total_pages": 1 } ``` ##### Status: 400 Request rejected — usually a missing required parameter or an at-least-one-of constraint not satisfied. ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 401 Authentication failed - missing or invalid API key ###### Content-Type: application/json - **`message`** `string` **Example:** ```json { "message": "Missing API key in request" } ``` ##### Status: 422 Request validation failed - invalid or missing parameters ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 429 Rate limit exceeded for your tier ###### Content-Type: application/json - **`message`** `string` **Example:** ```json { "message": "" } ``` ##### Status: 500 Unhandled server error — file an issue with the request\_id from the error envelope. ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 502 Upstream dependency failed — gateway, key store, or downstream service unavailable. ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 503 Database query error or timeout — retry with backoff ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ### List available entities - **Method:** `GET` - **Path:** `/api/v1/statements/entities` - **Tags:** Periodic Reports Get a list of all companies/entities that have financial statement data available. Returns summary information for each entity including: - Company identifiers (CIK, name, tickers) - Total statement count - Fiscal year range (earliest to latest data) - Available statement types (bs, inc, cf) **Example Uses:** - List all entities: `/statements/entities` - Search for Apple: `/statements/entities?search=AAPL` - Paginate results: `/statements/entities?limit=50&offset=100` **See also:** `/api/v1/entities/{cik}` for the registry-level profile (SIC, exchanges, EIN, LEI, filer status flags) of any entity returned here, and `/api/v1/companies` for a registry-wide directory not limited to entities with statement data. #### Responses ##### Status: 200 Successful Response ###### Content-Type: application/json - **`data` (required)** `array` — Array of entities **Items:** - **`cik` (required)** `string` — SEC Central Index Key - **`fiscal_year_max` (required)** `integer` — Latest fiscal year with data - **`fiscal_year_min` (required)** `integer` — Earliest fiscal year with data - **`statement_count` (required)** `integer` — Total number of statements available - **`statement_types` (required)** `array` — Available statement types (e.g., \['bs', 'inc', 'cf']) **Items:** `string` - **`company_name`** `object` — Company name - **`tickers`** `object` — Ticker symbols - **`page` (required)** `integer` — Current page number (1-indexed) - **`page_size` (required)** `integer` — Results per page - **`total` (required)** `integer` — Total count of matching entities - **`total_pages` (required)** `integer` — Total number of pages **Example:** ```json { "data": [ { "cik": "320193", "company_name": "Apple Inc.", "fiscal_year_max": 2024, "fiscal_year_min": 2020, "statement_count": 45, "statement_types": [ "bs", "inc", "cf" ], "tickers": [ "AAPL" ] } ], "page": 1, "page_size": 100, "total": 5000, "total_pages": 50 } ``` ##### Status: 401 Authentication failed - missing or invalid API key ###### Content-Type: application/json - **`message`** `string` **Example:** ```json { "message": "Missing API key in request" } ``` ##### Status: 422 Request validation failed - invalid or missing parameters ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 429 Rate limit exceeded for your tier ###### Content-Type: application/json - **`message`** `string` **Example:** ```json { "message": "" } ``` ##### Status: 500 Unhandled server error — file an issue with the request\_id from the error envelope. ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 502 Upstream dependency failed — gateway, key store, or downstream service unavailable. ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 503 Database query error or timeout — retry with backoff ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ### Get latest statements by CIK - **Method:** `GET` - **Path:** `/api/v1/statements/latest/cik/{cik}` - **Tags:** Periodic Reports Get the most recent statement of each type (balance sheet, income statement, cash flow) for a company identified by CIK. Returns the latest financial snapshot regardless of fiscal period. #### Responses ##### Status: 200 Successful Response ###### Content-Type: application/json - **`cik` (required)** `string` — Company CIK - **`balance_sheet`** `object` — Most recent balance sheet - **`cash_flow`** `object` — Most recent cash flow statement - **`company_name`** `object` — Company name - **`income_statement`** `object` — Most recent income statement - **`tickers`** `object` — Ticker symbols **Example:** ```json { "balance_sheet": { "block_id": "...", "fiscal_year": 2024, "statement_type": "bs" }, "cash_flow": { "block_id": "...", "fiscal_year": 2024, "statement_type": "cf" }, "cik": "0000320193", "company_name": "Apple Inc.", "income_statement": { "block_id": "...", "fiscal_year": 2024, "statement_type": "inc" }, "tickers": [ "AAPL" ] } ``` ##### Status: 401 Authentication failed - missing or invalid API key ###### Content-Type: application/json - **`message`** `string` **Example:** ```json { "message": "Missing API key in request" } ``` ##### Status: 404 Resource not found ###### Content-Type: application/json - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } ``` ##### Status: 422 Request validation failed - invalid or missing parameters ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 429 Rate limit exceeded for your tier ###### Content-Type: application/json - **`message`** `string` **Example:** ```json { "message": "" } ``` ##### Status: 500 Unhandled server error — file an issue with the request\_id from the error envelope. ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 502 Upstream dependency failed — gateway, key store, or downstream service unavailable. ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 503 Database query error or timeout — retry with backoff ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ### Get latest statements by ticker - **Method:** `GET` - **Path:** `/api/v1/statements/latest/ticker/{ticker}` - **Tags:** Periodic Reports Get the most recent statement of each type (balance sheet, income statement, cash flow) for a company identified by ticker symbol. Returns the latest financial snapshot regardless of fiscal period. #### Responses ##### Status: 200 Successful Response ###### Content-Type: application/json - **`cik` (required)** `string` — Company CIK - **`balance_sheet`** `object` — Most recent balance sheet - **`cash_flow`** `object` — Most recent cash flow statement - **`company_name`** `object` — Company name - **`income_statement`** `object` — Most recent income statement - **`tickers`** `object` — Ticker symbols **Example:** ```json { "balance_sheet": { "block_id": "...", "fiscal_year": 2024, "statement_type": "bs" }, "cash_flow": { "block_id": "...", "fiscal_year": 2024, "statement_type": "cf" }, "cik": "0000320193", "company_name": "Apple Inc.", "income_statement": { "block_id": "...", "fiscal_year": 2024, "statement_type": "inc" }, "tickers": [ "AAPL" ] } ``` ##### Status: 401 Authentication failed - missing or invalid API key ###### Content-Type: application/json - **`message`** `string` **Example:** ```json { "message": "Missing API key in request" } ``` ##### Status: 404 Resource not found ###### Content-Type: application/json - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } ``` ##### Status: 422 Request validation failed - invalid or missing parameters ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 429 Rate limit exceeded for your tier ###### Content-Type: application/json - **`message`** `string` **Example:** ```json { "message": "" } ``` ##### Status: 500 Unhandled server error — file an issue with the request\_id from the error envelope. ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 502 Upstream dependency failed — gateway, key store, or downstream service unavailable. ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 503 Database query error or timeout — retry with backoff ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ### Get statement by ID - **Method:** `GET` - **Path:** `/api/v1/statements/{block_id}` - **Tags:** Periodic Reports Retrieve a single financial statement by its block\_id. #### Responses ##### Status: 200 Successful Response ###### Content-Type: application/json - **`accession_num` (required)** `object` — EDGAR accession number derived from filing\_id (e.g., '0000320193-24-000123') - **`block_id` (required)** `string` — Unique statement identifier (UUID) - **`cik` (required)** `string` — SEC Central Index Key (10 digits) - **`filing_id` (required)** `string` — Unique filing identifier - **`fiscal_quarter` (required)** `integer` — Fiscal quarter: 0=FY, 1-4=quarters - **`fiscal_year` (required)** `integer` — Fiscal year the statement covers - **`source_url` (required)** `object` — Canonical SEC EDGAR Archives URL pointing at the filing's index page - **`statement_type` (required)** `string` — Statement type: 'inc', 'bs', 'cf' - **`company_name`** `object` — Company name - **`is_comparative`** `object` — Whether this is comparative data - **`period_label`** `object` — Human-readable label (e.g., 'Q1', 'FY') - **`period_length`** `object` — Period length in months - **`period_type`** `object` — Period type: 'quarterly' or 'annual' - **`statement`** `object` — Complete financial statement JSON (omitted if include\_statement=false) - **`statement_date`** `object` — Statement period end date - **`tickers`** `object` — Ticker symbols **Example:** ```json { "block_id": "550e8400-e29b-41d4-a716-446655440000", "cik": "0000320193", "company_name": "Apple Inc.", "filing_id": "0000320193_0000320193-24-000123", "fiscal_quarter": 1, "fiscal_year": 2024, "is_comparative": false, "period_label": "Q1", "period_type": "quarterly", "statement": { "Assets": 360836000000, "Liabilities": 279281000000, "Stockholders' Equity": 81555000000 }, "statement_date": "2024-03-30T00:00:00Z", "statement_type": "bs", "tickers": [ "AAPL" ] } ``` ##### Status: 401 Authentication failed - missing or invalid API key ###### Content-Type: application/json - **`message`** `string` **Example:** ```json { "message": "Missing API key in request" } ``` ##### Status: 404 Resource not found ###### Content-Type: application/json - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } ``` ##### Status: 422 Request validation failed - invalid or missing parameters ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 429 Rate limit exceeded for your tier ###### Content-Type: application/json - **`message`** `string` **Example:** ```json { "message": "" } ``` ##### Status: 500 Unhandled server error — file an issue with the request\_id from the error envelope. ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 502 Upstream dependency failed — gateway, key store, or downstream service unavailable. ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 503 Database query error or timeout — retry with backoff ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ### Get statements by filing - **Method:** `GET` - **Path:** `/api/v1/statements/filing/{filing_id}` - **Tags:** Periodic Reports Retrieve all financial statements for a specific SEC filing. Typically returns 3 statements (income, balance sheet, cash flow) unless filtered. #### Responses ##### Status: 200 Successful Response ###### Content-Type: application/json **Array of:** - **`accession_num` (required)** `object` — EDGAR accession number derived from filing\_id (e.g., '0000320193-24-000123') - **`block_id` (required)** `string` — Unique statement identifier (UUID) - **`cik` (required)** `string` — SEC Central Index Key (10 digits) - **`filing_id` (required)** `string` — Unique filing identifier - **`fiscal_quarter` (required)** `integer` — Fiscal quarter: 0=FY, 1-4=quarters - **`fiscal_year` (required)** `integer` — Fiscal year the statement covers - **`source_url` (required)** `object` — Canonical SEC EDGAR Archives URL pointing at the filing's index page - **`statement_type` (required)** `string` — Statement type: 'inc', 'bs', 'cf' - **`company_name`** `object` — Company name - **`is_comparative`** `object` — Whether this is comparative data - **`period_label`** `object` — Human-readable label (e.g., 'Q1', 'FY') - **`period_length`** `object` — Period length in months - **`period_type`** `object` — Period type: 'quarterly' or 'annual' - **`statement`** `object` — Complete financial statement JSON (omitted if include\_statement=false) - **`statement_date`** `object` — Statement period end date - **`tickers`** `object` — Ticker symbols **Example:** ```json [ { "block_id": "550e8400-e29b-41d4-a716-446655440000", "cik": "0000320193", "company_name": "Apple Inc.", "filing_id": "0000320193_0000320193-24-000123", "fiscal_quarter": 1, "fiscal_year": 2024, "is_comparative": false, "period_label": "Q1", "period_type": "quarterly", "statement": { "Assets": 360836000000, "Liabilities": 279281000000, "Stockholders' Equity": 81555000000 }, "statement_date": "2024-03-30T00:00:00Z", "statement_type": "bs", "tickers": [ "AAPL" ] } ] ``` ##### Status: 401 Authentication failed - missing or invalid API key ###### Content-Type: application/json - **`message`** `string` **Example:** ```json { "message": "Missing API key in request" } ``` ##### Status: 404 Resource not found ###### Content-Type: application/json - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } ``` ##### Status: 422 Request validation failed - invalid or missing parameters ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 429 Rate limit exceeded for your tier ###### Content-Type: application/json - **`message`** `string` **Example:** ```json { "message": "" } ``` ##### Status: 500 Unhandled server error — file an issue with the request\_id from the error envelope. ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 502 Upstream dependency failed — gateway, key store, or downstream service unavailable. ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 503 Database query error or timeout — retry with backoff ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ### Screen companies by metric - **Method:** `GET` - **Path:** `/api/v1/companies/screen` - **Tags:** Periodic Reports Screen companies by a single financial metric value. **Example Uses:** - Companies with revenue > $1B: `?metric=revenue&min_value=1000000000` - Profitable companies: `?metric=net_income&min_value=0` - Revenue between $100M-$500M: `?metric=revenue&min_value=100000000&max_value=500000000` - Revenue > $1B in 2024: `?metric=revenue&min_value=1000000000&fiscal_year=2024` **Note:** Results auto-filter to latest filing version for each company/period. #### Responses ##### Status: 200 Successful Response ###### Content-Type: application/json - **`data` (required)** `array` — Matching companies **Items:** - **`cik` (required)** `string` — SEC Central Index Key - **`fiscal_quarter` (required)** `integer` — Fiscal quarter - **`fiscal_year` (required)** `integer` — Fiscal year - **`metric` (required)** `string` — Metric name - **`company_name`** `object` — Company name - **`metric_value`** `object` — Metric value - **`period_label`** `object` — Period label - **`tickers`** `object` — Ticker symbols - **`total` (required)** `integer` — Total matching results **Example:** ```json { "data": [ { "cik": "", "company_name": "", "tickers": [ "" ], "fiscal_year": 1, "fiscal_quarter": 1, "period_label": "", "metric": "", "metric_value": 1 } ], "total": 1 } ``` ##### Status: 401 Authentication failed - missing or invalid API key ###### Content-Type: application/json - **`message`** `string` **Example:** ```json { "message": "Missing API key in request" } ``` ##### Status: 422 Request validation failed - invalid or missing parameters ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 429 Rate limit exceeded for your tier ###### Content-Type: application/json - **`message`** `string` **Example:** ```json { "message": "" } ``` ##### Status: 500 Unhandled server error — file an issue with the request\_id from the error envelope. ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 502 Upstream dependency failed — gateway, key store, or downstream service unavailable. ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 503 Database query error or timeout — retry with backoff ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ### Multi-metric company screening - **Method:** `POST` - **Path:** `/api/v1/companies/screen/advanced` - **Tags:** Periodic Reports Screen companies using multiple metric criteria with AND logic. Find companies that match ALL specified filters. **Example Request:** ```json { "filters": [ {"metric": "revenue", "min_value": 1000000000}, {"metric": "net_income", "min_value": 0} ], "fiscal_year": 2024 } ``` Returns profitable companies with revenue > $1B in fiscal year 2024. **Note:** Results auto-filter to latest filing version for each company/period. #### Request Body ##### Content-Type: application/json - **`filters` (required)** `array` — Required. List of metric filters (AND logic). **Items:** - **`metric` (required)** `string` — Required. Metric name (e.g., 'revenue', 'net\_income'). - **`max_value`** `object` — Optional. Maximum value (inclusive). - **`min_value`** `object` — Optional. Minimum value (inclusive). - **`fiscal_year` (required)** `integer` — Required. Fiscal year to screen. - **`fiscal_quarter`** `object` — Optional. Fiscal quarter: 0=FY, 1-4=quarters (optional). - **`limit`** `integer`, default: `100` — Optional. Maximum results to return. **Example:** ```json { "filters": [ { "metric": "", "min_value": 1, "max_value": 1 } ], "fiscal_year": 1990, "fiscal_quarter": 0, "limit": 100 } ``` #### Responses ##### Status: 200 Successful Response ###### Content-Type: application/json - **`data` (required)** `array` — Companies matching ALL metric criteria **Items:** - **`cik` (required)** `string` — SEC Central Index Key - **`company_name`** `object` — Company name - **`tickers`** `object` — Ticker symbols - **`filters_applied` (required)** `array` — Filters that were applied **Items:** - **`metric` (required)** `string` — Required. Metric name (e.g., 'revenue', 'net\_income'). - **`max_value`** `object` — Optional. Maximum value (inclusive). - **`min_value`** `object` — Optional. Minimum value (inclusive). - **`total` (required)** `integer` — Total matching companies **Example:** ```json { "data": [ { "cik": "", "company_name": "", "tickers": [ "" ] } ], "total": 1, "filters_applied": [ { "metric": "", "min_value": 1, "max_value": 1 } ] } ``` ##### Status: 400 Request rejected — usually a missing required parameter or an at-least-one-of constraint not satisfied. ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 401 Authentication failed - missing or invalid API key ###### Content-Type: application/json - **`message`** `string` **Example:** ```json { "message": "Missing API key in request" } ``` ##### Status: 422 Request validation failed - invalid or missing parameters ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 429 Rate limit exceeded for your tier ###### Content-Type: application/json - **`message`** `string` **Example:** ```json { "message": "" } ``` ##### Status: 500 Unhandled server error — file an issue with the request\_id from the error envelope. ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 502 Upstream dependency failed — gateway, key store, or downstream service unavailable. ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 503 Database query error or timeout — retry with backoff ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ### List available metrics - **Method:** `GET` - **Path:** `/api/v1/companies/metrics` - **Tags:** Periodic Reports Get the list of standardized metric names available for cross-company screening. Per-company XBRL custom tags are excluded — they can't be used to compare issuers. #### Responses ##### Status: 200 Successful Response ###### Content-Type: application/json - **`data` (required)** `array` — Standardized metric names available for screening **Items:** `string` - **`total` (required)** `integer` — Number of metrics returned **Example:** ```json { "data": [ "" ], "total": 1 } ``` ##### Status: 401 Authentication failed - missing or invalid API key ###### Content-Type: application/json - **`message`** `string` **Example:** ```json { "message": "Missing API key in request" } ``` ##### Status: 429 Rate limit exceeded for your tier ###### Content-Type: application/json - **`message`** `string` **Example:** ```json { "message": "" } ``` ##### Status: 500 Unhandled server error — file an issue with the request\_id from the error envelope. ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 502 Upstream dependency failed — gateway, key store, or downstream service unavailable. ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 503 Database query error or timeout — retry with backoff ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ### List companies in the entity registry - **Method:** `GET` - **Path:** `/api/v1/companies` - **Tags:** Periodic Reports Paginated directory of companies — `is_human IS NOT TRUE` in the entity registry. Captures both the curated metadata-rich subset (SIC, exchanges, EIN, LEI, state\_of\_incorp, filer status flags populated) and the unclassified bulk where most major companies currently live (Apple, Microsoft, NVIDIA, etc.). **Coverage note:** the curated subset has full metadata; the bulk has only `cik + name` until the upstream metadata pass backfills. The structured filters (`exchange`, `sic`, `state_of_incorp`, `entity_type`) only return rows where those fields are populated — narrowing to the curated subset is the expected behavior. For the full per-CIK profile (with outbound links into family endpoints), call `GET /api/v1/companies/{cik}` or the type-agnostic `GET /api/v1/entities/{cik}`. Distinct from the per-family `/{family}/entities` endpoints — those enumerate filers that have actually submitted in that family. This endpoint returns the registry-wide directory regardless of filing activity. #### Responses ##### Status: 200 Successful Response ###### Content-Type: application/json - **`data` (required)** `array` — Registry entries matching the search / filters. **Items:** - **`cik` (required)** `string` — SEC Central Index Key, canonical short form (no leading zeros). - **`category`** `object` — Categorization tags (filer category, fund type, etc.). - **`description`** `object` — Free-text entity description. - **`ein`** `object` — IRS Employer Identification Number. - **`entity_type`** `object` — Entity type: \`operating\`, \`investment\`, or \`other\`. - **`exchanges`** `object` — Exchanges the entity trades on (e.g., \`NYSE\`, \`Nasdaq\`). - **`filer_status_flags`** `object` — Filer status flags (e.g., \`Large Accelerated\`, \`Well Known Seasoned Issuer\`, \`Emerging Growth Company\`). - **`fiscal_year_end`** `object` — Fiscal year end as \`MMDD\` (e.g., \`0930\` for Sep 30). - **`is_human`** `object` — Tri-state classification: \`true\` = confirmed human, \`false\` = confirmed company, \`null\` = not yet classified by the metadata pass. - **`lei`** `object` — Legal Entity Identifier (20-char ISO 17442). - **`name`** `object` — Entity legal name. - **`owner_org`** `object` — Owning organization name (when the entity is a subsidiary). - **`sic`** `object` — 4-digit Standard Industrial Classification code. - **`sic_description`** `object` — Plain-text SIC name. - **`state_of_incorp`** `object` — 2-letter state code or country code of incorporation. - **`tickers`** `object` — Ticker symbols associated with the entity. - **`page_size` (required)** `integer` — Results per page - **`page`** `integer`, default: `1` — Current page number (1-indexed) - **`total`** `integer`, default: `0` — Total count of matching rows - **`total_pages`** `integer`, default: `1` — Total number of pages **Example:** ```json { "total": 0, "page": 1, "page_size": 1, "total_pages": 1, "data": [ { "cik": "", "name": "", "is_human": true, "entity_type": "", "sic": "", "sic_description": "", "tickers": [ "" ], "exchanges": [ "" ], "ein": "", "lei": "", "description": "", "category": null, "fiscal_year_end": "", "state_of_incorp": "", "owner_org": "", "filer_status_flags": [ "" ] } ] } ``` ##### Status: 401 Authentication failed - missing or invalid API key ###### Content-Type: application/json - **`message`** `string` **Example:** ```json { "message": "Missing API key in request" } ``` ##### Status: 422 Request validation failed - invalid or missing parameters ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 429 Rate limit exceeded for your tier ###### Content-Type: application/json - **`message`** `string` **Example:** ```json { "message": "" } ``` ##### Status: 500 Unhandled server error — file an issue with the request\_id from the error envelope. ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 502 Upstream dependency failed — gateway, key store, or downstream service unavailable. ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 503 Database query error or timeout — retry with backoff ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ### Get registry profile for one company - **Method:** `GET` - **Path:** `/api/v1/companies/{cik}` - **Tags:** Periodic Reports Returns the registry profile for one company by CIK. 404 if the CIK doesn't exist in the registry, or if the row is classified as a human (`is_human IS TRUE`) — humans live under `/api/v1/people/{cik}` and the type-agnostic `/api/v1/entities/{cik}` covers either case. #### Responses ##### Status: 200 Successful Response ###### Content-Type: application/json - **`cik` (required)** `string` — SEC Central Index Key, canonical short form (no leading zeros). - **`links` (required)** `object` — Outbound links into family-specific endpoints, keyed by the kind of follow-up query they support. Always present (every CIK in the registry can in principle file in any family). The \`form4\_as\_filer\` link is the high-value hop for confirmed humans — both companies and humans can appear as Form 4 reporting owners. - **`category`** `object` — Categorization tags (filer category, fund type, etc.). - **`description`** `object` — Free-text entity description. - **`ein`** `object` — IRS Employer Identification Number. - **`entity_type`** `object` — Entity type: \`operating\`, \`investment\`, or \`other\`. - **`exchanges`** `object` — Exchanges the entity trades on (e.g., \`NYSE\`, \`Nasdaq\`). - **`filer_status_flags`** `object` — Filer status flags (e.g., \`Large Accelerated\`, \`Well Known Seasoned Issuer\`, \`Emerging Growth Company\`). - **`fiscal_year_end`** `object` — Fiscal year end as \`MMDD\` (e.g., \`0930\` for Sep 30). - **`is_human`** `object` — Tri-state classification: \`true\` = confirmed human, \`false\` = confirmed company, \`null\` = not yet classified by the metadata pass. - **`lei`** `object` — Legal Entity Identifier (20-char ISO 17442). - **`name`** `object` — Entity legal name. - **`owner_org`** `object` — Owning organization name (when the entity is a subsidiary). - **`sic`** `object` — 4-digit Standard Industrial Classification code. - **`sic_description`** `object` — Plain-text SIC name. - **`state_of_incorp`** `object` — 2-letter state code or country code of incorporation. - **`tickers`** `object` — Ticker symbols associated with the entity. **Example:** ```json { "cik": "", "name": "", "is_human": true, "entity_type": "", "sic": "", "sic_description": "", "tickers": [ "" ], "exchanges": [ "" ], "ein": "", "lei": "", "description": "", "category": null, "fiscal_year_end": "", "state_of_incorp": "", "owner_org": "", "filer_status_flags": [ "" ], "links": { "additionalProperty": "" } } ``` ##### Status: 401 Authentication failed - missing or invalid API key ###### Content-Type: application/json - **`message`** `string` **Example:** ```json { "message": "Missing API key in request" } ``` ##### Status: 404 Resource not found ###### Content-Type: application/json - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } ``` ##### Status: 422 Request validation failed - invalid or missing parameters ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 429 Rate limit exceeded for your tier ###### Content-Type: application/json - **`message`** `string` **Example:** ```json { "message": "" } ``` ##### Status: 500 Unhandled server error — file an issue with the request\_id from the error envelope. ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 502 Upstream dependency failed — gateway, key store, or downstream service unavailable. ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 503 Database query error or timeout — retry with backoff ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ### Get financial ratios - **Method:** `GET` - **Path:** `/api/v1/ratios` - **Tags:** Periodic Reports Retrieve financial ratios with filtering and quality scoring. **Key Features:** - Auto-filters to latest filing version (handles restatements) - Quality filtering via `min_quality` parameter - Screen by ratio value (min\_value, max\_value) - Filter by category or specific ratio name **Example Uses:** - All ratios for Apple Q1 2024: `?cik=0000320193&fiscal_year=2024&fiscal_quarter=1` - Companies with current ratio > 2: `?ratio_name=current_ratio&min_value=2.0` - All liquidity ratios: `?ratio_category=liquidity` - High-quality data only: `?min_quality=0.9` **Quality Scores:** - 0.9+ = Excellent data completeness - 0.7-0.9 = Good (default threshold) - <0.7 = May have missing inputs #### Responses ##### Status: 200 Successful Response ###### Content-Type: application/json - **`data` (required)** `array` — Array of ratios **Items:** - **`cik` (required)** `string` — SEC Central Index Key - **`fiscal_quarter` (required)** `integer` — Fiscal quarter: 0=FY, 1-4=quarters - **`fiscal_year` (required)** `integer` — Fiscal year - **`quality` (required)** `number` — Data-completeness score in \[0, 1]. Computed as the share of non-null source statements (balance sheet / income / cash flow) the ratio was derived from. 1.0 means all three sources were present; 0.67 means two of three; 0.33 means one of three. - **`ratio_category` (required)** `string` — Category: liquidity, profitability, leverage, etc. - **`ratio_id` (required)** `integer` — Unique ratio identifier - **`ratio_name` (required)** `string` — Ratio name (e.g., 'current\_ratio', 'roe') - **`company_name`** `object` — Company name - **`period_label`** `object` — Period label (e.g., 'Q1', 'FY') - **`ratio_value`** `object` — Calculated ratio value - **`tickers`** `object` — Ticker symbols - **`page` (required)** `integer` — Current page number - **`page_size` (required)** `integer` — Results per page - **`total` (required)** `integer` — Total count of matching ratios - **`total_pages` (required)** `integer` — Total pages **Example:** ```json { "data": [ { "cik": "0000320193", "company_name": "Apple Inc.", "fiscal_quarter": 1, "fiscal_year": 2024, "period_label": "Q1", "ratio_category": "liquidity", "ratio_id": 12345, "ratio_name": "current_ratio", "ratio_value": 2.45, "tickers": [ "AAPL" ] } ], "page": 1, "page_size": 100, "total": 150, "total_pages": 2 } ``` ##### Status: 401 Authentication failed - missing or invalid API key ###### Content-Type: application/json - **`message`** `string` **Example:** ```json { "message": "Missing API key in request" } ``` ##### Status: 422 Request validation failed - invalid or missing parameters ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 429 Rate limit exceeded for your tier ###### Content-Type: application/json - **`message`** `string` **Example:** ```json { "message": "" } ``` ##### Status: 500 Unhandled server error — file an issue with the request\_id from the error envelope. ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 502 Upstream dependency failed — gateway, key store, or downstream service unavailable. ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 503 Database query error or timeout — retry with backoff ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ### List ratio categories - **Method:** `GET` - **Path:** `/api/v1/ratios/categories` - **Tags:** Periodic Reports Get list of available ratio categories. Common categories include: - **liquidity** - Current ratio, quick ratio, cash ratio - **profitability** - ROE, ROA, profit margins - **leverage** - Debt-to-equity, interest coverage - **efficiency** - Asset turnover, inventory turnover - **valuation** - P/E ratio, P/B ratio, EV/EBITDA #### Responses ##### Status: 200 Successful Response ###### Content-Type: application/json - **`categories` (required)** `array` — Available ratio categories **Items:** `string` - **`data` (required)** `array` — Alias of \`categories\`, matching the canonical \`{data}\` envelope. **Items:** `string` **Example:** ```json { "categories": [ "" ], "data": [ "" ] } ``` ##### Status: 401 Authentication failed - missing or invalid API key ###### Content-Type: application/json - **`message`** `string` **Example:** ```json { "message": "Missing API key in request" } ``` ##### Status: 429 Rate limit exceeded for your tier ###### Content-Type: application/json - **`message`** `string` **Example:** ```json { "message": "" } ``` ##### Status: 500 Unhandled server error — file an issue with the request\_id from the error envelope. ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 502 Upstream dependency failed — gateway, key store, or downstream service unavailable. ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 503 Database query error or timeout — retry with backoff ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ### List ratio names - **Method:** `GET` - **Path:** `/api/v1/ratios/names` - **Tags:** Periodic Reports Get list of available ratio names, optionally filtered by category. **Example Uses:** - All ratio names: `/ratios/names` - Liquidity ratios only: `/ratios/names?category=liquidity` #### Responses ##### Status: 200 Successful Response ###### Content-Type: application/json - **`data` (required)** `array` — Alias of \`ratio\_names\`, matching the canonical \`{data}\` envelope. **Items:** `string` - **`ratio_names` (required)** `array` — Available ratio names **Items:** `string` - **`category`** `object` — Category filter applied (if any) **Example:** ```json { "ratio_names": [ "" ], "category": "", "data": [ "" ] } ``` ##### Status: 401 Authentication failed - missing or invalid API key ###### Content-Type: application/json - **`message`** `string` **Example:** ```json { "message": "Missing API key in request" } ``` ##### Status: 422 Request validation failed - invalid or missing parameters ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 429 Rate limit exceeded for your tier ###### Content-Type: application/json - **`message`** `string` **Example:** ```json { "message": "" } ``` ##### Status: 500 Unhandled server error — file an issue with the request\_id from the error envelope. ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 502 Upstream dependency failed — gateway, key store, or downstream service unavailable. ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 503 Database query error or timeout — retry with backoff ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ### Year-over-year ratio deltas - **Method:** `GET` - **Path:** `/api/v1/ratios/yoy` - **Tags:** Periodic Reports Returns current vs same-quarter-prior-year value for each ratio\_name on file for the issuer. **Required:** at least one of `cik` or `ticker`. The anchor period defaults to the latest (fiscal\_year, fiscal\_quarter) on file for the issuer; pass explicit `?fiscal_year=&fiscal_quarter=` to anchor on a specific period. `?ratio_name=` narrows to one ratio (e.g., `gross_margin_pct`). **Example:** AAPL gross-margin YoY: `?ticker=AAPL&ratio_name=gross_margin_pct` #### Responses ##### Status: 200 Successful Response ###### Content-Type: application/json - **`cik` (required)** `string` — Resolved issuer CIK (canonical short form). - **`comparison` (required)** `string` — 'yoy' (year-over-year) or 'qoq' (quarter-over-quarter). - **`data` (required)** `array` — Per-ratio current vs prior comparison rows. **Items:** - **`current` (required)** `object` — Current-period value. - **`ratio_name` (required)** `string` — Ratio name (e.g., 'gross\_margin\_pct'). - **`delta`** `object` — current.ratio\_value - prior.ratio\_value; null when either is missing. - **`pct_change`** `object` — delta / |prior.ratio\_value|, expressed as a fraction (e.g., 0.05 = +5%); null when prior is missing or zero. - **`prior`** `object` — Comparison-period value; null when no prior period is on file. - **`ratio_category`** `object` — Ratio category (e.g., 'profitability'). - **`fiscal_quarter` (required)** `integer` — Anchor fiscal quarter resolved. - **`fiscal_year` (required)** `integer` — Anchor fiscal year resolved. - **`company_name`** `object` — Issuer name. - **`ticker`** `object` — Issuer ticker queried, when supplied. **Example:** ```json { "cik": "", "ticker": "", "company_name": "", "comparison": "", "fiscal_year": 1, "fiscal_quarter": 1, "data": [ { "ratio_name": "", "ratio_category": "", "current": null, "prior": null, "delta": 1, "pct_change": 1 } ] } ``` ##### Status: 401 Authentication failed - missing or invalid API key ###### Content-Type: application/json - **`message`** `string` **Example:** ```json { "message": "Missing API key in request" } ``` ##### Status: 422 Request validation failed - invalid or missing parameters ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 429 Rate limit exceeded for your tier ###### Content-Type: application/json - **`message`** `string` **Example:** ```json { "message": "" } ``` ##### Status: 500 Unhandled server error — file an issue with the request\_id from the error envelope. ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 502 Upstream dependency failed — gateway, key store, or downstream service unavailable. ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 503 Database query error or timeout — retry with backoff ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ### Quarter-over-quarter ratio deltas - **Method:** `GET` - **Path:** `/api/v1/ratios/qoq` - **Tags:** Periodic Reports Returns current vs prior-quarter value for each ratio\_name on file for the issuer. When the anchor is fiscal Q1, the prior comparison falls back to the previous fiscal year's Q4. **Required:** at least one of `cik` or `ticker`. **Example:** AAPL ROE QoQ: `?ticker=AAPL&ratio_name=return_on_equity_pct` #### Responses ##### Status: 200 Successful Response ###### Content-Type: application/json - **`cik` (required)** `string` — Resolved issuer CIK (canonical short form). - **`comparison` (required)** `string` — 'yoy' (year-over-year) or 'qoq' (quarter-over-quarter). - **`data` (required)** `array` — Per-ratio current vs prior comparison rows. **Items:** - **`current` (required)** `object` — Current-period value. - **`ratio_name` (required)** `string` — Ratio name (e.g., 'gross\_margin\_pct'). - **`delta`** `object` — current.ratio\_value - prior.ratio\_value; null when either is missing. - **`pct_change`** `object` — delta / |prior.ratio\_value|, expressed as a fraction (e.g., 0.05 = +5%); null when prior is missing or zero. - **`prior`** `object` — Comparison-period value; null when no prior period is on file. - **`ratio_category`** `object` — Ratio category (e.g., 'profitability'). - **`fiscal_quarter` (required)** `integer` — Anchor fiscal quarter resolved. - **`fiscal_year` (required)** `integer` — Anchor fiscal year resolved. - **`company_name`** `object` — Issuer name. - **`ticker`** `object` — Issuer ticker queried, when supplied. **Example:** ```json { "cik": "", "ticker": "", "company_name": "", "comparison": "", "fiscal_year": 1, "fiscal_quarter": 1, "data": [ { "ratio_name": "", "ratio_category": "", "current": null, "prior": null, "delta": 1, "pct_change": 1 } ] } ``` ##### Status: 401 Authentication failed - missing or invalid API key ###### Content-Type: application/json - **`message`** `string` **Example:** ```json { "message": "Missing API key in request" } ``` ##### Status: 422 Request validation failed - invalid or missing parameters ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 429 Rate limit exceeded for your tier ###### Content-Type: application/json - **`message`** `string` **Example:** ```json { "message": "" } ``` ##### Status: 500 Unhandled server error — file an issue with the request\_id from the error envelope. ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 502 Upstream dependency failed — gateway, key store, or downstream service unavailable. ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 503 Database query error or timeout — retry with backoff ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ### Issuer's ratio percentile rank within SIC peer set - **Method:** `GET` - **Path:** `/api/v1/ratios/percentile` - **Tags:** Periodic Reports Returns the issuer's percentile rank for a given ratio\_name compared to other issuers in the same SIC code at the same fiscal period. The result is in \[0, 1] where higher = larger ratio value. **Required:** at least one of `cik` or `ticker`, plus `ratio_name`. `peer_set` currently accepts only `sic`; `spx500` is on the Tier-3 roadmap (needs an index-membership data source). **Examples:** - AAPL gross margin vs SIC 3571 cohort: `?ticker=AAPL&ratio_name=gross_margin_pct&peer_set=sic` #### Responses ##### Status: 200 Successful Response ###### Content-Type: application/json - **`cik` (required)** `string` — Resolved issuer CIK (canonical short form). - **`cohort_size` (required)** `integer` — Number of issuers in the SIC cohort with a ratio\_value at the same (fiscal\_year, fiscal\_quarter, ratio\_name). - **`fiscal_quarter` (required)** `integer` — Anchor fiscal quarter resolved. - **`fiscal_year` (required)** `integer` — Anchor fiscal year resolved. - **`peer_set` (required)** `string` — Peer-set used for the rank ('sic'). - **`ratio_name` (required)** `string` — Ratio name compared. - **`company_name`** `object` — Issuer name. - **`percentile`** `object` — Rank of this issuer in the cohort, in \[0, 1]. Higher = larger ratio value. Null when cohort\_size <= 1. - **`ratio_value`** `object` — The issuer's ratio value at the resolved period. - **`sic`** `object` — Issuer's SIC code (the partition key for the rank). - **`sic_description`** `object` — SIC description. - **`ticker`** `object` — Issuer ticker queried, when supplied. **Example:** ```json { "cik": "", "ticker": "", "company_name": "", "ratio_name": "", "ratio_value": 1, "fiscal_year": 1, "fiscal_quarter": 1, "peer_set": "", "sic": "", "sic_description": "", "cohort_size": 1, "percentile": 1 } ``` ##### Status: 401 Authentication failed - missing or invalid API key ###### Content-Type: application/json - **`message`** `string` **Example:** ```json { "message": "Missing API key in request" } ``` ##### Status: 422 Request validation failed - invalid or missing parameters ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 429 Rate limit exceeded for your tier ###### Content-Type: application/json - **`message`** `string` **Example:** ```json { "message": "" } ``` ##### Status: 500 Unhandled server error — file an issue with the request\_id from the error envelope. ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 502 Upstream dependency failed — gateway, key store, or downstream service unavailable. ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 503 Database query error or timeout — retry with backoff ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ### Resolve any security identifier to the canonical cross-reference - **Method:** `GET` - **Path:** `/api/v1/securities/{identifier}` - **Tags:** Securities Resolve any of CUSIP, CUSIP-9, ISIN, ticker, or CIK to the full mapping ({cik, company\_name, tickers, cusip, isin, lei}). The identifier type is auto-detected from the input shape — pass the value without a type hint. **Examples:** - Ticker: `/securities/AAPL` - CIK: `/securities/320193` (canonical short form) or `/securities/0000320193` - CUSIP: `/securities/037833100` - ISIN: `/securities/US0378331005` (when N-PORT carries it) Coverage notes (audit-honest): - `cik ↔ company_name ↔ tickers` is rock solid via `vw_api_statements`. - CUSIP → `name` uses the modal name across 13F / N-PORT holdings to avoid the per-filer spelling drift (e.g., "TRAVELERS COMPANIES INC" for Apple's CUSIP that the round-4 audit caught). - CUSIP → `cik` / `ticker` is best-effort via the N-PORT `registrant_cik` link. - ISIN coverage is sparse (N-PORT-only) and may return 404 when the upstream view doesn't carry the ISIN. Returns 400 if the identifier doesn't match any known shape, 404 if it matches but no view contains data for it. #### Responses ##### Status: 200 Successful Response ###### Content-Type: application/json - **`identifier` (required)** `string` — The identifier the caller passed in, normalized. - **`identifier_type` (required)** `string`, possible values: `"cusip", "isin", "ticker", "cik"` — Detected type of the input identifier. CIKs are stripped of leading zeros; tickers are uppercased; CUSIP/ISIN are passed through unchanged. - **`cik`** `object` — Issuer SEC CIK (canonical short form, no leading zeros). - **`company_name`** `object` — Issuer company name. Sourced from \`vw\_api\_statements\` when we have the CIK; otherwise the modal name across 13F / N-PORT holdings. - **`cusip`** `object` — 9-character CUSIP, or 8 if reported short. - **`entity_type`** `object` — Entity type from the registry: \`operating\`, \`investment\`, or \`other\`. - **`exchanges`** `object` — Exchanges the entity trades on (e.g., \`NYSE\`, \`Nasdaq\`). - **`filer_status_flags`** `object` — Filer status flags from the registry (e.g., \`Large Accelerated\`, \`Well Known Seasoned Issuer\`). - **`is_human`** `object` — Tri-state classification from the entity registry: \`true\` = confirmed human, \`false\` = confirmed company, \`null\` = either not in the registry or not yet classified. - **`isin`** `object` — 12-character ISIN (sparse coverage). - **`lei`** `object` — 20-character Legal Entity Identifier (N-PORT-sourced). - **`sic`** `object` — 4-digit Standard Industrial Classification code. - **`sic_description`** `object` — Plain-text SIC name. - **`sources`** `array` — Underlying views that contributed to the response. Useful for debugging coverage gaps. **Items:** `string` - **`state_of_incorp`** `object` — 2-letter state code or country code of incorporation. - **`tickers`** `object` — All ticker symbols associated with the issuer. **Example:** ```json { "cik": "320193", "company_name": "Apple Inc.", "cusip": "037833100", "identifier": "AAPL", "identifier_type": "ticker", "lei": "HWUPKR0MPOU8FGXBT394", "sources": [ "vw_api_statements", "vw_api_data_nport_holdings" ], "tickers": [ "AAPL" ] } ``` ##### Status: 401 Authentication failed - missing or invalid API key ###### Content-Type: application/json - **`message`** `string` **Example:** ```json { "message": "Missing API key in request" } ``` ##### Status: 404 Resource not found ###### Content-Type: application/json - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } ``` ##### Status: 422 Request validation failed - invalid or missing parameters ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 429 Rate limit exceeded for your tier ###### Content-Type: application/json - **`message`** `string` **Example:** ```json { "message": "" } ``` ##### Status: 500 Unhandled server error — file an issue with the request\_id from the error envelope. ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 502 Upstream dependency failed — gateway, key store, or downstream service unavailable. ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 503 Database query error or timeout — retry with backoff ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ### Get text sections - **Method:** `GET` - **Path:** `/api/v1/text/sections` - **Tags:** Periodic Reports Retrieve textual sections from SEC filings (MD\&A, Risk Factors, Business Description, etc.). **Required:** at least one of `filing_id`, `cik`, `ticker`, `part`, `item_number`, `item_label`, `form_type`. Returns `400 MISSING_PARAMETER` otherwise. **IMPORTANT:** SEC filings have Parts (I, II, III, IV) where item numbers repeat: - Part I, Item 1 = Business Description - Part II, Item 1 = Market Info (DIFFERENT content!) - Part II, Item 7 = MD\&A For unique section identification, filter by BOTH `part` AND `item_number`. **Example Uses:** - All sections from a filing: `?filing_id=0000320193_0000320193-24-000123` - All 10-K sections for Apple: `?cik=0000320193&form_type=10-K` - MD\&A sections (Part II, Item 7): `?part=2&item_number=7` - Business Description (Part I, Item 1): `?part=1&item_number=1` - Risk Factors by label: `?item_label=Risk Factors` #### Responses ##### Status: 200 Successful Response ###### Content-Type: application/json - **`data` (required)** `array` — Array of text sections **Items:** - **`accession_num` (required)** `object` — EDGAR accession number derived from filing\_id (e.g., '0000320193-24-000123') - **`cik` (required)** `string` — SEC Central Index Key - **`filing_id` (required)** `string` — Filing identifier - **`section_id` (required)** `string` — Unique section identifier (UUID) - **`source_url` (required)** `object` — Canonical SEC EDGAR Archives URL pointing at the filing's index page - **`accepted_time`** `object` — SEC acceptance timestamp - **`block_id`** `object` — Parent block identifier - **`clean_title`** `object` — Cleaned section title - **`company_name`** `object` — Company name - **`date`** `object` — Filing date - **`form_type`** `object` — Form type (10-K, 10-Q) - **`item_label`** `object` — Item label - **`item_number`** `object` — Item number - **`part`** `object` — Part number (1-4) - **`tickers`** `object` — Ticker symbols - **`validated_tables`** `object` — Extracted tables - **`validated_text`** `object` — Cleaned text content - **`page` (required)** `integer` — Current page number - **`page_size` (required)** `integer` — Results per page - **`total` (required)** `integer` — Total count of matching sections - **`total_pages` (required)** `integer` — Total pages **Example:** ```json { "data": [ { "block_id": "block456-789", "cik": "0000320193", "clean_title": "Management's Discussion and Analysis", "company_name": "Apple Inc.", "date": "2024-11-01T00:00:00Z", "filing_id": "0000320193_0000320193-24-000123", "form_type": "10-K", "item_label": "Item 7", "item_number": "7", "part": 2, "section_id": "sec123-456-789", "tickers": [ "AAPL" ], "validated_text": "The following discussion should be read..." } ], "page": 1, "page_size": 100, "total": 25, "total_pages": 1 } ``` ##### Status: 401 Authentication failed - missing or invalid API key ###### Content-Type: application/json - **`message`** `string` **Example:** ```json { "message": "Missing API key in request" } ``` ##### Status: 422 Request validation failed - invalid or missing parameters ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 429 Rate limit exceeded for your tier ###### Content-Type: application/json - **`message`** `string` **Example:** ```json { "message": "" } ``` ##### Status: 500 Unhandled server error — file an issue with the request\_id from the error envelope. ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 502 Upstream dependency failed — gateway, key store, or downstream service unavailable. ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 503 Database query error or timeout — retry with backoff ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ### Get section by ID - **Method:** `GET` - **Path:** `/api/v1/text/sections/{section_id}` - **Tags:** Periodic Reports Retrieve a single text section by its section\_id. #### Responses ##### Status: 200 Successful Response ###### Content-Type: application/json - **`accession_num` (required)** `object` — EDGAR accession number derived from filing\_id (e.g., '0000320193-24-000123') - **`cik` (required)** `string` — SEC Central Index Key - **`filing_id` (required)** `string` — Filing identifier - **`section_id` (required)** `string` — Unique section identifier (UUID) - **`source_url` (required)** `object` — Canonical SEC EDGAR Archives URL pointing at the filing's index page - **`accepted_time`** `object` — SEC acceptance timestamp - **`block_id`** `object` — Parent block identifier - **`clean_title`** `object` — Cleaned section title - **`company_name`** `object` — Company name - **`date`** `object` — Filing date - **`form_type`** `object` — Form type (10-K, 10-Q) - **`item_label`** `object` — Item label - **`item_number`** `object` — Item number - **`part`** `object` — Part number (1-4) - **`tickers`** `object` — Ticker symbols - **`validated_tables`** `object` — Extracted tables - **`validated_text`** `object` — Cleaned text content **Example:** ```json { "accepted_time": "2024-11-01T16:30:00Z", "block_id": "block456-789", "cik": "0000320193", "clean_title": "Management's Discussion and Analysis", "company_name": "Apple Inc.", "date": "2024-11-01T00:00:00Z", "filing_id": "0000320193_0000320193-24-000123", "form_type": "10-K", "item_label": "Item 7", "item_number": "7", "part": 2, "section_id": "sec123-456-789", "tickers": [ "AAPL" ], "validated_text": "The following discussion should be read..." } ``` ##### Status: 401 Authentication failed - missing or invalid API key ###### Content-Type: application/json - **`message`** `string` **Example:** ```json { "message": "Missing API key in request" } ``` ##### Status: 404 Resource not found ###### Content-Type: application/json - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } ``` ##### Status: 422 Request validation failed - invalid or missing parameters ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 429 Rate limit exceeded for your tier ###### Content-Type: application/json - **`message`** `string` **Example:** ```json { "message": "" } ``` ##### Status: 500 Unhandled server error — file an issue with the request\_id from the error envelope. ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 502 Upstream dependency failed — gateway, key store, or downstream service unavailable. ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 503 Database query error or timeout — retry with backoff ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ### Get sections by filing - **Method:** `GET` - **Path:** `/api/v1/text/sections/filing/{filing_id}` - **Tags:** Periodic Reports Retrieve all text sections for a specific SEC filing. Optionally filter by part and/or item number. #### Responses ##### Status: 200 Successful Response ###### Content-Type: application/json **Array of:** - **`accession_num` (required)** `object` — EDGAR accession number derived from filing\_id (e.g., '0000320193-24-000123') - **`cik` (required)** `string` — SEC Central Index Key - **`filing_id` (required)** `string` — Filing identifier - **`section_id` (required)** `string` — Unique section identifier (UUID) - **`source_url` (required)** `object` — Canonical SEC EDGAR Archives URL pointing at the filing's index page - **`accepted_time`** `object` — SEC acceptance timestamp - **`block_id`** `object` — Parent block identifier - **`clean_title`** `object` — Cleaned section title - **`company_name`** `object` — Company name - **`date`** `object` — Filing date - **`form_type`** `object` — Form type (10-K, 10-Q) - **`item_label`** `object` — Item label - **`item_number`** `object` — Item number - **`part`** `object` — Part number (1-4) - **`tickers`** `object` — Ticker symbols - **`validated_tables`** `object` — Extracted tables - **`validated_text`** `object` — Cleaned text content **Example:** ```json [ { "accepted_time": "2024-11-01T16:30:00Z", "block_id": "block456-789", "cik": "0000320193", "clean_title": "Management's Discussion and Analysis", "company_name": "Apple Inc.", "date": "2024-11-01T00:00:00Z", "filing_id": "0000320193_0000320193-24-000123", "form_type": "10-K", "item_label": "Item 7", "item_number": "7", "part": 2, "section_id": "sec123-456-789", "tickers": [ "AAPL" ], "validated_text": "The following discussion should be read..." } ] ``` ##### Status: 401 Authentication failed - missing or invalid API key ###### Content-Type: application/json - **`message`** `string` **Example:** ```json { "message": "Missing API key in request" } ``` ##### Status: 404 Resource not found ###### Content-Type: application/json - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } ``` ##### Status: 422 Request validation failed - invalid or missing parameters ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 429 Rate limit exceeded for your tier ###### Content-Type: application/json - **`message`** `string` **Example:** ```json { "message": "" } ``` ##### Status: 500 Unhandled server error — file an issue with the request\_id from the error envelope. ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 502 Upstream dependency failed — gateway, key store, or downstream service unavailable. ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 503 Database query error or timeout — retry with backoff ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ### Get registry metadata for one CIK - **Method:** `GET` - **Path:** `/api/v1/entities/{cik}` - **Tags:** Entities Returns the registry profile for one SEC CIK — humans or companies, classified or not. Includes whatever metadata the upstream pass has populated (SIC, exchanges, EIN, LEI, state\_of\_incorp, filer status flags) plus a `links` block of outbound family-endpoint URLs. **Coverage note:** the registry is the union of every CIK 3spread tracks. Most rows currently have only `cik + name` populated; the rich metadata fields fill in as the metadata pass backfills. Use `is_human IS NOT NULL` on a row as today's reliable proxy for "this row has been classified" (the curated subset has full metadata). `links.form4_as_filer` always points at `/insiders/owners/{cik}` — both humans and companies can appear as Form 4 reporting owners, so the outbound link is meaningful regardless of `is_human`. For directory-style listings, see: - `/api/v1/people` — paginated list of confirmed humans. - `/api/v1/companies` — paginated list of companies (includes unclassified rows where most major companies currently live). Returns 404 if the CIK is not in the registry. #### Responses ##### Status: 200 Successful Response ###### Content-Type: application/json - **`cik` (required)** `string` — SEC Central Index Key, canonical short form (no leading zeros). - **`links` (required)** `object` — Outbound links into family-specific endpoints, keyed by the kind of follow-up query they support. Always present (every CIK in the registry can in principle file in any family). The \`form4\_as\_filer\` link is the high-value hop for confirmed humans — both companies and humans can appear as Form 4 reporting owners. - **`category`** `object` — Categorization tags (filer category, fund type, etc.). - **`description`** `object` — Free-text entity description. - **`ein`** `object` — IRS Employer Identification Number. - **`entity_type`** `object` — Entity type: \`operating\`, \`investment\`, or \`other\`. - **`exchanges`** `object` — Exchanges the entity trades on (e.g., \`NYSE\`, \`Nasdaq\`). - **`filer_status_flags`** `object` — Filer status flags (e.g., \`Large Accelerated\`, \`Well Known Seasoned Issuer\`, \`Emerging Growth Company\`). - **`fiscal_year_end`** `object` — Fiscal year end as \`MMDD\` (e.g., \`0930\` for Sep 30). - **`is_human`** `object` — Tri-state classification: \`true\` = confirmed human, \`false\` = confirmed company, \`null\` = not yet classified by the metadata pass. - **`lei`** `object` — Legal Entity Identifier (20-char ISO 17442). - **`name`** `object` — Entity legal name. - **`owner_org`** `object` — Owning organization name (when the entity is a subsidiary). - **`sic`** `object` — 4-digit Standard Industrial Classification code. - **`sic_description`** `object` — Plain-text SIC name. - **`state_of_incorp`** `object` — 2-letter state code or country code of incorporation. - **`tickers`** `object` — Ticker symbols associated with the entity. **Example:** ```json { "cik": "", "name": "", "is_human": true, "entity_type": "", "sic": "", "sic_description": "", "tickers": [ "" ], "exchanges": [ "" ], "ein": "", "lei": "", "description": "", "category": null, "fiscal_year_end": "", "state_of_incorp": "", "owner_org": "", "filer_status_flags": [ "" ], "links": { "additionalProperty": "" } } ``` ##### Status: 401 Authentication failed - missing or invalid API key ###### Content-Type: application/json - **`message`** `string` **Example:** ```json { "message": "Missing API key in request" } ``` ##### Status: 404 Resource not found ###### Content-Type: application/json - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } ``` ##### Status: 422 Request validation failed - invalid or missing parameters ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 429 Rate limit exceeded for your tier ###### Content-Type: application/json - **`message`** `string` **Example:** ```json { "message": "" } ``` ##### Status: 500 Unhandled server error — file an issue with the request\_id from the error envelope. ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 502 Upstream dependency failed — gateway, key store, or downstream service unavailable. ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 503 Database query error or timeout — retry with backoff ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ### List humans in the entity registry - **Method:** `GET` - **Path:** `/api/v1/people` - **Tags:** Entities Paginated directory of confirmed individual filers — `is_human IS TRUE` in the entity registry. Mostly Form 4 reporting owners (insiders, officers, directors, 10% owners). **Coverage note:** the directory is bounded by the upstream metadata pass. The currently-classified \~1,136 humans is a fraction of the total — additional rows arrive as the pass backfills. For the full per-CIK profile (metadata + outbound links into family endpoints), call `GET /api/v1/entities/{cik}` with the `cik` returned in this list. Distinct from `/api/v1/insiders/entities` — that endpoint enumerates the *issuers* whose securities Form 4 filings reference; this endpoint enumerates the *people* doing the filing. #### Responses ##### Status: 200 Successful Response ###### Content-Type: application/json - **`data` (required)** `array` — Registry entries matching the search / filters. **Items:** - **`cik` (required)** `string` — SEC Central Index Key, canonical short form (no leading zeros). - **`category`** `object` — Categorization tags (filer category, fund type, etc.). - **`description`** `object` — Free-text entity description. - **`ein`** `object` — IRS Employer Identification Number. - **`entity_type`** `object` — Entity type: \`operating\`, \`investment\`, or \`other\`. - **`exchanges`** `object` — Exchanges the entity trades on (e.g., \`NYSE\`, \`Nasdaq\`). - **`filer_status_flags`** `object` — Filer status flags (e.g., \`Large Accelerated\`, \`Well Known Seasoned Issuer\`, \`Emerging Growth Company\`). - **`fiscal_year_end`** `object` — Fiscal year end as \`MMDD\` (e.g., \`0930\` for Sep 30). - **`is_human`** `object` — Tri-state classification: \`true\` = confirmed human, \`false\` = confirmed company, \`null\` = not yet classified by the metadata pass. - **`lei`** `object` — Legal Entity Identifier (20-char ISO 17442). - **`name`** `object` — Entity legal name. - **`owner_org`** `object` — Owning organization name (when the entity is a subsidiary). - **`sic`** `object` — 4-digit Standard Industrial Classification code. - **`sic_description`** `object` — Plain-text SIC name. - **`state_of_incorp`** `object` — 2-letter state code or country code of incorporation. - **`tickers`** `object` — Ticker symbols associated with the entity. - **`page_size` (required)** `integer` — Results per page - **`page`** `integer`, default: `1` — Current page number (1-indexed) - **`total`** `integer`, default: `0` — Total count of matching rows - **`total_pages`** `integer`, default: `1` — Total number of pages **Example:** ```json { "total": 0, "page": 1, "page_size": 1, "total_pages": 1, "data": [ { "cik": "", "name": "", "is_human": true, "entity_type": "", "sic": "", "sic_description": "", "tickers": [ "" ], "exchanges": [ "" ], "ein": "", "lei": "", "description": "", "category": null, "fiscal_year_end": "", "state_of_incorp": "", "owner_org": "", "filer_status_flags": [ "" ] } ] } ``` ##### Status: 401 Authentication failed - missing or invalid API key ###### Content-Type: application/json - **`message`** `string` **Example:** ```json { "message": "Missing API key in request" } ``` ##### Status: 422 Request validation failed - invalid or missing parameters ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 429 Rate limit exceeded for your tier ###### Content-Type: application/json - **`message`** `string` **Example:** ```json { "message": "" } ``` ##### Status: 500 Unhandled server error — file an issue with the request\_id from the error envelope. ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 502 Upstream dependency failed — gateway, key store, or downstream service unavailable. ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 503 Database query error or timeout — retry with backoff ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ### Coverage matrix for a single issuer - **Method:** `GET` - **Path:** `/api/v1/coverage/by-issuer/{cik_or_ticker}` - **Tags:** Coverage Returns per-family filing counts and period ranges for one issuer. Accepts either a CIK (zero-padded or short form) or a ticker symbol. Families with no filings on file for the issuer are omitted from the response. Schedule 13D/G is not included — those filings key on CUSIP, not issuer CIK, and require a separate cusip → cik resolve hop. **Example uses:** - `?` Apple's coverage: `/api/v1/coverage/by-issuer/AAPL` - `?` Apple by CIK: `/api/v1/coverage/by-issuer/320193` #### Responses ##### Status: 200 Successful Response ###### Content-Type: application/json - **`cik` (required)** `string` — Resolved issuer CIK (canonical short form, no leading zeros). - **`families` (required)** `object` — Per-family filing coverage for this issuer. Families with no filings on file are omitted. - **`company_name`** `object` — Modal company name across the issuer's filings. - **`tickers`** `object` — Ticker symbols associated with the issuer (when known). **Example:** ```json { "cik": "", "company_name": "", "tickers": [ "" ], "families": { "additionalProperty": { "filing_count": 0, "period_min": "", "period_max": "", "accepted_time_max": "" } } } ``` ##### Status: 401 Authentication failed - missing or invalid API key ###### Content-Type: application/json - **`message`** `string` **Example:** ```json { "message": "Missing API key in request" } ``` ##### Status: 404 Resource not found ###### Content-Type: application/json - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } ``` ##### Status: 422 Request validation failed - invalid or missing parameters ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 429 Rate limit exceeded for your tier ###### Content-Type: application/json - **`message`** `string` **Example:** ```json { "message": "" } ``` ##### Status: 500 Unhandled server error — file an issue with the request\_id from the error envelope. ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 502 Upstream dependency failed — gateway, key store, or downstream service unavailable. ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 503 Database query error or timeout — retry with backoff ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ### Global coverage matrix per family - **Method:** `GET` - **Path:** `/api/v1/coverage/by-family` - **Tags:** Coverage Returns a per-family snapshot of the data 3spread has on file: distinct CIK count, total filings, period range, accepted\_time range. This is the "what does 3spread know?" page-one answer — useful for sales / sizing / health-check consumers without polling each list endpoint individually. #### Responses ##### Status: 200 Successful Response ###### Content-Type: application/json - **`families` (required)** `object` — Coverage summary keyed by filing family. **Example:** ```json { "families": { "additionalProperty": { "distinct_cik_count": 0, "filing_count": 0, "period_min": "", "period_max": "", "accepted_time_min": "", "accepted_time_max": "" } } } ``` ##### Status: 401 Authentication failed - missing or invalid API key ###### Content-Type: application/json - **`message`** `string` **Example:** ```json { "message": "Missing API key in request" } ``` ##### Status: 429 Rate limit exceeded for your tier ###### Content-Type: application/json - **`message`** `string` **Example:** ```json { "message": "" } ``` ##### Status: 500 Unhandled server error — file an issue with the request\_id from the error envelope. ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 502 Upstream dependency failed — gateway, key store, or downstream service unavailable. ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 503 Database query error or timeout — retry with backoff ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ### Issuers with no recent filings - **Method:** `GET` - **Path:** `/api/v1/coverage/stale-issuers` - **Tags:** Coverage Lists issuers (from `vw_api_entities`) whose most-recent filing across all families is at least `min_gap_days` old. Useful for delinquency / suspension monitoring. Schedule 13D/G is not counted toward freshness for this endpoint (those filings key on CUSIP, not issuer CIK). **Examples:** - 90-day stale: `?min_gap_days=90` - Pulled from the last year only: `?min_gap_days=180&lookback_days=365` #### Responses ##### Status: 200 Successful Response ###### Content-Type: application/json - **`data` (required)** `array` — Issuers ranked by \`last\_accepted\_time\` ascending (most stale first). **Items:** - **`cik` (required)** `string` — Issuer CIK (canonical short form). - **`company_name`** `object` — Issuer name from the registry. - **`days_since_last_filing`** `object` — Whole days between today (UTC) and \`last\_accepted\_time\`. Null when no filings are on file. - **`families_on_file`** `array` — Families this issuer has at least one filing in. **Items:** `string`, possible values: `"insiders", "institutional_holdings", "private_offerings", "fund_portfolios", "beneficial_ownership", "proposed_sales", "fund_census", "money_market_funds", "proxy_votes", "reg_a_offerings", "narratives"` — Filing families surfaced by /api/v1/{family} resources. The eleven values below correspond 1:1 with the per-family routers registered in \`app/api/v1/router.py\`. Coverage / intake / data-as-of aggregate across exactly this set, so adding a new family means registering its view in \`app/services/api\_coverage\_service.py:FAMILY\_VIEWS\` and extending this enum in lockstep. - **`last_accepted_time`** `object` — Most recent accepted\_time across all families on file. - **`page_size` (required)** `integer` — Results per page - **`page`** `integer`, default: `1` — Current page number (1-indexed) - **`total`** `integer`, default: `0` — Total count of matching rows - **`total_pages`** `integer`, default: `1` — Total number of pages **Example:** ```json { "total": 0, "page": 1, "page_size": 1, "total_pages": 1, "data": [ { "cik": "", "company_name": "", "last_accepted_time": "", "days_since_last_filing": 1, "families_on_file": [] } ] } ``` ##### Status: 401 Authentication failed - missing or invalid API key ###### Content-Type: application/json - **`message`** `string` **Example:** ```json { "message": "Missing API key in request" } ``` ##### Status: 422 Request validation failed - invalid or missing parameters ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 429 Rate limit exceeded for your tier ###### Content-Type: application/json - **`message`** `string` **Example:** ```json { "message": "" } ``` ##### Status: 500 Unhandled server error — file an issue with the request\_id from the error envelope. ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 502 Upstream dependency failed — gateway, key store, or downstream service unavailable. ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 503 Database query error or timeout — retry with backoff ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ### Filing intake histogram - **Method:** `GET` - **Path:** `/api/v1/intake` - **Tags:** Coverage Returns filing counts bucketed by accepted\_time per family. Useful for monitoring ETL throughput — e.g., "did we ingest fewer Form 4s this week than expected?". `bucket_start` truncates to the period boundary (day / week / month). Empty (bucket, family) pairs are omitted; treat absent rows as zero. **Examples:** - Daily for the last 30 days: `?period=daily&lookback_days=30` - Weekly for the last quarter: `?period=weekly&lookback_days=90` #### Responses ##### Status: 200 Successful Response ###### Content-Type: application/json - **`data` (required)** `array` — Per-(bucket, family) counts. Empty (bucket, family) pairs are omitted; clients should treat absent rows as zero. **Items:** - **`bucket_start` (required)** `string`, format: `date` — Start date of this bucket (inclusive). - **`family` (required)** `object` — Filing family this bucket counts. - **`filing_count`** `integer`, default: `0` — Filings accepted within this bucket. - **`lookback_days` (required)** `integer` — Window length in days, ending at the most recent accepted\_time. - **`period` (required)** `string`, possible values: `"daily", "weekly", "monthly"` — Bucket size used for the histogram. **Example:** ```json { "period": "daily", "lookback_days": 1, "data": [ { "bucket_start": "", "family": null, "filing_count": 0 } ] } ``` ##### Status: 401 Authentication failed - missing or invalid API key ###### Content-Type: application/json - **`message`** `string` **Example:** ```json { "message": "Missing API key in request" } ``` ##### Status: 422 Request validation failed - invalid or missing parameters ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 429 Rate limit exceeded for your tier ###### Content-Type: application/json - **`message`** `string` **Example:** ```json { "message": "" } ``` ##### Status: 500 Unhandled server error — file an issue with the request\_id from the error envelope. ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 502 Upstream dependency failed — gateway, key store, or downstream service unavailable. ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 503 Database query error or timeout — retry with backoff ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ### Per-family freshness snapshot - **Method:** `GET` - **Path:** `/api/v1/data-as-of` - **Tags:** Coverage Returns the latest `accepted_time` and `period_of_report` plus total `filing_count` for every filing family. The cousin of `/health.data_as_of` — same idea, structured per-family for monitoring and integration use. Pair with `/intake` to see whether recent absence of new rows is a pipeline issue or a quiet day. #### Responses ##### Status: 200 Successful Response ###### Content-Type: application/json - **`families` (required)** `object` — Freshness summary keyed by filing family. **Example:** ```json { "families": { "fund_portfolios": { "accepted_time_max": "2024-03-30T18:00:00", "filing_count": 12500, "period_of_report_max": "2024-02-29" }, "insiders": { "accepted_time_max": "2024-03-15T20:14:00", "filing_count": 71800, "period_of_report_max": "2024-03-15" } } } ``` ##### Status: 401 Authentication failed - missing or invalid API key ###### Content-Type: application/json - **`message`** `string` **Example:** ```json { "message": "Missing API key in request" } ``` ##### Status: 429 Rate limit exceeded for your tier ###### Content-Type: application/json - **`message`** `string` **Example:** ```json { "message": "" } ``` ##### Status: 500 Unhandled server error — file an issue with the request\_id from the error envelope. ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 502 Upstream dependency failed — gateway, key store, or downstream service unavailable. ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 503 Database query error or timeout — retry with backoff ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ### Top issuers by insider buy volume - **Method:** `GET` - **Path:** `/api/v1/leaderboards/insider-buying` - **Tags:** Leaderboards Rank issuers by total dollar value of insider purchases (Form 4 transaction code `P`, acquired-disposed `A`) over the window. Default window is the last 30 days; pass `?lookback_days=` or explicit `?since=`/`?until=` to override. #### Responses ##### Status: 200 Successful Response ###### Content-Type: application/json - **`data` (required)** `array` — Issuers ranked by \`buys\_dollars\` descending. **Items:** - **`buys_count` (required)** `integer` — Number of buy transactions over the window. - **`buys_dollars` (required)** `string` — Sum of acquired-share value (USD) over the window. - **`cik` (required)** `string` — Issuer SEC Central Index Key (short form). - **`distinct_insiders_buying` (required)** `integer` — Distinct reporting owners with at least one buy in the window. - **`rank` (required)** `integer` — 1-indexed rank in this leaderboard. - **`company_name`** `object` — Modal issuer name across the window's filings. - **`tickers`** `object` — Issuer ticker symbols when known. - **`window` (required)** `object` — Window the leaderboard ranks over. - **`lookback_days` (required)** `integer` — Window length in days (until - since). - **`since` (required)** `string`, format: `date` — Window start (inclusive). - **`until` (required)** `string`, format: `date` — Window end (inclusive). **Example:** ```json { "window": { "since": "", "until": "", "lookback_days": 1 }, "data": [ { "rank": 1, "cik": "", "company_name": "", "tickers": [ "" ], "buys_dollars": "", "buys_count": 1, "distinct_insiders_buying": 1 } ] } ``` ##### Status: 401 Authentication failed - missing or invalid API key ###### Content-Type: application/json - **`message`** `string` **Example:** ```json { "message": "Missing API key in request" } ``` ##### Status: 422 Request validation failed - invalid or missing parameters ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 429 Rate limit exceeded for your tier ###### Content-Type: application/json - **`message`** `string` **Example:** ```json { "message": "" } ``` ##### Status: 500 Unhandled server error — file an issue with the request\_id from the error envelope. ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 502 Upstream dependency failed — gateway, key store, or downstream service unavailable. ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 503 Database query error or timeout — retry with backoff ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ### Top issuers by insider sell volume - **Method:** `GET` - **Path:** `/api/v1/leaderboards/insider-selling` - **Tags:** Leaderboards Rank issuers by total dollar value of insider sales (Form 4 transaction code `S`, acquired-disposed `D`) over the window. Pass `?exclude_10b51=true` to filter out 10b5-1 plan-driven sells — the discretionary-only ranking is the more informative one for sentiment work. #### Responses ##### Status: 200 Successful Response ###### Content-Type: application/json - **`data` (required)** `array` — Issuers ranked by \`sells\_dollars\` descending. **Items:** - **`cik` (required)** `string` — Issuer SEC Central Index Key (short form). - **`distinct_insiders_selling` (required)** `integer` — Distinct reporting owners with at least one sell in the window. - **`rank` (required)** `integer` — 1-indexed rank in this leaderboard. - **`sells_count` (required)** `integer` — Number of sell transactions over the window. - **`sells_dollars` (required)** `string` — Sum of disposed-share value (USD) over the window. - **`company_name`** `object` — Modal issuer name across the window's filings. - **`tickers`** `object` — Issuer ticker symbols when known. - **`exclude_10b51` (required)** `boolean` — When true, sells flagged \`aff10b5\_one=true\` are excluded from \`sells\_dollars\` (discretionary-only ranking). - **`window` (required)** `object` — Window the leaderboard ranks over. - **`lookback_days` (required)** `integer` — Window length in days (until - since). - **`since` (required)** `string`, format: `date` — Window start (inclusive). - **`until` (required)** `string`, format: `date` — Window end (inclusive). **Example:** ```json { "window": { "since": "", "until": "", "lookback_days": 1 }, "exclude_10b51": true, "data": [ { "rank": 1, "cik": "", "company_name": "", "tickers": [ "" ], "sells_dollars": "", "sells_count": 1, "distinct_insiders_selling": 1 } ] } ``` ##### Status: 401 Authentication failed - missing or invalid API key ###### Content-Type: application/json - **`message`** `string` **Example:** ```json { "message": "Missing API key in request" } ``` ##### Status: 422 Request validation failed - invalid or missing parameters ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 429 Rate limit exceeded for your tier ###### Content-Type: application/json - **`message`** `string` **Example:** ```json { "message": "" } ``` ##### Status: 500 Unhandled server error — file an issue with the request\_id from the error envelope. ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 502 Upstream dependency failed — gateway, key store, or downstream service unavailable. ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 503 Database query error or timeout — retry with backoff ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ### Largest Form D offerings - **Method:** `GET` - **Path:** `/api/v1/leaderboards/largest-form-d` - **Tags:** Leaderboards Rank Form D filings by `total_offering_amount` (USD), descending, within the window. One row per filing — same issuer can appear multiple times when it has filed multiple Form D rounds in the window. #### Responses ##### Status: 200 Successful Response ###### Content-Type: application/json - **`data` (required)** `array` — Form D filings ranked by \`total\_offering\_amount\` descending. **Items:** - **`cik` (required)** `string` — Filer SEC Central Index Key (short form). - **`filing_id` (required)** `string` — Form D filing identifier. - **`rank` (required)** `integer` — 1-indexed rank in this leaderboard. - **`accepted_time`** `object` — When the SEC accepted the filing. - **`company_name`** `object` — Filer name on the filing. - **`industry_group_type`** `object` — Form D industry-group classification (e.g., 'Technology'). - **`period_of_report`** `object` — Filing's period\_of\_report. - **`total_offering_amount`** `object` — Total offering amount (USD) reported on the filing. - **`window` (required)** `object` — Window the leaderboard ranks over. - **`lookback_days` (required)** `integer` — Window length in days (until - since). - **`since` (required)** `string`, format: `date` — Window start (inclusive). - **`until` (required)** `string`, format: `date` — Window end (inclusive). **Example:** ```json { "window": { "since": "", "until": "", "lookback_days": 1 }, "data": [ { "rank": 1, "filing_id": "", "cik": "", "company_name": "", "accepted_time": "", "period_of_report": "", "total_offering_amount": "", "industry_group_type": "" } ] } ``` ##### Status: 401 Authentication failed - missing or invalid API key ###### Content-Type: application/json - **`message`** `string` **Example:** ```json { "message": "Missing API key in request" } ``` ##### Status: 422 Request validation failed - invalid or missing parameters ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 429 Rate limit exceeded for your tier ###### Content-Type: application/json - **`message`** `string` **Example:** ```json { "message": "" } ``` ##### Status: 500 Unhandled server error — file an issue with the request\_id from the error envelope. ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 502 Upstream dependency failed — gateway, key store, or downstream service unavailable. ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 503 Database query error or timeout — retry with backoff ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ### Most-active filers per family - **Method:** `GET` - **Path:** `/api/v1/leaderboards/most-active-filers` - **Tags:** Leaderboards Rank filers by total filings accepted within the window for the chosen family. `?family=` accepts the same enum used by `/coverage/by-family`. SC 13D/G counts by filer (the holder making the disclosure), not issuer — those filings have no issuer\_cik column. #### Responses ##### Status: 200 Successful Response ###### Content-Type: application/json - **`data` (required)** `array` — Filers ranked by \`filing\_count\` descending. **Items:** - **`cik` (required)** `string` — Issuer SEC Central Index Key (short form). - **`filing_count` (required)** `integer` — Filings accepted in the window for this (cik, family) pair. - **`rank` (required)** `integer` — 1-indexed rank in this leaderboard. - **`company_name`** `object` — Modal issuer name across the window's filings. - **`tickers`** `object` — Issuer ticker symbols when known. - **`family` (required)** `object` — Family this leaderboard is scoped to. - **`window` (required)** `object` — Window the leaderboard ranks over. - **`lookback_days` (required)** `integer` — Window length in days (until - since). - **`since` (required)** `string`, format: `date` — Window start (inclusive). - **`until` (required)** `string`, format: `date` — Window end (inclusive). **Example:** ```json { "window": { "since": "", "until": "", "lookback_days": 1 }, "family": "insiders", "data": [ { "rank": 1, "cik": "", "company_name": "", "tickers": [ "" ], "filing_count": 1 } ] } ``` ##### Status: 401 Authentication failed - missing or invalid API key ###### Content-Type: application/json - **`message`** `string` **Example:** ```json { "message": "Missing API key in request" } ``` ##### Status: 422 Request validation failed - invalid or missing parameters ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 429 Rate limit exceeded for your tier ###### Content-Type: application/json - **`message`** `string` **Example:** ```json { "message": "" } ``` ##### Status: 500 Unhandled server error — file an issue with the request\_id from the error envelope. ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 502 Upstream dependency failed — gateway, key store, or downstream service unavailable. ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 503 Database query error or timeout — retry with backoff ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ### Filers with the highest amendment ratio per family - **Method:** `GET` - **Path:** `/api/v1/leaderboards/most-amended` - **Tags:** Leaderboards Rank filers by `amendment_count / filing_count` within the window — a known proxy for sloppy filers / refiling risk. `?min_filings=` (default 3) filters out the long-tail of single-filing filers whose 1/1 ratio would dominate the rank without being informative. #### Responses ##### Status: 200 Successful Response ###### Content-Type: application/json - **`data` (required)** `array` — Filers ranked by \`amendment\_ratio\` descending. **Items:** - **`amendment_count` (required)** `integer` — Filings flagged as amendments within \`filing\_count\`. - **`amendment_ratio` (required)** `number` — amendment\_count / filing\_count, clamped to \[0, 1]. - **`cik` (required)** `string` — Issuer SEC Central Index Key (short form). - **`filing_count` (required)** `integer` — Filings accepted in the window for this (cik, family) pair. - **`rank` (required)** `integer` — 1-indexed rank in this leaderboard. - **`company_name`** `object` — Modal issuer name across the window's filings. - **`tickers`** `object` — Issuer ticker symbols when known. - **`family` (required)** `object` — Family this leaderboard is scoped to. - **`window` (required)** `object` — Window the leaderboard ranks over. - **`lookback_days` (required)** `integer` — Window length in days (until - since). - **`since` (required)** `string`, format: `date` — Window start (inclusive). - **`until` (required)** `string`, format: `date` — Window end (inclusive). **Example:** ```json { "window": { "since": "", "until": "", "lookback_days": 1 }, "family": "insiders", "data": [ { "rank": 1, "cik": "", "company_name": "", "tickers": [ "" ], "filing_count": 1, "amendment_count": 1, "amendment_ratio": 1 } ] } ``` ##### Status: 401 Authentication failed - missing or invalid API key ###### Content-Type: application/json - **`message`** `string` **Example:** ```json { "message": "Missing API key in request" } ``` ##### Status: 422 Request validation failed - invalid or missing parameters ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 429 Rate limit exceeded for your tier ###### Content-Type: application/json - **`message`** `string` **Example:** ```json { "message": "" } ``` ##### Status: 500 Unhandled server error — file an issue with the request\_id from the error envelope. ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 502 Upstream dependency failed — gateway, key store, or downstream service unavailable. ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 503 Database query error or timeout — retry with backoff ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ### Top issuers by composite governance-pressure score - **Method:** `GET` - **Path:** `/api/v1/leaderboards/governance-pressure` - **Tags:** Leaderboards Rank issuers by a coarse pressure score combining insider-disposition intensity, distinct-insider count, and Schedule 13D/G filing volume naming the issuer (matched on issuer\_name). The score formula mirrors the per-issuer `/signals/governance-features` service — see that endpoint for full component definitions. #### Responses ##### Status: 200 Successful Response ###### Content-Type: application/json - **`data` (required)** `array` — Issuers ranked by \`governance\_pressure\_score\` descending. **Items:** - **`cik` (required)** `string` — Issuer SEC Central Index Key (short form). - **`dispositions_dollars` (required)** `string` — Sum of disposed-share value (USD) in the window. - **`distinct_insiders_selling` (required)** `integer` — Insiders with disposition transactions in the window. - **`governance_pressure_score` (required)** `number` — Coarse pressure score \[0, 1+] composed of insider-disposition intensity, distinct-insider count, and SC13 filing volume. - **`rank` (required)** `integer` — 1-indexed rank in this leaderboard. - **`sc13_filings_count` (required)** `integer` — Schedule 13D/G filings naming this issuer (by name match) in the window. - **`company_name`** `object` — Modal issuer name across the window's filings. - **`tickers`** `object` — Issuer ticker symbols when known. - **`window` (required)** `object` — Window the leaderboard ranks over. - **`lookback_days` (required)** `integer` — Window length in days (until - since). - **`since` (required)** `string`, format: `date` — Window start (inclusive). - **`until` (required)** `string`, format: `date` — Window end (inclusive). **Example:** ```json { "window": { "since": "", "until": "", "lookback_days": 1 }, "data": [ { "rank": 1, "cik": "", "company_name": "", "tickers": [ "" ], "governance_pressure_score": 1, "distinct_insiders_selling": 1, "dispositions_dollars": "", "sc13_filings_count": 1 } ] } ``` ##### Status: 401 Authentication failed - missing or invalid API key ###### Content-Type: application/json - **`message`** `string` **Example:** ```json { "message": "Missing API key in request" } ``` ##### Status: 422 Request validation failed - invalid or missing parameters ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 429 Rate limit exceeded for your tier ###### Content-Type: application/json - **`message`** `string` **Example:** ```json { "message": "" } ``` ##### Status: 500 Unhandled server error — file an issue with the request\_id from the error envelope. ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 502 Upstream dependency failed — gateway, key store, or downstream service unavailable. ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 503 Database query error or timeout — retry with backoff ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ### Issuers a single insider has filed Form 3/4/5 against - **Method:** `GET` - **Path:** `/api/v1/network/director-interlocks` - **Tags:** Network Returns every issuer the supplied reporting owner has filed Form 3/4/5 against, with per-issuer flags (`is_director` / `is_officer` / `is_ten_percent_owner`) and filing counts. Useful for governance research — "is this person on multiple boards?" The result is the issuer-set neighborhood of one insider in the Form 4 graph. **Examples:** - Insider's full board list: `?cik=1214156` (Tim Cook) #### Responses ##### Status: 200 Successful Response ###### Content-Type: application/json - **`boards` (required)** `array` — Distinct issuers this insider has filed Form 3/4/5 against, sorted by filing\_count descending. **Items:** - **`cik` (required)** `string` — Issuer CIK (canonical short form, no leading zeros). - **`filing_count` (required)** `integer` — Form 3/4/5 filings this insider has made naming this issuer. - **`company_name`** `object` — Modal issuer name across the insider's filings. - **`is_director`** `object` — Whether the insider was flagged as a director on any of their filings for this issuer. - **`is_officer`** `object` — Whether the insider was flagged as an officer on any of their filings for this issuer. - **`is_ten_percent_owner`** `object` — Whether the insider was flagged as a 10%+ owner on any of their filings for this issuer. - **`period_max`** `object` — Latest period\_of\_report observed for this insider's filings on this issuer. - **`period_min`** `object` — Earliest period\_of\_report observed for this insider's filings on this issuer. - **`ticker`** `object` — Issuer ticker symbol when known (modal across the insider's filings). - **`rpt_owner_cik` (required)** `string` — Reporting-owner CIK queried (canonical short form). - **`insider_name`** `object` — Modal insider name across their filings. **Example:** ```json { "rpt_owner_cik": "", "insider_name": "", "boards": [ { "cik": "", "company_name": "", "ticker": "", "filing_count": 1, "is_director": true, "is_officer": true, "is_ten_percent_owner": true, "period_min": "", "period_max": "" } ] } ``` ##### Status: 401 Authentication failed - missing or invalid API key ###### Content-Type: application/json - **`message`** `string` **Example:** ```json { "message": "Missing API key in request" } ``` ##### Status: 422 Request validation failed - invalid or missing parameters ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 429 Rate limit exceeded for your tier ###### Content-Type: application/json - **`message`** `string` **Example:** ```json { "message": "" } ``` ##### Status: 500 Unhandled server error — file an issue with the request\_id from the error envelope. ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 502 Upstream dependency failed — gateway, key store, or downstream service unavailable. ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 503 Database query error or timeout — retry with backoff ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ### Recurring co-filer pairs on Schedule 13D/G - **Method:** `GET` - **Path:** `/api/v1/network/13d-coordinated-filers` - **Tags:** Network Identifies pairs of reporting persons who appear together on multiple distinct Schedule 13D/G filings. A high `co_filing_count` paired with multiple distinct issuers is a known activism-partnership signal. **Examples:** - Top recurring pairs: `/network/13d-coordinated-filers` - Last 12 months only: `/network/13d-coordinated-filers?since=2025-04-30` - Tighter threshold: `/network/13d-coordinated-filers?min_co_filings=5` #### Responses ##### Status: 200 Successful Response ###### Content-Type: application/json - **`min_co_filings` (required)** `integer` — Minimum co-filing threshold applied (default 2 — pairs with a single shared filing are excluded). - **`pairs` (required)** `array` — Recurring co-filer pairs ranked by co\_filing\_count descending. **Items:** - **`co_filing_count` (required)** `integer` — Number of distinct Schedule 13D/G filings where both persons appear. - **`distinct_issuer_names` (required)** `array` — Up to 10 issuer names this pair has co-filed against. **Items:** `string` - **`distinct_issuers` (required)** `integer` — Number of distinct issuer CUSIPs the pair has co-filed against. - **`person_a_name` (required)** `string` — Reporting person A's name (lexicographically first member of the pair). - **`person_b_name` (required)** `string` — Reporting person B's name (lexicographically second member of the pair). - **`last_filing_accepted`** `object` — Most recent accepted\_time across the pair's co-filings. - **`since`** `object` — Window start (inclusive) applied to filings.accepted\_time, when supplied. **Example:** ```json { "since": "", "min_co_filings": 1, "pairs": [ { "person_a_name": "", "person_b_name": "", "co_filing_count": 1, "distinct_issuers": 1, "distinct_issuer_names": [ "" ], "last_filing_accepted": "" } ] } ``` ##### Status: 401 Authentication failed - missing or invalid API key ###### Content-Type: application/json - **`message`** `string` **Example:** ```json { "message": "Missing API key in request" } ``` ##### Status: 422 Request validation failed - invalid or missing parameters ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 429 Rate limit exceeded for your tier ###### Content-Type: application/json - **`message`** `string` **Example:** ```json { "message": "" } ``` ##### Status: 500 Unhandled server error — file an issue with the request\_id from the error envelope. ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 502 Upstream dependency failed — gateway, key store, or downstream service unavailable. ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 503 Database query error or timeout — retry with backoff ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ### Form D total-offering money-map by industry - **Method:** `GET` - **Path:** `/api/v1/rollups/private-capital-by-industry` - **Tags:** Rollups Group Form D filings by `industry_group_type` and sum `total_offering_amount` and `total_amount_sold`. Returns one row per industry, sorted by total offering size descending. Useful for tracking sector capital flow ("VCs are pouring money into biotech this quarter"). **Examples:** - Last 12 months: `?since=2025-04-30` - Calendar 2024: `?since=2024-01-01&until=2024-12-31` #### Responses ##### Status: 200 Successful Response ###### Content-Type: application/json - **`data` (required)** `array` — Industries ranked by \`total\_offering\_amount\_sum\` descending. **Items:** - **`distinct_filer_count` (required)** `integer` — Distinct filer CIKs within this industry in the window. - **`filing_count` (required)** `integer` — Form D filings classified to this industry within the window. - **`industry_group_type` (required)** `string` — Form D \`industry\_group\_type\` value (e.g., 'Pooled Investment Fund'). - **`total_amount_sold_sum`** `object` — Sum of \`total\_amount\_sold\` (USD) across the filings in this industry. - **`total_offering_amount_sum`** `object` — Sum of \`total\_offering\_amount\` (USD) across the filings in this industry; null when no filing reports an amount. - **`since`** `object` — Window start applied to filings.accepted\_time, when supplied. - **`until`** `object` — Window end applied to filings.accepted\_time, when supplied. **Example:** ```json { "since": "", "until": "", "data": [ { "industry_group_type": "", "filing_count": 1, "distinct_filer_count": 1, "total_offering_amount_sum": "", "total_amount_sold_sum": "" } ] } ``` ##### Status: 401 Authentication failed - missing or invalid API key ###### Content-Type: application/json - **`message`** `string` **Example:** ```json { "message": "Missing API key in request" } ``` ##### Status: 422 Request validation failed - invalid or missing parameters ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 429 Rate limit exceeded for your tier ###### Content-Type: application/json - **`message`** `string` **Example:** ```json { "message": "" } ``` ##### Status: 500 Unhandled server error — file an issue with the request\_id from the error envelope. ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 502 Upstream dependency failed — gateway, key store, or downstream service unavailable. ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 503 Database query error or timeout — retry with backoff ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ### Insider buy/sell flow rolled up by sector (SIC) - **Method:** `GET` - **Path:** `/api/v1/rollups/insider-sentiment-by-sic` - **Tags:** Rollups Sum Form 4 dispositions and acquisitions by filer `sic`. Returns one row per SIC with `buys_dollars`, `sells_dollars`, the buy/sell ratio, and counts. Useful for sector-mood dashboards: "tech (SIC 7372) saw 65% buys in the last 90 days; energy (SIC 1311) saw 18%." #### Responses ##### Status: 200 Successful Response ###### Content-Type: application/json - **`data` (required)** `array` — SIC sectors ranked by absolute \`buys\_dollars + sells\_dollars\` descending. **Items:** - **`buys_count` (required)** `integer` — Buy transaction count in the window. - **`buys_dollars` (required)** `string` — Sum of acquired-share value (USD) — \`transaction\_acquired\_disposed\_code='A'\`. - **`sells_count` (required)** `integer` — Sell transaction count in the window. - **`sells_dollars` (required)** `string` — Sum of disposed-share value (USD) — \`transaction\_acquired\_disposed\_code='D'\`. - **`buy_sell_ratio`** `object` — buys\_dollars / (buys\_dollars + sells\_dollars), in \[0, 1]. Null when both totals are zero. - **`sic`** `object` — Form 4 filer's SIC code (4 digits, when known). - **`sic_description`** `object` — SIC description (modal across the rollup). - **`since`** `object` — Window start applied to transaction\_date, when supplied. - **`until`** `object` — Window end applied to transaction\_date, when supplied. **Example:** ```json { "since": "", "until": "", "data": [ { "sic": "", "sic_description": "", "buys_dollars": "", "sells_dollars": "", "buys_count": 1, "sells_count": 1, "buy_sell_ratio": 1 } ] } ``` ##### Status: 401 Authentication failed - missing or invalid API key ###### Content-Type: application/json - **`message`** `string` **Example:** ```json { "message": "Missing API key in request" } ``` ##### Status: 422 Request validation failed - invalid or missing parameters ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 429 Rate limit exceeded for your tier ###### Content-Type: application/json - **`message`** `string` **Example:** ```json { "message": "" } ``` ##### Status: 500 Unhandled server error — file an issue with the request\_id from the error envelope. ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 502 Upstream dependency failed — gateway, key store, or downstream service unavailable. ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 503 Database query error or timeout — retry with backoff ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ### Per-family changefeed over accepted\_time - **Method:** `GET` - **Path:** `/api/v1/changes/{family}` - **Tags:** Changes Returns a chronologically-sorted feed of filings accepted in the chosen family within the supplied window. Each row carries the filing\_id, cik, accepted\_time, and an `action` flag indicating whether the row is `created` (an original filing) or `amended` (an amendment). The natural integration pattern is to keep a single cursor (the most recent `accepted_time` you've seen) and poll `/changes/{family}?since=` for incremental updates. **Examples:** - Insider filings since yesterday: `/changes/insiders?since=2026-04-28` - Form D filings within a window: `/changes/private_offerings?since=2026-04-01&until=2026-04-30` #### Responses ##### Status: 200 Successful Response ###### Content-Type: application/json - **`data` (required)** `array` — Change events sorted by accepted\_time ascending (oldest first). **Items:** - **`accepted_time` (required)** `string`, format: `date-time` — When the SEC accepted the filing (the changefeed cursor). - **`action` (required)** `string`, possible values: `"created", "amended"` — \`amended\` when the filing is an amendment of an earlier filing in the same family; \`created\` otherwise. - **`family` (required)** `object` — Family this change belongs to. - **`filing_id` (required)** `string` — Filing identifier. - **`cik`** `object` — Filer CIK on the filing (canonical short form). - **`form_type`** `object` — SEC form type. - **`family` (required)** `object` — Family the changefeed is scoped to. - **`page_size` (required)** `integer` — Results per page - **`page`** `integer`, default: `1` — Current page number (1-indexed) - **`total`** `integer`, default: `0` — Total count of matching rows - **`total_pages`** `integer`, default: `1` — Total number of pages **Example:** ```json { "total": 0, "page": 1, "page_size": 1, "total_pages": 1, "family": "insiders", "data": [ { "family": null, "filing_id": "", "cik": "", "form_type": "", "accepted_time": "", "action": "created" } ] } ``` ##### Status: 401 Authentication failed - missing or invalid API key ###### Content-Type: application/json - **`message`** `string` **Example:** ```json { "message": "Missing API key in request" } ``` ##### Status: 422 Request validation failed - invalid or missing parameters ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 429 Rate limit exceeded for your tier ###### Content-Type: application/json - **`message`** `string` **Example:** ```json { "message": "" } ``` ##### Status: 500 Unhandled server error — file an issue with the request\_id from the error envelope. ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 502 Upstream dependency failed — gateway, key store, or downstream service unavailable. ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 503 Database query error or timeout — retry with backoff ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ### List SEC filings (cross-cutting) - **Method:** `GET` - **Path:** `/api/v1/filings` - **Tags:** Filings List SEC filings across every family the ETL covers, with filtering by filer, ticker, form type, and date ranges. **Examples:** - All Form 4 filings: `?form_type=4` - Filings by AAPL filers: `?ticker=AAPL` - Filings by a specific CIK: `?cik=1209191` #### Responses ##### Status: 200 Successful Response ###### Content-Type: application/json - **`data` (required)** `array` — Array of filings **Items:** - **`accession_num` (required)** `object` — EDGAR accession number derived from filing\_id (e.g., '0000320193-24-000123') - **`cik` (required)** `string` — Filer SEC Central Index Key - **`filing_id` (required)** `string` — Unique filing identifier - **`form_type` (required)** `string` — SEC form type (e.g., '4', '13F-HR', 'D') - **`source_url` (required)** `object` — Canonical SEC EDGAR Archives URL pointing at the filing's index page - **`accepted_time`** `object` — When the SEC accepted the filing - **`filer_name`** `object` — Filer entity name - **`filer_sic`** `object` — Filer Standard Industrial Classification code (e.g., '7372' Prepackaged Software) - **`filer_tickers`** `object` — Ticker symbols associated with the filer - **`is_valid`** `object` — Whether the filing passed validation - **`period_of_report`** `object` — Reporting period end date (null on the cross-cutting index) - **`page_size` (required)** `integer` — Results per page - **`page`** `integer`, default: `1` — Current page number (1-indexed) - **`total`** `integer`, default: `0` — Total count of matching rows - **`total_pages`** `integer`, default: `1` — Total number of pages **Example:** ```json { "total": 0, "page": 1, "page_size": 1, "total_pages": 1, "data": [ { "accepted_time": "2024-03-17T16:30:00", "accession_num": "0001209191-24-031337", "cik": "1209191", "filer_name": "DOE JOHN", "filer_sic": "3571", "filer_tickers": [ "AAPL" ], "filing_id": "0001209191_0001209191-24-031337", "form_type": "4", "is_valid": true, "period_of_report": "2024-03-15", "source_url": "https://www.sec.gov/Archives/edgar/data/1209191/000120919124031337/0001209191-24-031337-index.htm" } ] } ``` ##### Status: 401 Authentication failed - missing or invalid API key ###### Content-Type: application/json - **`message`** `string` **Example:** ```json { "message": "Missing API key in request" } ``` ##### Status: 422 Request validation failed - invalid or missing parameters ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 429 Rate limit exceeded for your tier ###### Content-Type: application/json - **`message`** `string` **Example:** ```json { "message": "" } ``` ##### Status: 500 Unhandled server error — file an issue with the request\_id from the error envelope. ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 502 Upstream dependency failed — gateway, key store, or downstream service unavailable. ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 503 Database query error or timeout — retry with backoff ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ### List insider filings (Forms 3, 4, 5) - **Method:** `GET` - **Path:** `/api/v1/insiders` - **Tags:** Insiders List Form 3/4/5 filings (insider beneficial ownership reports). **Required:** at least one of `cik` (insider's CIK), `ticker` (issuer trading symbol), `issuer_cik`, or both `period_start`+`period_end` / both `accepted_start`+`accepted_end`. Returns `400 MISSING_PARAMETER` otherwise. **Examples:** - All Form 4 filings for AAPL: `?ticker=AAPL&form_type=4` - A specific insider's filings: `?cik=1209191` - A company's amendments only: `?issuer_cik=320193&is_amendment=true` #### Responses ##### Status: 200 Successful Response ###### Content-Type: application/json - **`data` (required)** `array` — Page of Form 3/4/5 filing rows **Items:** - **`accession_num` (required)** `object` — EDGAR accession number derived from filing\_id (e.g., '0000320193-24-000123') - **`cik` (required)** `string` — Filer (insider) SEC Central Index Key - **`filing_id` (required)** `string` — Unique filing identifier - **`form_type` (required)** `string` — SEC form type ('3', '3/A', '4', '4/A', '5', '5/A') - **`rpt_owner_cik` (required)** `string` — Alias of \`cik\` — the reporting owner's CIK. Matches the \`{rpt\_owner\_cik}\` path parameter on \`/insiders/owners/...\` so callers can pass it through without remapping. - **`source_url` (required)** `object` — Canonical SEC EDGAR Archives URL pointing at the filing's index page - **`accepted_time`** `object` — When the SEC accepted the filing - **`filer_name`** `object` — Filer (insider) name - **`is_amendment`** `object` — True if this filing is an amendment ('/A' suffix) - **`is_valid`** `object` — Whether the filing passed validation - **`issuer_cik`** `object` — Issuer (company) CIK — the company whose securities are being reported - **`issuer_name`** `object` — Issuer (company) legal name - **`issuer_trading_symbol`** `object` — Issuer ticker symbol - **`period_of_report`** `object` — Reporting period end date - **`page_size` (required)** `integer` — Results per page - **`page`** `integer`, default: `1` — Current page number (1-indexed) - **`total`** `integer`, default: `0` — Total count of matching rows - **`total_pages`** `integer`, default: `1` — Total number of pages **Example:** ```json { "total": 0, "page": 1, "page_size": 1, "total_pages": 1, "data": [ { "filing_id": "", "cik": "", "form_type": "", "is_amendment": true, "period_of_report": "", "accepted_time": "", "is_valid": true, "filer_name": "", "issuer_cik": "", "issuer_name": "", "issuer_trading_symbol": "", "accession_num": "", "source_url": "", "rpt_owner_cik": "" } ] } ``` ##### Status: 400 Request rejected — usually a missing required parameter or an at-least-one-of constraint not satisfied. ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 401 Authentication failed - missing or invalid API key ###### Content-Type: application/json - **`message`** `string` **Example:** ```json { "message": "Missing API key in request" } ``` ##### Status: 422 Request validation failed - invalid or missing parameters ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 429 Rate limit exceeded for your tier ###### Content-Type: application/json - **`message`** `string` **Example:** ```json { "message": "" } ``` ##### Status: 500 Unhandled server error — file an issue with the request\_id from the error envelope. ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 502 Upstream dependency failed — gateway, key store, or downstream service unavailable. ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 503 Database query error or timeout — retry with backoff ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ### Cross-filing insider transaction stream - **Method:** `GET` - **Path:** `/api/v1/insiders/transactions` - **Tags:** Insiders Stream insider transactions across many filings (non-derivative, derivative, or both — set `transaction_kind`). **Required:** at least one of `issuer_cik`, `issuer_ticker`, `rpt_owner_cik`. Returns `400 MISSING_PARAMETER` otherwise. **Examples:** - All AAPL insider purchases: `?issuer_ticker=AAPL&transaction_code=P` - Tim Cook's recent transactions: `?rpt_owner_cik=...` - Big trades only: `?issuer_ticker=AAPL&min_value=1000000` #### Responses ##### Status: 200 Successful Response ###### Content-Type: application/json - **`data` (required)** `array` — Page of insider-transaction rows **Items:** - **`filing_id` (required)** `string` — Filing the transaction belongs to - **`record_index` (required)** `integer` — Per-filing 0-based ordinal of the row - **`transaction_kind` (required)** `object` — Whether this row came from the non-derivative or derivative table - **`conversion_or_exercise_price`** `object` — Deriv only: strike / conversion price per underlying share - **`direct_or_indirect_ownership`** `object` — 'D' = direct ownership, 'I' = indirect - **`exercise_date`** `object` — Deriv only: earliest exercise date - **`expiration_date`** `object` — Deriv only: expiration date - **`filer_cik`** `object` — Reporting owner CIK(s) for this filing. Distinct values, no implied ordering with \`filer\_name\`. - **`filer_name`** `object` — Reporting owner name(s) for this filing. Multiple owners are joined with \`; \` (alphabetical) — Form 4 filings occasionally list more than one reporting person. - **`issuer_cik`** `object` — Issuer (company) CIK - **`issuer_trading_symbol`** `object` — Issuer ticker symbol - **`security_title`** `object` — Security name (e.g., 'Common Stock', 'Stock Option') - **`shares_owned_following_transaction`** `object` — Total shares (or derivatives) owned after this transaction - **`transaction_acquired_disposed_code`** `object` — 'A' = acquired, 'D' = disposed - **`transaction_code`** `object` — Single-letter transaction code (P, S, A, M, G, F, etc.) - **`transaction_date`** `object` — Date the transaction occurred - **`transaction_price_per_share`** `object` — Price per share; 0 for grants and gifts - **`transaction_shares`** `object` — Number of shares (or derivative instruments) involved - **`transaction_total_value`** `object` — Total USD value — for deriv rows the form's transaction\_total\_value; for nonderiv rows shares × price\_per\_share - **`underlying_security_shares`** `object` — Deriv only: number of underlying shares the derivative covers - **`underlying_security_title`** `object` — Deriv only: underlying security title - **`page_size` (required)** `integer` — Results per page - **`page`** `integer`, default: `1` — Current page number (1-indexed) - **`total`** `integer`, default: `0` — Total count of matching rows - **`total_pages`** `integer`, default: `1` — Total number of pages **Example:** ```json { "total": 0, "page": 1, "page_size": 1, "total_pages": 1, "data": [ { "direct_or_indirect_ownership": "D", "filer_cik": [ "0001214156" ], "filer_name": "Cook Timothy D.", "filing_id": "0000320193_0001127602-24-031337", "issuer_cik": "0000320193", "issuer_trading_symbol": "AAPL", "record_index": 0, "security_title": "Common Stock", "shares_owned_following_transaction": "248500", "transaction_acquired_disposed_code": "D", "transaction_code": "S", "transaction_date": "2024-03-15", "transaction_kind": "nonderiv", "transaction_price_per_share": "172.50", "transaction_shares": "12000", "transaction_total_value": "2070000.00" } ] } ``` ##### Status: 401 Authentication failed - missing or invalid API key ###### Content-Type: application/json - **`message`** `string` **Example:** ```json { "message": "Missing API key in request" } ``` ##### Status: 422 Request validation failed - invalid or missing parameters ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 429 Rate limit exceeded for your tier ###### Content-Type: application/json - **`message`** `string` **Example:** ```json { "message": "" } ``` ##### Status: 500 Unhandled server error — file an issue with the request\_id from the error envelope. ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 502 Upstream dependency failed — gateway, key store, or downstream service unavailable. ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 503 Database query error or timeout — retry with backoff ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ### List filings where a person is a reporting owner - **Method:** `GET` - **Path:** `/api/v1/insiders/owners/{rpt_owner_cik}` - **Tags:** Insiders Every Form 3/4/5 filing where `rpt_owner_cik` appears in the reporting owners list. #### Responses ##### Status: 200 Successful Response ###### Content-Type: application/json - **`data` (required)** `array` — Page of Form 3/4/5 filing rows **Items:** - **`accession_num` (required)** `object` — EDGAR accession number derived from filing\_id (e.g., '0000320193-24-000123') - **`cik` (required)** `string` — Filer (insider) SEC Central Index Key - **`filing_id` (required)** `string` — Unique filing identifier - **`form_type` (required)** `string` — SEC form type ('3', '3/A', '4', '4/A', '5', '5/A') - **`rpt_owner_cik` (required)** `string` — Alias of \`cik\` — the reporting owner's CIK. Matches the \`{rpt\_owner\_cik}\` path parameter on \`/insiders/owners/...\` so callers can pass it through without remapping. - **`source_url` (required)** `object` — Canonical SEC EDGAR Archives URL pointing at the filing's index page - **`accepted_time`** `object` — When the SEC accepted the filing - **`filer_name`** `object` — Filer (insider) name - **`is_amendment`** `object` — True if this filing is an amendment ('/A' suffix) - **`is_valid`** `object` — Whether the filing passed validation - **`issuer_cik`** `object` — Issuer (company) CIK — the company whose securities are being reported - **`issuer_name`** `object` — Issuer (company) legal name - **`issuer_trading_symbol`** `object` — Issuer ticker symbol - **`period_of_report`** `object` — Reporting period end date - **`page_size` (required)** `integer` — Results per page - **`page`** `integer`, default: `1` — Current page number (1-indexed) - **`total`** `integer`, default: `0` — Total count of matching rows - **`total_pages`** `integer`, default: `1` — Total number of pages **Example:** ```json { "total": 0, "page": 1, "page_size": 1, "total_pages": 1, "data": [ { "filing_id": "", "cik": "", "form_type": "", "is_amendment": true, "period_of_report": "", "accepted_time": "", "is_valid": true, "filer_name": "", "issuer_cik": "", "issuer_name": "", "issuer_trading_symbol": "", "accession_num": "", "source_url": "", "rpt_owner_cik": "" } ] } ``` ##### Status: 401 Authentication failed - missing or invalid API key ###### Content-Type: application/json - **`message`** `string` **Example:** ```json { "message": "Missing API key in request" } ``` ##### Status: 404 Resource not found ###### Content-Type: application/json - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } ``` ##### Status: 422 Request validation failed - invalid or missing parameters ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 429 Rate limit exceeded for your tier ###### Content-Type: application/json - **`message`** `string` **Example:** ```json { "message": "" } ``` ##### Status: 500 Unhandled server error — file an issue with the request\_id from the error envelope. ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 502 Upstream dependency failed — gateway, key store, or downstream service unavailable. ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 503 Database query error or timeout — retry with backoff ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ### List issuers with insider-filing data - **Method:** `GET` - **Path:** `/api/v1/insiders/entities` - **Tags:** Insiders Discovery endpoint — list distinct issuers (public companies) with Form 3/4/5 filings on file, with summary statistics for each. Returns one row per `issuer_cik` with: - Issuer identifiers (CIK, modal name, distinct issuer trading symbols) - `filing_count` — total Form 3/4/5 filings naming the issuer - `period_min` / `period_max` — earliest and latest period\_of\_report **Examples:** - All issuers: `/insiders/entities` - Search by name or ticker: `/insiders/entities?search=apple` - Most-active issuers first: `/insiders/entities?sort=filing_count&order=desc` **See also:** `/api/v1/entities/{cik}` for the registry-level profile (SIC, exchanges, EIN, LEI, filer status flags) and outbound link map for any of the issuers returned here. #### Responses ##### Status: 200 Successful Response ###### Content-Type: application/json - **`data` (required)** `array` — Page of issuers with Form 3/4/5 data on file. **Items:** - **`cik` (required)** `string` — Required. Issuer SEC Central Index Key (canonical short form, no leading zeros). - **`filing_count` (required)** `integer` — Required. Total Form 3/4/5 filings on file naming this issuer. - **`company_name`** `object` — Optional. Modal issuer name across the issuer's Form 3/4/5 filings. - **`period_max`** `object` — Optional. Latest period\_of\_report observed for this issuer. - **`period_min`** `object` — Optional. Earliest period\_of\_report observed for this issuer. - **`tickers`** `object` — Optional. Issuer ticker symbols sampled from one filing's \`filer\_tickers\`. - **`page_size` (required)** `integer` — Results per page - **`page`** `integer`, default: `1` — Current page number (1-indexed) - **`total`** `integer`, default: `0` — Total count of matching rows - **`total_pages`** `integer`, default: `1` — Total number of pages **Example:** ```json { "total": 0, "page": 1, "page_size": 1, "total_pages": 1, "data": [ { "cik": "320193", "company_name": "Apple Inc.", "filing_count": 184, "period_max": "2024-03-15", "period_min": "2018-04-30", "tickers": [ "AAPL" ] } ] } ``` ##### Status: 401 Authentication failed - missing or invalid API key ###### Content-Type: application/json - **`message`** `string` **Example:** ```json { "message": "Missing API key in request" } ``` ##### Status: 422 Request validation failed - invalid or missing parameters ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 429 Rate limit exceeded for your tier ###### Content-Type: application/json - **`message`** `string` **Example:** ```json { "message": "" } ``` ##### Status: 500 Unhandled server error — file an issue with the request\_id from the error envelope. ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 502 Upstream dependency failed — gateway, key store, or downstream service unavailable. ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 503 Database query error or timeout — retry with backoff ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ### Form 4 transactions filed late under Section 16(a) - **Method:** `GET` - **Path:** `/api/v1/insiders/late-filers` - **Tags:** Insiders Section 16(a) requires Form 4 within 2 business days of the reportable transaction. Returns transactions whose accepted\_time gap exceeds that deadline, with both business-day and calendar-day deltas. Late filings are a known governance red-flag — both date fields are already on every Form 4, but no other endpoint surfaces them as a filtered list. **Examples:** - Last year, sorted most-late-first: `?lookback_days=365` - AAPL only: `?lookback_days=365&ticker=AAPL` #### Responses ##### Status: 200 Successful Response ###### Content-Type: application/json - **`data` (required)** `array` — Late filings sorted by \`business\_days\_late\` descending. **Items:** - **`accepted_time` (required)** `string`, format: `date-time` — When the SEC accepted the filing. - **`business_days_late` (required)** `integer` — Business-days delay between transaction\_date and accepted\_time. - **`days_late` (required)** `integer` — Calendar-days delay (informational; the regulatory deadline is in business days). - **`filing_id` (required)** `string` — Form 4 filing identifier. - **`transaction_date` (required)** `string`, format: `date` — Date of the reportable transaction. - **`issuer_cik`** `object` — Issuer CIK (canonical short form). - **`issuer_name`** `object` — Issuer name on the filing. - **`issuer_trading_symbol`** `object` — Issuer ticker symbol. - **`rpt_owner_cik`** `object` — Reporting owner CIK on the filing (canonical short form). - **`rpt_owner_name`** `object` — Reporting owner name. - **`deadline_business_days` (required)** `integer` — Number of business days after transaction\_date by which Form 4 must be filed under Section 16(a) — currently 2. - **`page_size` (required)** `integer` — Results per page - **`page`** `integer`, default: `1` — Current page number (1-indexed) - **`total`** `integer`, default: `0` — Total count of matching rows - **`total_pages`** `integer`, default: `1` — Total number of pages **Example:** ```json { "total": 0, "page": 1, "page_size": 1, "total_pages": 1, "deadline_business_days": 1, "data": [ { "filing_id": "", "rpt_owner_cik": "", "rpt_owner_name": "", "issuer_cik": "", "issuer_name": "", "issuer_trading_symbol": "", "transaction_date": "", "accepted_time": "", "business_days_late": 1, "days_late": 1 } ] } ``` ##### Status: 401 Authentication failed - missing or invalid API key ###### Content-Type: application/json - **`message`** `string` **Example:** ```json { "message": "Missing API key in request" } ``` ##### Status: 422 Request validation failed - invalid or missing parameters ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 429 Rate limit exceeded for your tier ###### Content-Type: application/json - **`message`** `string` **Example:** ```json { "message": "" } ``` ##### Status: 500 Unhandled server error — file an issue with the request\_id from the error envelope. ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 502 Upstream dependency failed — gateway, key store, or downstream service unavailable. ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 503 Database query error or timeout — retry with backoff ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ### Lifetime Form 4 record for one reporting owner - **Method:** `GET` - **Path:** `/api/v1/insiders/biography/{rpt_owner_cik}` - **Tags:** Insiders Returns the lifetime Form 3/4/5 footprint for a single reporting owner: per-issuer rollups (filing count, transaction count, lifetime buy/sell dollars, first/last transaction dates) plus officer/director/ 10%+ flags. The natural copy-trader query: "show me Bezos's full AMZN trade history" — one call instead of paginating /insiders/transactions. **Examples:** - Tim Cook (CIK 1214156): `/insiders/biography/1214156` #### Responses ##### Status: 200 Successful Response ###### Content-Type: application/json - **`issuers` (required)** `array` — Per-issuer lifetime rollups, sorted by \`last\_transaction\_date\` descending. **Items:** - **`buys_dollars` (required)** `string` — Sum of acquired-share value (USD) across the lifetime. - **`filing_count` (required)** `integer` — Form 3/4/5 filings for this issuer. - **`sells_dollars` (required)** `string` — Sum of disposed-share value (USD) across the lifetime. - **`transaction_count` (required)** `integer` — Nonderivative transactions for this issuer. - **`first_transaction_date`** `object` — Earliest reportable transaction\_date for this issuer. - **`is_director`** `object` — Whether the insider was flagged as a director on any filing. - **`is_officer`** `object` — Whether the insider was flagged as an officer on any filing. - **`is_ten_percent_owner`** `object` — Whether the insider was flagged as a 10%+ owner on any filing. - **`issuer_cik`** `object` — Issuer CIK (canonical short form). - **`issuer_name`** `object` — Issuer name. - **`issuer_trading_symbol`** `object` — Issuer ticker symbol. - **`last_transaction_date`** `object` — Latest reportable transaction\_date for this issuer. - **`rpt_owner_cik` (required)** `string` — Reporting owner CIK queried (canonical short form). - **`total_filings` (required)** `integer` — Total Form 3/4/5 filings on file. - **`total_transactions` (required)** `integer` — Total nonderivative transactions on file. - **`rpt_owner_name`** `object` — Modal insider name across the lifetime. **Example:** ```json { "rpt_owner_cik": "", "rpt_owner_name": "", "total_filings": 1, "total_transactions": 1, "issuers": [ { "issuer_cik": "", "issuer_name": "", "issuer_trading_symbol": "", "is_director": true, "is_officer": true, "is_ten_percent_owner": true, "filing_count": 1, "transaction_count": 1, "buys_dollars": "", "sells_dollars": "", "first_transaction_date": "", "last_transaction_date": "" } ] } ``` ##### Status: 401 Authentication failed - missing or invalid API key ###### Content-Type: application/json - **`message`** `string` **Example:** ```json { "message": "Missing API key in request" } ``` ##### Status: 404 Resource not found ###### Content-Type: application/json - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } ``` ##### Status: 422 Request validation failed - invalid or missing parameters ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 429 Rate limit exceeded for your tier ###### Content-Type: application/json - **`message`** `string` **Example:** ```json { "message": "" } ``` ##### Status: 500 Unhandled server error — file an issue with the request\_id from the error envelope. ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 502 Upstream dependency failed — gateway, key store, or downstream service unavailable. ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 503 Database query error or timeout — retry with backoff ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ### Group-by rollup of insider transactions - **Method:** `GET` - **Path:** `/api/v1/insiders/transactions/aggregate` - **Tags:** Insiders Aggregate Form 4 nonderivative transactions over a window, grouped by date / week / month / insider / issuer. Each bucket carries buys\_dollars, sells\_dollars, counts, and the buy/sell ratio. **Examples:** - Daily insider flow last 90 days: `?groupby=date` - Tech-sector (SIC 7372) weekly buy/sell: `?groupby=week&sic=7372` - AAPL by-insider rollup: `?groupby=insider&ticker=AAPL` #### Responses ##### Status: 200 Successful Response ###### Content-Type: application/json - **`data` (required)** `array` — Per-bucket aggregates sorted by \`group\_key\`. **Items:** - **`buys_count` (required)** `integer` — Buy transactions in this bucket. - **`buys_dollars` (required)** `string` — Sum of acquired-share value (USD). - **`group_key` (required)** `string` — Bucket key — for \`groupby=date|week|month\` this is an ISO date (period start); for \`insider\` it's the rpt\_owner\_cik; for \`issuer\` it's the issuer\_cik. - **`sells_count` (required)** `integer` — Sell transactions in this bucket. - **`sells_dollars` (required)** `string` — Sum of disposed-share value (USD). - **`bucket_start`** `object` — Start date of the bucket when grouping by date/week/month. - **`buy_sell_ratio`** `object` — buys\_dollars / (buys\_dollars + sells\_dollars), in \[0, 1]; null when both are zero. - **`group_label`** `object` — Human-readable label (e.g., insider name, issuer name). - **`groupby` (required)** `string`, possible values: `"date", "week", "month", "insider", "issuer"` — Group key applied to the rollup. - **`since` (required)** `string`, format: `date` — Window start applied to transaction\_date. - **`until` (required)** `string`, format: `date` — Window end applied to transaction\_date. **Example:** ```json { "groupby": "date", "since": "", "until": "", "data": [ { "group_key": "", "group_label": "", "bucket_start": "", "buys_dollars": "", "sells_dollars": "", "buys_count": 1, "sells_count": 1, "buy_sell_ratio": 1 } ] } ``` ##### Status: 401 Authentication failed - missing or invalid API key ###### Content-Type: application/json - **`message`** `string` **Example:** ```json { "message": "Missing API key in request" } ``` ##### Status: 422 Request validation failed - invalid or missing parameters ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 429 Rate limit exceeded for your tier ###### Content-Type: application/json - **`message`** `string` **Example:** ```json { "message": "" } ``` ##### Status: 500 Unhandled server error — file an issue with the request\_id from the error envelope. ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 502 Upstream dependency failed — gateway, key store, or downstream service unavailable. ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 503 Database query error or timeout — retry with backoff ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ### Insider buy/sell directional aggregate - **Method:** `GET` - **Path:** `/api/v1/insiders/buy-sell-ratio` - **Tags:** Insiders Returns the canonical insider sentiment ratio over a rolling window: buys\_dollars / (buys\_dollars + sells\_dollars). Defaults to the last 90 days; filter by issuer (cik or ticker) or by SIC for sector mood. **Examples:** - AAPL last 90 days: `?ticker=AAPL` - AAPL last 30 days: `?ticker=AAPL&window_days=30` - Tech-sector (SIC 7372) buy-sell ratio: `?sic=7372` #### Responses ##### Status: 200 Successful Response ###### Content-Type: application/json - **`buys_count` (required)** `integer` — Buy transaction count in the window. - **`buys_dollars` (required)** `string` — Sum of acquired-share value (USD). - **`sells_count` (required)** `integer` — Sell transaction count in the window. - **`sells_dollars` (required)** `string` — Sum of disposed-share value (USD). - **`since` (required)** `string`, format: `date` — Window start applied to transaction\_date. - **`until` (required)** `string`, format: `date` — Window end applied to transaction\_date. - **`buy_sell_ratio`** `object` — buys\_dollars / (buys\_dollars + sells\_dollars), in \[0, 1]. Null when both totals are zero. - **`cik`** `object` — Issuer CIK queried (canonical short form), when supplied. - **`sic`** `object` — Filer SIC filter applied, when supplied. - **`ticker`** `object` — Issuer ticker queried, when supplied. **Example:** ```json { "cik": "", "ticker": "", "sic": "", "since": "", "until": "", "buys_dollars": "", "sells_dollars": "", "buys_count": 1, "sells_count": 1, "buy_sell_ratio": 1 } ``` ##### Status: 401 Authentication failed - missing or invalid API key ###### Content-Type: application/json - **`message`** `string` **Example:** ```json { "message": "Missing API key in request" } ``` ##### Status: 422 Request validation failed - invalid or missing parameters ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 429 Rate limit exceeded for your tier ###### Content-Type: application/json - **`message`** `string` **Example:** ```json { "message": "" } ``` ##### Status: 500 Unhandled server error — file an issue with the request\_id from the error envelope. ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 502 Upstream dependency failed — gateway, key store, or downstream service unavailable. ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 503 Database query error or timeout — retry with backoff ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ### Get a Form 3/4/5 insider filing - **Method:** `GET` - **Path:** `/api/v1/insiders/{filing_id}` - **Tags:** Insiders Returns the parent filing plus reporting\_owners, nonderiv/deriv holdings, and nonderiv/deriv transactions in a single response. Each child set is small per filing (max \~30). #### Responses ##### Status: 200 Successful Response ###### Content-Type: application/json - **`accession_num` (required)** `object` — EDGAR accession number derived from filing\_id (e.g., '0000320193-24-000123') - **`cik` (required)** `string` — Filer (insider) SEC Central Index Key - **`filing_id` (required)** `string` — Unique filing identifier - **`form_type` (required)** `string` — SEC form type ('3', '3/A', '4', '4/A', '5', '5/A') - **`rpt_owner_cik` (required)** `string` — Alias of \`cik\` — the reporting owner's CIK. Matches the \`{rpt\_owner\_cik}\` path parameter on \`/insiders/owners/...\` so callers can pass it through without remapping. - **`source_url` (required)** `object` — Canonical SEC EDGAR Archives URL pointing at the filing's index page - **`accepted_time`** `object` — When the SEC accepted the filing - **`aff10b5_one`** `object` — True if any reported transaction was made under a Rule 10b5-1 trading plan - **`deriv_holdings`** `array` — All derivative holding rows for this filing **Items:** - **`record_index` (required)** `integer` — Per-filing 0-based ordinal of this derivative-holding row - **`conversion_or_exercise_price`** `object` — Strike / conversion price per share - **`direct_or_indirect_ownership`** `object` — 'D' = direct ownership, 'I' = indirect - **`exercise_date`** `object` — Earliest date the derivative becomes exercisable - **`expiration_date`** `object` — Date the derivative expires - **`nature_of_ownership`** `object` — Free-text describing indirect ownership - **`security_title`** `object` — Derivative title (e.g., 'Stock Option (Right to Buy)', 'RSU') - **`shares_owned_following_transaction`** `object` — Derivative-instrument count owned after the most recent transaction - **`underlying_security_shares`** `object` — Number of underlying shares the derivative covers - **`underlying_security_title`** `object` — Underlying security title (typically 'Common Stock') - **`underlying_security_value`** `object` — USD value of the underlying shares - **`value_owned_following_transaction`** `object` — USD value of derivatives owned after the most recent transaction - **`deriv_transactions`** `array` — All derivative transaction rows for this filing **Items:** - **`record_index` (required)** `integer` — Per-filing 0-based ordinal of this derivative-transaction row - **`conversion_or_exercise_price`** `object` — Strike / conversion price per share - **`direct_or_indirect_ownership`** `object` — 'D' = direct ownership, 'I' = indirect - **`exercise_date`** `object` — Earliest date the derivative becomes exercisable - **`expiration_date`** `object` — Date the derivative expires - **`security_title`** `object` — Derivative title - **`shares_owned_following_transaction`** `object` — Total derivative instruments owned after this transaction - **`transaction_acquired_disposed_code`** `object` — 'A' = acquired, 'D' = disposed - **`transaction_code`** `object` — Single-letter transaction code (see NonderivTransactionResponse) - **`transaction_date`** `object` — Date the transaction occurred - **`transaction_price_per_share`** `object` — Price per derivative instrument - **`transaction_shares`** `object` — Number of derivative instruments involved - **`transaction_total_value`** `object` — Total USD value of the transaction - **`underlying_security_shares`** `object` — Number of underlying shares the derivative covers - **`underlying_security_title`** `object` — Underlying security title (typically 'Common Stock') - **`underlying_security_value`** `object` — USD value of the underlying shares - **`document_type`** `object` — EDGAR document type label - **`filer_name`** `object` — Filer (insider) name - **`footnotes`** `object` — Footnote payload (XML-derived JSON of footnote text + targets) - **`form3_holdings_reported`** `object` — True if Form 3 initial-holdings table is reported - **`form4_transactions_reported`** `object` — True if Form 4 transactions are reported - **`is_amendment`** `object` — True if this filing is an amendment ('/A' suffix) - **`is_valid`** `object` — Whether the filing passed validation - **`issuer_cik`** `object` — Issuer (company) CIK — the company whose securities are being reported - **`issuer_name`** `object` — Issuer (company) legal name - **`issuer_trading_symbol`** `object` — Issuer ticker symbol - **`no_securities_owned`** `object` — True if filer reports no securities owned (typical Form 3) - **`nonderiv_holdings`** `array` — All non-derivative holding rows for this filing **Items:** - **`record_index` (required)** `integer` — Per-filing 0-based ordinal of this holding row - **`direct_or_indirect_ownership`** `object` — 'D' = direct ownership, 'I' = indirect (e.g., via trust or family member) - **`nature_of_ownership`** `object` — Free-text describing indirect ownership (e.g., 'By spouse', 'By trust') - **`security_title`** `object` — Security name (e.g., 'Common Stock', 'Class A Common') - **`shares_owned_following_transaction`** `object` — Total shares beneficially owned after the most recent transaction - **`value_owned_following_transaction`** `object` — Total USD value beneficially owned after the most recent transaction - **`nonderiv_transactions`** `array` — All non-derivative transaction rows for this filing **Items:** - **`record_index` (required)** `integer` — Per-filing 0-based ordinal of this transaction row - **`direct_or_indirect_ownership`** `object` — 'D' = direct ownership, 'I' = indirect - **`security_title`** `object` — Security name (e.g., 'Common Stock') - **`shares_owned_following_transaction`** `object` — Total shares owned after this transaction settles - **`transaction_acquired_disposed_code`** `object` — 'A' = shares acquired, 'D' = shares disposed - **`transaction_code`** `object` — Single-letter transaction code (e.g., P=open-market purchase, S=open-market sale, A=grant, M=option exercise, F=tax-withholding) - **`transaction_date`** `object` — Date the transaction occurred - **`transaction_price_per_share`** `object` — Price per share; 0 for grants, gifts, and other no-cost transactions - **`transaction_shares`** `object` — Number of shares involved in the transaction - **`not_subject_to_section16`** `object` — True if filer claims exemption from Section 16 reporting - **`period_of_report`** `object` — Reporting period end date - **`remarks`** `object` — Free-text remarks attached to the filing - **`reporting_owners`** `array` — All reporting-owner rows for this filing **Items:** - **`record_index` (required)** `integer` — Per-filing 0-based ordinal of this owner row - **`is_director`** `object` — True if reporting owner is a director of the issuer - **`is_officer`** `object` — True if reporting owner is an officer of the issuer - **`is_other`** `object` — True if reporting owner falls into none of the above categories — see \`other\_text\` - **`is_ten_percent_owner`** `object` — True if reporting owner holds 10%+ of the issuer's stock - **`officer_title`** `object` — Officer title (e.g., 'Chief Executive Officer'); blank if not an officer - **`other_text`** `object` — Free-text description when \`is\_other\` is True - **`rpt_owner_cik`** `object` — Reporting owner (insider) SEC CIK - **`rpt_owner_name`** `object` — Reporting owner (insider) legal name - **`schema_version`** `object` — EDGAR XML schema version this filing was produced under - **`signatures`** `object` — Signatures payload (signing party + date) **Example:** ```json { "filing_id": "", "cik": "", "form_type": "", "is_amendment": true, "period_of_report": "", "accepted_time": "", "is_valid": true, "filer_name": "", "issuer_cik": "", "issuer_name": "", "issuer_trading_symbol": "", "document_type": "", "schema_version": "", "not_subject_to_section16": true, "form3_holdings_reported": true, "form4_transactions_reported": true, "no_securities_owned": true, "aff10b5_one": true, "remarks": "", "footnotes": null, "signatures": null, "reporting_owners": [ { "record_index": 1, "rpt_owner_cik": "", "rpt_owner_name": "", "officer_title": "", "is_director": true, "is_officer": true, "is_ten_percent_owner": true, "is_other": true, "other_text": "" } ], "nonderiv_holdings": [ { "record_index": 1, "security_title": "", "shares_owned_following_transaction": "", "value_owned_following_transaction": "", "direct_or_indirect_ownership": "", "nature_of_ownership": "" } ], "nonderiv_transactions": [ { "record_index": 1, "security_title": "", "transaction_date": "", "transaction_code": "", "transaction_acquired_disposed_code": "", "transaction_shares": "", "transaction_price_per_share": "", "shares_owned_following_transaction": "", "direct_or_indirect_ownership": "" } ], "deriv_holdings": [ { "record_index": 1, "security_title": "", "conversion_or_exercise_price": "", "exercise_date": "", "expiration_date": "", "underlying_security_title": "", "underlying_security_shares": "", "underlying_security_value": "", "shares_owned_following_transaction": "", "value_owned_following_transaction": "", "direct_or_indirect_ownership": "", "nature_of_ownership": "" } ], "deriv_transactions": [ { "record_index": 1, "security_title": "", "conversion_or_exercise_price": "", "transaction_date": "", "transaction_code": "", "transaction_acquired_disposed_code": "", "transaction_shares": "", "transaction_total_value": "", "transaction_price_per_share": "", "exercise_date": "", "expiration_date": "", "underlying_security_title": "", "underlying_security_shares": "", "underlying_security_value": "", "shares_owned_following_transaction": "", "direct_or_indirect_ownership": "" } ], "accession_num": "", "source_url": "", "rpt_owner_cik": "" } ``` ##### Status: 401 Authentication failed - missing or invalid API key ###### Content-Type: application/json - **`message`** `string` **Example:** ```json { "message": "Missing API key in request" } ``` ##### Status: 404 Resource not found ###### Content-Type: application/json - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } ``` ##### Status: 422 Request validation failed - invalid or missing parameters ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 429 Rate limit exceeded for your tier ###### Content-Type: application/json - **`message`** `string` **Example:** ```json { "message": "" } ``` ##### Status: 500 Unhandled server error — file an issue with the request\_id from the error envelope. ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 502 Upstream dependency failed — gateway, key store, or downstream service unavailable. ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 503 Database query error or timeout — retry with backoff ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ### List Form 13F institutional holdings filings - **Method:** `GET` - **Path:** `/api/v1/institutional-holdings` - **Tags:** Institutional Holdings List Form 13F filings (institutional investment manager quarterly holdings). Filters by manager (`cik` or `filing_manager_cik`), ticker (filer\_tickers JSONB), report\_type (HR/NT), period dates. #### Responses ##### Status: 200 Successful Response ###### Content-Type: application/json - **`data` (required)** `array` — Page of 13F filing rows **Items:** - **`accession_num` (required)** `object` — EDGAR accession number derived from filing\_id (e.g., '0000320193-24-000123') - **`cik` (required)** `string` — Filer SEC Central Index Key - **`filing_id` (required)** `string` — Unique filing identifier - **`form_type` (required)** `string` — SEC form type (e.g., '13F-HR', '13F-NT', '13F-HR/A') - **`source_url` (required)** `object` — Canonical SEC EDGAR Archives URL pointing at the filing's index page - **`accepted_time`** `object` — When the SEC accepted the filing - **`amendment_no`** `object` — Amendment number (1, 2, ...) for amendment filings - **`filer_name`** `object` — Filer entity name - **`filer_tickers`** `object` — Ticker symbols associated with the filer - **`filing_manager_cik`** `object` — Filing manager CIK (institutional investment manager) - **`filing_manager_name`** `object` — Filing manager legal name - **`is_amendment`** `object` — True if this filing is an amendment - **`is_valid`** `object` — Whether the filing passed validation - **`other_included_managers_count`** `object` — Count of other managers also included on this filing - **`period_of_report`** `object` — Reporting period end date (calendar quarter end) - **`report_type`** `object` — 13F report type code: 'HR', 'NT', or 'CR' (see query-param doc) - **`submission_type`** `object` — EDGAR submission type - **`table_entry_total`** `object` — Total number of holdings rows reported on this filing - **`table_value_total`** `object` — Total reported portfolio value (in thousands of USD per Form 13F convention) - **`page_size` (required)** `integer` — Results per page - **`page`** `integer`, default: `1` — Current page number (1-indexed) - **`total`** `integer`, default: `0` — Total count of matching rows - **`total_pages`** `integer`, default: `1` — Total number of pages **Example:** ```json { "total": 0, "page": 1, "page_size": 1, "total_pages": 1, "data": [ { "filing_id": "", "cik": "", "form_type": "", "period_of_report": "", "accepted_time": "", "is_valid": true, "filer_name": "", "filer_tickers": [ "" ], "filing_manager_cik": "", "filing_manager_name": "", "submission_type": "", "report_type": "", "is_amendment": true, "amendment_no": 1, "other_included_managers_count": 1, "table_entry_total": 1, "table_value_total": "", "accession_num": "", "source_url": "" } ] } ``` ##### Status: 401 Authentication failed - missing or invalid API key ###### Content-Type: application/json - **`message`** `string` **Example:** ```json { "message": "Missing API key in request" } ``` ##### Status: 422 Request validation failed - invalid or missing parameters ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 429 Rate limit exceeded for your tier ###### Content-Type: application/json - **`message`** `string` **Example:** ```json { "message": "" } ``` ##### Status: 500 Unhandled server error — file an issue with the request\_id from the error envelope. ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 502 Upstream dependency failed — gateway, key store, or downstream service unavailable. ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 503 Database query error or timeout — retry with backoff ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ### Cross-filing 13F holdings stream - **Method:** `GET` - **Path:** `/api/v1/institutional-holdings/holdings` - **Tags:** Institutional Holdings Stream 13F holdings across many filings — supports "who holds AAPL?" by `cusip`, "Berkshire's holdings over time" by `filing_manager_cik`, and "this filing's holdings" by `filing_id`. **Required:** at least one of `cusip`, `name_of_issuer`, `filing_manager_cik`, `filing_id`. Returns `400 MISSING_PARAMETER` otherwise. #### Responses ##### Status: 200 Successful Response ###### Content-Type: application/json - **`data` (required)** `array` — Page of 13F holding rows **Items:** - **`filing_id` (required)** `string` — Filing this holding belongs to - **`record_index` (required)** `integer` — Per-filing 0-based ordinal of this holding row - **`cusip`** `object` — 9-character CUSIP of the held security - **`figi`** `object` — OpenFIGI Financial Instrument Global Identifier (12 chars) - **`filing_manager_cik`** `object` — Filing manager CIK - **`filing_manager_name`** `object` — Filing manager legal name - **`investment_discretion`** `object` — Investment discretion: 'SOLE', 'DFND' (defined), 'OTR' (other shared) - **`name_of_issuer`** `object` — Issuer name of the held security - **`period_of_report`** `object` — Reporting period end date (calendar quarter end) - **`ssh_prnamt`** `object` — Number of shares or principal amount held - **`ssh_prnamt_type`** `object` — Type of \`ssh\_prnamt\` units: 'SH' = shares, 'PRN' = principal amount (debt) - **`title_of_class`** `object` — Title of class (e.g., 'COM', 'CL A', 'PFD CL B') - **`value`** `object` — Position value in thousands of USD (per Form 13F reporting convention) - **`voting_none`** `object` — Shares with no voting authority - **`voting_shared`** `object` — Shares with shared voting authority - **`voting_sole`** `object` — Shares with sole voting authority - **`page_size` (required)** `integer` — Results per page - **`page`** `integer`, default: `1` — Current page number (1-indexed) - **`total`** `integer`, default: `0` — Total count of matching rows - **`total_pages`** `integer`, default: `1` — Total number of pages **Example:** ```json { "total": 0, "page": 1, "page_size": 1, "total_pages": 1, "data": [ { "cusip": "037833100", "figi": "BBG000B9XRY4", "filing_id": "0001067983_0001067983-24-000012", "filing_manager_cik": "0001067983", "filing_manager_name": "BERKSHIRE HATHAWAY INC", "investment_discretion": "DFND", "name_of_issuer": "APPLE INC", "period_of_report": "2024-03-31", "record_index": 42, "ssh_prnamt": "789368450", "ssh_prnamt_type": "SH", "title_of_class": "COM", "value": "135360500", "voting_none": "0", "voting_shared": "0", "voting_sole": "789368450" } ] } ``` ##### Status: 400 Request rejected — usually a missing required parameter or an at-least-one-of constraint not satisfied. ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 401 Authentication failed - missing or invalid API key ###### Content-Type: application/json - **`message`** `string` **Example:** ```json { "message": "Missing API key in request" } ``` ##### Status: 422 Request validation failed - invalid or missing parameters ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 429 Rate limit exceeded for your tier ###### Content-Type: application/json - **`message`** `string` **Example:** ```json { "message": "" } ``` ##### Status: 500 Unhandled server error — file an issue with the request\_id from the error envelope. ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 502 Upstream dependency failed — gateway, key store, or downstream service unavailable. ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 503 Database query error or timeout — retry with backoff ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ### List distinct 13F filing managers - **Method:** `GET` - **Path:** `/api/v1/institutional-holdings/managers` - **Tags:** Institutional Holdings Distinct filing-manager CIKs and names with filing counts. #### Responses ##### Status: 200 Successful Response ###### Content-Type: application/json - **`data` (required)** `array` — Page of distinct filing managers **Items:** - **`filing_count` (required)** `integer` — Total 13F filings this manager has submitted - **`filing_manager_cik`** `object` — Filing manager SEC CIK - **`filing_manager_name`** `object` — Filing manager legal name - **`page_size` (required)** `integer` — Results per page - **`page`** `integer`, default: `1` — Current page number (1-indexed) - **`total`** `integer`, default: `0` — Total count of matching rows - **`total_pages`** `integer`, default: `1` — Total number of pages **Example:** ```json { "total": 0, "page": 1, "page_size": 1, "total_pages": 1, "data": [ { "filing_manager_cik": "", "filing_manager_name": "", "filing_count": 1 } ] } ``` ##### Status: 401 Authentication failed - missing or invalid API key ###### Content-Type: application/json - **`message`** `string` **Example:** ```json { "message": "Missing API key in request" } ``` ##### Status: 422 Request validation failed - invalid or missing parameters ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 429 Rate limit exceeded for your tier ###### Content-Type: application/json - **`message`** `string` **Example:** ```json { "message": "" } ``` ##### Status: 500 Unhandled server error — file an issue with the request\_id from the error envelope. ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 502 Upstream dependency failed — gateway, key store, or downstream service unavailable. ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 503 Database query error or timeout — retry with backoff ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ### Get a Form 13F institutional holdings filing - **Method:** `GET` - **Path:** `/api/v1/institutional-holdings/{filing_id}` - **Tags:** Institutional Holdings Returns the parent filing plus other\_managers. Holdings (which can hit 50k+ rows per filing) are NOT bundled — fetch them via `/api/v1/institutional-holdings/holdings?filing_id={filing_id}`. #### Responses ##### Status: 200 Successful Response ###### Content-Type: application/json - **`accession_num` (required)** `object` — EDGAR accession number derived from filing\_id (e.g., '0000320193-24-000123') - **`cik` (required)** `string` — Filer SEC Central Index Key - **`filing_id` (required)** `string` — Unique filing identifier - **`form_type` (required)** `string` — SEC form type (e.g., '13F-HR', '13F-NT', '13F-HR/A') - **`source_url` (required)** `object` — Canonical SEC EDGAR Archives URL pointing at the filing's index page - **`accepted_time`** `object` — When the SEC accepted the filing - **`additional_information`** `object` — Free-text additional information narrative from the filing - **`amendment_no`** `object` — Amendment number (1, 2, ...) for amendment filings - **`filer_name`** `object` — Filer entity name - **`filer_tickers`** `object` — Ticker symbols associated with the filer - **`filing_manager_cik`** `object` — Filing manager CIK (institutional investment manager) - **`filing_manager_city`** `object` — Filing manager city - **`filing_manager_name`** `object` — Filing manager legal name - **`filing_manager_state_or_country`** `object` — Filing manager state code or country code (US states or ISO country) - **`filing_manager_street1`** `object` — Filing manager street address - **`holdings_count`** `object` — Total holdings rows on this filing (mirrors table\_entry\_total). Fetch the rows via /institutional-holdings/holdings?filing\_id={filing\_id}. - **`holdings_url`** `object` — Convenience link to fetch the holdings rows for this filing - **`is_amendment`** `object` — True if this filing is an amendment - **`is_confidential_omitted`** `object` — True if confidential treatment caused holdings to be omitted - **`is_valid`** `object` — Whether the filing passed validation - **`other_included_managers_count`** `object` — Count of other managers also included on this filing - **`other_managers`** `array` — Other managers also included on this filing **Items:** - **`record_index` (required)** `integer` — Per-filing 0-based ordinal of this manager row - **`crd_number`** `object` — FINRA CRD number for the other manager - **`form13_f_file_number`** `object` — Form 13F file number (e.g., '028-12345') - **`other_manager_cik`** `object` — Other manager SEC CIK - **`other_manager_name`** `object` — Other manager legal name - **`sec_file_number`** `object` — SEC file number for the other manager (e.g., '801-12345' for advisers) - **`period_of_report`** `object` — Reporting period end date (calendar quarter end) - **`report_calendar_or_quarter`** `object` — Reported calendar quarter / period (e.g., '03-31-2024') - **`report_type`** `object` — 13F report type code: 'HR', 'NT', or 'CR' (see query-param doc) - **`submission_type`** `object` — EDGAR submission type - **`table_entry_total`** `object` — Total number of holdings rows reported on this filing - **`table_value_total`** `object` — Total reported portfolio value (in thousands of USD per Form 13F convention) **Example:** ```json { "filing_id": "", "cik": "", "form_type": "", "period_of_report": "", "accepted_time": "", "is_valid": true, "filer_name": "", "filer_tickers": [ "" ], "filing_manager_cik": "", "filing_manager_name": "", "submission_type": "", "report_type": "", "is_amendment": true, "amendment_no": 1, "other_included_managers_count": 1, "table_entry_total": 1, "table_value_total": "", "filing_manager_street1": "", "filing_manager_city": "", "filing_manager_state_or_country": "", "report_calendar_or_quarter": "", "additional_information": "", "is_confidential_omitted": true, "other_managers": [ { "record_index": 1, "other_manager_cik": "", "other_manager_name": "", "form13_f_file_number": "", "crd_number": "", "sec_file_number": "" } ], "holdings_count": 1, "holdings_url": "", "accession_num": "", "source_url": "" } ``` ##### Status: 401 Authentication failed - missing or invalid API key ###### Content-Type: application/json - **`message`** `string` **Example:** ```json { "message": "Missing API key in request" } ``` ##### Status: 404 Resource not found ###### Content-Type: application/json - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } ``` ##### Status: 422 Request validation failed - invalid or missing parameters ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 429 Rate limit exceeded for your tier ###### Content-Type: application/json - **`message`** `string` **Example:** ```json { "message": "" } ``` ##### Status: 500 Unhandled server error — file an issue with the request\_id from the error envelope. ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 502 Upstream dependency failed — gateway, key store, or downstream service unavailable. ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 503 Database query error or timeout — retry with backoff ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ### List Form D exempt offering filings - **Method:** `GET` - **Path:** `/api/v1/private-offerings` - **Tags:** Private Offerings List Form D filings (private placements / Reg D exempt offerings). **Examples:** - All offerings by a company: `?cik=1234567` - Hedge funds only: `?investment_fund_type=Hedge Fund` - Big offerings: `?min_offering_amount=10000000` - Recent: `?accepted_start=2024-01-01` #### Responses ##### Status: 200 Successful Response ###### Content-Type: application/json - **`data` (required)** `array` — Page of Form D filing rows **Items:** - **`accession_num` (required)** `object` — EDGAR accession number derived from filing\_id (e.g., '0000320193-24-000123') - **`cik` (required)** `string` — Filer SEC Central Index Key - **`filing_id` (required)** `string` — Unique filing identifier - **`form_type` (required)** `string` — SEC form type (e.g., '4', '13F-HR', 'D') - **`source_url` (required)** `object` — Canonical SEC EDGAR Archives URL pointing at the filing's index page - **`accepted_time`** `object` — When SEC accepted the filing - **`filer_name`** `object` — Filer entity name - **`filer_tickers`** `object` — Ticker symbols associated with the filer - **`industry_group_type`** `object` — Form D industry group code (see query-param doc) - **`investment_fund_type`** `object` — Investment-fund type for fund issuers (see query-param doc) - **`is_40_act`** `object` — True if the issuer is a registered investment company under the 1940 Act - **`is_amendment`** `object` — True if this filing is an amendment - **`is_valid`** `object` — Whether the filing passed validation - **`minimum_investment_accepted`** `object` — Minimum investment accepted from any one investor (USD) - **`period_of_report`** `object` — Reporting period end date - **`submission_type`** `object` — EDGAR submission type - **`total_amount_sold`** `object` — Total amount sold to date (USD) - **`total_offering_amount`** `object` — Total offering amount (USD) - **`total_remaining`** `object` — Total amount remaining to be sold (USD; offering minus amount sold) - **`page_size` (required)** `integer` — Results per page - **`page`** `integer`, default: `1` — Current page number (1-indexed) - **`total`** `integer`, default: `0` — Total count of matching rows - **`total_pages`** `integer`, default: `1` — Total number of pages **Example:** ```json { "total": 0, "page": 1, "page_size": 1, "total_pages": 1, "data": [ { "filing_id": "", "cik": "", "form_type": "", "period_of_report": "", "accepted_time": "", "is_valid": true, "filer_name": "", "filer_tickers": [ "" ], "is_amendment": true, "submission_type": "", "industry_group_type": "", "investment_fund_type": "", "is_40_act": true, "total_offering_amount": "", "total_amount_sold": "", "total_remaining": "", "minimum_investment_accepted": "", "accession_num": "", "source_url": "" } ] } ``` ##### Status: 401 Authentication failed - missing or invalid API key ###### Content-Type: application/json - **`message`** `string` **Example:** ```json { "message": "Missing API key in request" } ``` ##### Status: 422 Request validation failed - invalid or missing parameters ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 429 Rate limit exceeded for your tier ###### Content-Type: application/json - **`message`** `string` **Example:** ```json { "message": "" } ``` ##### Status: 500 Unhandled server error — file an issue with the request\_id from the error envelope. ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 502 Upstream dependency failed — gateway, key store, or downstream service unavailable. ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 503 Database query error or timeout — retry with backoff ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ### List filers with Form D offering data - **Method:** `GET` - **Path:** `/api/v1/private-offerings/entities` - **Tags:** Private Offerings Discovery endpoint — list distinct filers with Form D filings on file, with summary statistics for each. Returns one row per filer `cik` with: - Filer identifiers (CIK, modal name, ticker symbols when present) - `filing_count` — total Form D filings on file - `period_min` / `period_max` — earliest and latest period\_of\_report - `total_offering_amount_sum` — SUM of `total_offering_amount` across the filer's filings (USD; null when no filing reports an amount) **Examples:** - All filers: `/private-offerings/entities` - Search by name: `/private-offerings/entities?search=acme` - Largest issuers first: `/private-offerings/entities?sort=filing_count&order=desc` **See also:** `/api/v1/entities/{cik}` for the registry-level profile of any filer returned here. #### Responses ##### Status: 200 Successful Response ###### Content-Type: application/json - **`data` (required)** `array` — Page of filers with Form D data on file. **Items:** - **`cik` (required)** `string` — Required. Filer SEC Central Index Key (canonical short form, no leading zeros). - **`filing_count` (required)** `integer` — Required. Total Form D filings on file for this filer. - **`company_name`** `object` — Optional. Modal filer name across the filer's Form D filings. - **`period_max`** `object` — Optional. Latest period\_of\_report observed for this filer. - **`period_min`** `object` — Optional. Earliest period\_of\_report observed for this filer. - **`tickers`** `object` — Optional. Filer ticker symbols sampled from one filing's \`filer\_tickers\`. - **`total_offering_amount_sum`** `object` — Optional. SUM of \`total\_offering\_amount\` across this filer's Form D filings (USD; null when no filing reports an amount). - **`page_size` (required)** `integer` — Results per page - **`page`** `integer`, default: `1` — Current page number (1-indexed) - **`total`** `integer`, default: `0` — Total count of matching rows - **`total_pages`** `integer`, default: `1` — Total number of pages **Example:** ```json { "total": 0, "page": 1, "page_size": 1, "total_pages": 1, "data": [ { "cik": "1234567", "company_name": "Acme Capital Partners LP", "filing_count": 12, "period_max": "2024-03-31", "period_min": "2019-06-30", "total_offering_amount_sum": "525000000" } ] } ``` ##### Status: 401 Authentication failed - missing or invalid API key ###### Content-Type: application/json - **`message`** `string` **Example:** ```json { "message": "Missing API key in request" } ``` ##### Status: 422 Request validation failed - invalid or missing parameters ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 429 Rate limit exceeded for your tier ###### Content-Type: application/json - **`message`** `string` **Example:** ```json { "message": "" } ``` ##### Status: 500 Unhandled server error — file an issue with the request\_id from the error envelope. ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 502 Upstream dependency failed — gateway, key store, or downstream service unavailable. ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 503 Database query error or timeout — retry with backoff ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ### Form D filings bucketed by Reg D exemption (506(b) / 506(c) / 504 / other) - **Method:** `GET` - **Path:** `/api/v1/private-offerings/506b-vs-506c` - **Tags:** Private Offerings Group Form D filings by the Reg D exemption claimed in `federal_exemptions_exclusions`. The 506(b) vs 506(c) split tells you how much of the private-offering universe is using general-solicitation vs traditional accredited-investor sales — the field is on every Form D, but no rollup surface exposes it today. **Examples:** - All-time: `/private-offerings/506b-vs-506c` - Last 12 months: `/private-offerings/506b-vs-506c?since=2025-04-30` #### Responses ##### Status: 200 Successful Response ###### Content-Type: application/json - **`data` (required)** `array` — Buckets ranked by \`total\_offering\_amount\_sum\` descending. **Items:** - **`distinct_filer_count` (required)** `integer` — Distinct filer CIKs in this bucket. - **`exemption_label` (required)** `string` — Bucket label: '506b' (Rule 506(b)), '506c' (Rule 506(c)), '504' (Rule 504), 'other', or 'unspecified' (no Reg D exemption claimed in \`federal\_exemptions\_exclusions\`). - **`filing_count` (required)** `integer` — Form D filings in this bucket. - **`total_amount_sold_sum`** `object` — Sum of \`total\_amount\_sold\` (USD) for the bucket. - **`total_offering_amount_sum`** `object` — Sum of \`total\_offering\_amount\` (USD) for the bucket. - **`since`** `object` — Window start applied to filings.accepted\_time, when supplied. - **`until`** `object` — Window end applied to filings.accepted\_time, when supplied. **Example:** ```json { "since": "", "until": "", "data": [ { "exemption_label": "", "filing_count": 1, "distinct_filer_count": 1, "total_offering_amount_sum": "", "total_amount_sold_sum": "" } ] } ``` ##### Status: 401 Authentication failed - missing or invalid API key ###### Content-Type: application/json - **`message`** `string` **Example:** ```json { "message": "Missing API key in request" } ``` ##### Status: 422 Request validation failed - invalid or missing parameters ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 429 Rate limit exceeded for your tier ###### Content-Type: application/json - **`message`** `string` **Example:** ```json { "message": "" } ``` ##### Status: 500 Unhandled server error — file an issue with the request\_id from the error envelope. ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 502 Upstream dependency failed — gateway, key store, or downstream service unavailable. ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 503 Database query error or timeout — retry with backoff ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ### Get a Form D exempt offering filing - **Method:** `GET` - **Path:** `/api/v1/private-offerings/{filing_id}` - **Tags:** Private Offerings #### Responses ##### Status: 200 Successful Response ###### Content-Type: application/json - **`accession_num` (required)** `object` — EDGAR accession number derived from filing\_id (e.g., '0000320193-24-000123') - **`cik` (required)** `string` — Filer SEC Central Index Key - **`filing_id` (required)** `string` — Unique filing identifier - **`form_type` (required)** `string` — SEC form type (e.g., '4', '13F-HR', 'D') - **`source_url` (required)** `object` — Canonical SEC EDGAR Archives URL pointing at the filing's index page - **`accepted_time`** `object` — When SEC accepted the filing - **`federal_exemptions_exclusions`** `object` — List of Securities Act exemption/exclusion citations (e.g., \['Rule 506(b)', 'Section 4(a)(2)']) - **`filer_name`** `object` — Filer entity name - **`filer_tickers`** `object` — Ticker symbols associated with the filer - **`form_data`** `object` — Full Form D form\_data JSON (omit by passing include\_form\_data=false on the request) - **`industry_group_type`** `object` — Form D industry group code (see query-param doc) - **`investment_fund_type`** `object` — Investment-fund type for fund issuers (see query-param doc) - **`is_40_act`** `object` — True if the issuer is a registered investment company under the 1940 Act - **`is_amendment`** `object` — True if this filing is an amendment - **`is_valid`** `object` — Whether the filing passed validation - **`issuers`** `array` — All issuer rows on this filing **Items:** - **`record_index` (required)** `integer` — Per-filing 0-based ordinal of this issuer row - **`entity_name`** `object` — Issuer legal name - **`entity_type`** `object` — Entity type (e.g., 'Corporation', 'Limited Partnership', 'Limited Liability Company') - **`issuer_cik`** `object` — Issuer SEC CIK (where the issuer has one) - **`issuer_city`** `object` — Issuer city - **`issuer_phone`** `object` — Issuer contact phone number - **`issuer_state_or_country`** `object` — Issuer state code or country code - **`issuer_state_or_country_description`** `object` — Human-readable state / country name - **`issuer_street1`** `object` — Issuer street address line 1 - **`issuer_street2`** `object` — Issuer street address line 2 - **`issuer_zip_code`** `object` — Issuer postal code - **`jurisdiction_of_inc`** `object` — State or country of incorporation/organization (e.g., 'DELAWARE') - **`year_of_inc`** `object` — Year of incorporation/organization - **`minimum_investment_accepted`** `object` — Minimum investment accepted from any one investor (USD) - **`period_of_report`** `object` — Reporting period end date - **`related_persons`** `array` — All related-person rows on this filing (officers, directors, promoters) **Items:** - **`record_index` (required)** `integer` — Per-filing 0-based ordinal of this person row - **`address_city`** `object` — Person's city - **`address_state_or_country`** `object` — Person's state code or country code - **`address_state_or_country_description`** `object` — Human-readable state / country name - **`address_street1`** `object` — Person's street address line 1 - **`address_street2`** `object` — Person's street address line 2 - **`address_zip_code`** `object` — Person's postal code - **`first_name`** `object` — Given name - **`last_name`** `object` — Family name - **`middle_name`** `object` — Middle name - **`relationship_clarification`** `object` — Free-text clarification of the relationship (where 'Other' is selected) - **`relationships`** `object` — Relationship tags (e.g., \['Executive Officer', 'Director', 'Promoter']) - **`submission_type`** `object` — EDGAR submission type - **`total_amount_sold`** `object` — Total amount sold to date (USD) - **`total_offering_amount`** `object` — Total offering amount (USD) - **`total_remaining`** `object` — Total amount remaining to be sold (USD; offering minus amount sold) **Example:** ```json { "filing_id": "", "cik": "", "form_type": "", "period_of_report": "", "accepted_time": "", "is_valid": true, "filer_name": "", "filer_tickers": [ "" ], "is_amendment": true, "submission_type": "", "industry_group_type": "", "investment_fund_type": "", "is_40_act": true, "total_offering_amount": "", "total_amount_sold": "", "total_remaining": "", "minimum_investment_accepted": "", "federal_exemptions_exclusions": null, "form_data": null, "issuers": [ { "record_index": 1, "issuer_cik": "", "entity_name": "", "jurisdiction_of_inc": "", "entity_type": "", "year_of_inc": "", "issuer_phone": "", "issuer_street1": "", "issuer_street2": "", "issuer_city": "", "issuer_state_or_country": "", "issuer_state_or_country_description": "", "issuer_zip_code": "" } ], "related_persons": [ { "record_index": 1, "first_name": "", "middle_name": "", "last_name": "", "address_street1": "", "address_street2": "", "address_city": "", "address_state_or_country": "", "address_state_or_country_description": "", "address_zip_code": "", "relationships": null, "relationship_clarification": "" } ], "accession_num": "", "source_url": "" } ``` ##### Status: 401 Authentication failed - missing or invalid API key ###### Content-Type: application/json - **`message`** `string` **Example:** ```json { "message": "Missing API key in request" } ``` ##### Status: 404 Resource not found ###### Content-Type: application/json - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } ``` ##### Status: 422 Request validation failed - invalid or missing parameters ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 429 Rate limit exceeded for your tier ###### Content-Type: application/json - **`message`** `string` **Example:** ```json { "message": "" } ``` ##### Status: 500 Unhandled server error — file an issue with the request\_id from the error envelope. ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 502 Upstream dependency failed — gateway, key store, or downstream service unavailable. ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 503 Database query error or timeout — retry with backoff ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ### List Form N-PORT filings - **Method:** `GET` - **Path:** `/api/v1/fund-portfolios` - **Tags:** Fund Portfolios List Form N-PORT filings (registered investment company monthly portfolio reports). Filters by registrant\_cik, series, class, period. #### Responses ##### Status: 200 Successful Response ###### Content-Type: application/json - **`data` (required)** `array` — Page of N-PORT filing rows **Items:** - **`accession_num` (required)** `object` — EDGAR accession number derived from filing\_id (e.g., '0000320193-24-000123') - **`cik` (required)** `string` — Filer SEC Central Index Key - **`filing_id` (required)** `string` — Unique filing identifier - **`form_type` (required)** `string` — SEC form type (e.g., 'N-PORT', 'N-PORT/A') - **`source_url` (required)** `object` — Canonical SEC EDGAR Archives URL pointing at the filing's index page - **`accepted_time`** `object` — When the SEC accepted the filing - **`class_id`** `object` — SEC share class identifier (e.g., C000001234) - **`filer_name`** `object` — Filer entity name - **`filer_tickers`** `object` — Ticker symbols associated with the filer - **`is_confidential`** `object` — True if filing is confidential treatment - **`is_final_filing`** `object` — True if this is a final (de-registration) filing - **`is_valid`** `object` — Whether the filing passed validation - **`period_of_report`** `object` — Reporting period end date - **`registrant_cik`** `object` — Fund registrant CIK (the registered investment company) - **`registrant_lei`** `object` — Fund registrant Legal Entity Identifier (20-char LEI) - **`registrant_name`** `object` — Fund registrant legal name - **`report_period_end`** `object` — End date of the reported portfolio period - **`series_id`** `object` — SEC fund series identifier (e.g., S000001234) - **`series_name`** `object` — Fund series display name - **`submission_type`** `object` — N-PORT submission type (e.g., NPORT-P, NPORT-EX) - **`page_size` (required)** `integer` — Results per page - **`page`** `integer`, default: `1` — Current page number (1-indexed) - **`total`** `integer`, default: `0` — Total count of matching rows - **`total_pages`** `integer`, default: `1` — Total number of pages **Example:** ```json { "total": 0, "page": 1, "page_size": 1, "total_pages": 1, "data": [ { "filing_id": "", "cik": "", "form_type": "", "period_of_report": "", "accepted_time": "", "is_valid": true, "filer_name": "", "filer_tickers": [ "" ], "submission_type": "", "report_period_end": "", "is_confidential": true, "is_final_filing": true, "series_id": "", "class_id": "", "registrant_cik": "", "registrant_name": "", "registrant_lei": "", "series_name": "", "accession_num": "", "source_url": "" } ] } ``` ##### Status: 401 Authentication failed - missing or invalid API key ###### Content-Type: application/json - **`message`** `string` **Example:** ```json { "message": "Missing API key in request" } ``` ##### Status: 422 Request validation failed - invalid or missing parameters ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 429 Rate limit exceeded for your tier ###### Content-Type: application/json - **`message`** `string` **Example:** ```json { "message": "" } ``` ##### Status: 500 Unhandled server error — file an issue with the request\_id from the error envelope. ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 502 Upstream dependency failed — gateway, key store, or downstream service unavailable. ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 503 Database query error or timeout — retry with backoff ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ### Cross-filing N-PORT holdings stream - **Method:** `GET` - **Path:** `/api/v1/fund-portfolios/holdings` - **Tags:** Fund Portfolios Stream N-PORT holdings across many filings. Supports fund-overlap analysis by `cusip`/`isin`/`lei`, single-filing pull via `filing_id`, and time-series via `registrant_cik` + period range. **Required:** at least one of `cusip`, `isin`, `lei`, `name`, `registrant_cik`, `filing_id`. Returns `400 MISSING_PARAMETER` otherwise. #### Responses ##### Status: 200 Successful Response ###### Content-Type: application/json - **`data` (required)** `array` — Page of N-PORT holding rows **Items:** - **`filing_id` (required)** `string` — Filing this holding belongs to - **`record_index` (required)** `integer` — Per-filing 0-based ordinal of this holding row - **`asset_cat`** `object` — N-PORT asset category code (e.g., 'EC' equity, 'DBT' debt, 'DCO' commodity) - **`balance`** `object` — Position size in \`units\` (shares, principal amount, contracts) - **`cur_cd`** `object` — ISO 4217 currency code of the underlying security - **`cusip`** `object` — CUSIP (8-9 chars); '000000000' / 'N/A' indicate not assigned - **`fair_val_level`** `object` — Fair-value hierarchy level: 1 (quoted), 2 (observable), 3 (unobservable) - **`inv_country`** `object` — Issuer country (ISO 3166-1 alpha-2 code) - **`is_restricted_sec`** `object` — True if this is a restricted security (Rule 144A etc.) - **`isin`** `object` — International Securities Identification Number (12 chars) - **`issuer_cat`** `object` — N-PORT issuer category code (e.g., 'CORP' corporate, 'TREA' treasury) - **`lei`** `object` — Issuer LEI (20-char Legal Entity Identifier) - **`name`** `object` — Issuer name of the held security - **`other_id`** `object` — Alternate security identifier (when CUSIP/ISIN unavailable) - **`other_id_desc`** `object` — Description of the identifier in \`other\_id\` (e.g., 'INTERNAL', 'TICKER') - **`payoff_profile`** `object` — Payoff direction: 'Long' or 'Short' (derivatives may be either) - **`pct_val`** `object` — Position as a percent of the fund series' net assets - **`period_of_report`** `object` — Reporting period end date - **`registrant_cik`** `object` — Fund registrant CIK - **`registrant_name`** `object` — Fund registrant legal name - **`series_id`** `object` — SEC fund series identifier - **`series_name`** `object` — Fund series display name - **`title`** `object` — Security title / description (e.g., '5.50% Senior Notes due 2030') - **`units`** `object` — Unit type for \`balance\` (NS=number of shares, PA=principal amount, NC=number of contracts) - **`val_usd`** `object` — Position value in USD at period-end mark - **`page_size` (required)** `integer` — Results per page - **`page`** `integer`, default: `1` — Current page number (1-indexed) - **`total`** `integer`, default: `0` — Total count of matching rows - **`total_pages`** `integer`, default: `1` — Total number of pages **Example:** ```json { "total": 0, "page": 1, "page_size": 1, "total_pages": 1, "data": [ { "asset_cat": "EC", "balance": "129084215", "cur_cd": "USD", "cusip": "037833100", "fair_val_level": 1, "filing_id": "0000884394_0001752724-24-049321", "inv_country": "US", "is_restricted_sec": false, "isin": "US0378331005", "issuer_cat": "CORP", "lei": "HWUPKR0MPOU8FGXBT394", "name": "APPLE INC", "payoff_profile": "Long", "pct_val": "6.84", "period_of_report": "2024-03-31", "record_index": 12, "registrant_cik": "0000884394", "registrant_name": "VANGUARD INDEX FUNDS", "series_id": "S000001234", "series_name": "Vanguard 500 Index Fund", "title": "Common Stock", "units": "NS", "val_usd": "22117483560.50" } ] } ``` ##### Status: 400 Request rejected — usually a missing required parameter or an at-least-one-of constraint not satisfied. ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 401 Authentication failed - missing or invalid API key ###### Content-Type: application/json - **`message`** `string` **Example:** ```json { "message": "Missing API key in request" } ``` ##### Status: 422 Request validation failed - invalid or missing parameters ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 429 Rate limit exceeded for your tier ###### Content-Type: application/json - **`message`** `string` **Example:** ```json { "message": "" } ``` ##### Status: 500 Unhandled server error — file an issue with the request\_id from the error envelope. ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 502 Upstream dependency failed — gateway, key store, or downstream service unavailable. ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 503 Database query error or timeout — retry with backoff ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ### List fund registrants with N-PORT data - **Method:** `GET` - **Path:** `/api/v1/fund-portfolios/entities` - **Tags:** Fund Portfolios Discovery endpoint — list distinct fund registrants with Form N-PORT filings on file. Returns one row per `registrant_cik` with: - Registrant identifiers (CIK, modal name, ticker symbols when present) - `filing_count` — total N-PORT filings on file - `period_min` / `period_max` — earliest and latest period\_of\_report **Examples:** - All registrants: `/fund-portfolios/entities` - Search by name: `/fund-portfolios/entities?search=vanguard` - Most-active registrants first: `/fund-portfolios/entities?sort=filing_count&order=desc` **See also:** `/api/v1/entities/{cik}` for the registry-level profile of any registrant returned here. #### Responses ##### Status: 200 Successful Response ###### Content-Type: application/json - **`data` (required)** `array` — Page of fund registrants with N-PORT data on file. **Items:** - **`cik` (required)** `string` — Required. Fund registrant CIK (canonical short form). - **`filing_count` (required)** `integer` — Required. Total N-PORT filings on file for this registrant. - **`company_name`** `object` — Optional. Modal registrant name across the registrant's N-PORT filings. - **`period_max`** `object` — Optional. Latest period\_of\_report observed for this registrant. - **`period_min`** `object` — Optional. Earliest period\_of\_report observed for this registrant. - **`tickers`** `object` — Optional. Registrant ticker symbols sampled from one filing's \`filer\_tickers\`. - **`page_size` (required)** `integer` — Results per page - **`page`** `integer`, default: `1` — Current page number (1-indexed) - **`total`** `integer`, default: `0` — Total count of matching rows - **`total_pages`** `integer`, default: `1` — Total number of pages **Example:** ```json { "total": 0, "page": 1, "page_size": 1, "total_pages": 1, "data": [ { "cik": "", "company_name": "", "tickers": [ "" ], "filing_count": 1, "period_min": "", "period_max": "" } ] } ``` ##### Status: 401 Authentication failed - missing or invalid API key ###### Content-Type: application/json - **`message`** `string` **Example:** ```json { "message": "Missing API key in request" } ``` ##### Status: 422 Request validation failed - invalid or missing parameters ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 429 Rate limit exceeded for your tier ###### Content-Type: application/json - **`message`** `string` **Example:** ```json { "message": "" } ``` ##### Status: 500 Unhandled server error — file an issue with the request\_id from the error envelope. ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 502 Upstream dependency failed — gateway, key store, or downstream service unavailable. ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 503 Database query error or timeout — retry with backoff ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ### Get a Form N-PORT fund portfolio filing - **Method:** `GET` - **Path:** `/api/v1/fund-portfolios/{filing_id}` - **Tags:** Fund Portfolios Returns the parent filing only — holdings (avg 500/filing, max 394k) are NOT bundled. Fetch them via `/api/v1/fund-portfolios/holdings?filing_id={filing_id}`. #### Responses ##### Status: 200 Successful Response ###### Content-Type: application/json - **`accession_num` (required)** `object` — EDGAR accession number derived from filing\_id (e.g., '0000320193-24-000123') - **`cik` (required)** `string` — Filer SEC Central Index Key - **`filing_id` (required)** `string` — Unique filing identifier - **`form_type` (required)** `string` — SEC form type (e.g., 'N-PORT', 'N-PORT/A') - **`source_url` (required)** `object` — Canonical SEC EDGAR Archives URL pointing at the filing's index page - **`accepted_time`** `object` — When the SEC accepted the filing - **`class_id`** `object` — SEC share class identifier (e.g., C000001234) - **`filer_name`** `object` — Filer entity name - **`filer_tickers`** `object` — Ticker symbols associated with the filer - **`form_data`** `object` — Full N-PORT form\_data JSON (omit with include\_form\_data=false) - **`holdings_count`** `object` — Count of holdings rows for this filing. - **`holdings_url`** `object` — Convenience link to fetch this filing's holdings via /fund-portfolios/holdings - **`is_confidential`** `object` — True if filing is confidential treatment - **`is_final_filing`** `object` — True if this is a final (de-registration) filing - **`is_valid`** `object` — Whether the filing passed validation - **`period_of_report`** `object` — Reporting period end date - **`previous_accession_number`** `object` — Accession number of the prior period's filing for this series - **`registrant_cik`** `object` — Fund registrant CIK (the registered investment company) - **`registrant_file_number`** `object` — Investment Company Act file number (e.g., 811-12345) - **`registrant_lei`** `object` — Fund registrant Legal Entity Identifier (20-char LEI) - **`registrant_name`** `object` — Fund registrant legal name - **`report_period_end`** `object` — End date of the reported portfolio period - **`series_id`** `object` — SEC fund series identifier (e.g., S000001234) - **`series_lei`** `object` — Fund series Legal Entity Identifier - **`series_name`** `object` — Fund series display name - **`submission_type`** `object` — N-PORT submission type (e.g., NPORT-P, NPORT-EX) **Example:** ```json { "filing_id": "", "cik": "", "form_type": "", "period_of_report": "", "accepted_time": "", "is_valid": true, "filer_name": "", "filer_tickers": [ "" ], "submission_type": "", "report_period_end": "", "is_confidential": true, "is_final_filing": true, "series_id": "", "class_id": "", "registrant_cik": "", "registrant_name": "", "registrant_lei": "", "series_name": "", "previous_accession_number": "", "series_lei": "", "registrant_file_number": "", "form_data": null, "holdings_count": 1, "holdings_url": "", "accession_num": "", "source_url": "" } ``` ##### Status: 401 Authentication failed - missing or invalid API key ###### Content-Type: application/json - **`message`** `string` **Example:** ```json { "message": "Missing API key in request" } ``` ##### Status: 404 Resource not found ###### Content-Type: application/json - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } ``` ##### Status: 422 Request validation failed - invalid or missing parameters ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 429 Rate limit exceeded for your tier ###### Content-Type: application/json - **`message`** `string` **Example:** ```json { "message": "" } ``` ##### Status: 500 Unhandled server error — file an issue with the request\_id from the error envelope. ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 502 Upstream dependency failed — gateway, key store, or downstream service unavailable. ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 503 Database query error or timeout — retry with backoff ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ### List Schedule 13D / 13G beneficial ownership filings - **Method:** `GET` - **Path:** `/api/v1/beneficial-ownership` - **Tags:** Beneficial Ownership List Schedule 13D (activist) and 13G (passive) filings. **Examples:** - All 13D activist filings: `?schedule_type=SC 13D` - Filings on AAPL: `?issuer_cusip=037833100` - Filings by a holder: `?cik=1067983` #### Responses ##### Status: 200 Successful Response ###### Content-Type: application/json - **`data` (required)** `array` — Page of Schedule 13D/G filing rows **Items:** - **`accession_num` (required)** `object` — EDGAR accession number derived from filing\_id (e.g., '0000320193-24-000123') - **`cik` (required)** `string` — Filer SEC Central Index Key - **`filing_id` (required)** `string` — Unique filing identifier - **`form_type` (required)** `string` — SEC form type (e.g., 'SC 13D', 'SC 13G/A') - **`source_url` (required)** `object` — Canonical SEC EDGAR Archives URL pointing at the filing's index page - **`accepted_time`** `object` — When the SEC accepted the filing - **`amendment_no`** `object` — Amendment number if this is an amendment ('/A' filing) - **`event_date`** `object` — Date of the event triggering the filing - **`filer_name`** `object` — Filer entity name - **`filer_tickers`** `object` — Ticker symbols associated with the filer - **`is_valid`** `object` — Whether the filing passed validation - **`issuer_class_title`** `object` — Title of the security class (e.g., 'Common Stock', 'Class A Common') - **`issuer_cusip`** `object` — 9-character CUSIP of the security covered by the filing - **`issuer_name`** `object` — Issuer (target company) legal name - **`period_of_report`** `object` — Reporting period end date - **`rule_basis`** `object` — Filing-rule basis (e.g., '13d-1(a)', '13d-1(b)', '13d-1(c)', '13d-1(d)') - **`schedule_type`** `object` — Normalized schedule variant (see ScheduleType enum) - **`submission_type`** `object` — EDGAR submission type - **`page_size` (required)** `integer` — Results per page - **`page`** `integer`, default: `1` — Current page number (1-indexed) - **`total`** `integer`, default: `0` — Total count of matching rows - **`total_pages`** `integer`, default: `1` — Total number of pages **Example:** ```json { "total": 0, "page": 1, "page_size": 1, "total_pages": 1, "data": [ { "filing_id": "", "cik": "", "form_type": "", "schedule_type": "", "amendment_no": "", "accepted_time": "", "period_of_report": "", "is_valid": true, "filer_name": "", "filer_tickers": [ "" ], "submission_type": "", "issuer_cusip": "", "issuer_name": "", "issuer_class_title": "", "event_date": "", "rule_basis": "", "accession_num": "", "source_url": "" } ] } ``` ##### Status: 401 Authentication failed - missing or invalid API key ###### Content-Type: application/json - **`message`** `string` **Example:** ```json { "message": "Missing API key in request" } ``` ##### Status: 422 Request validation failed - invalid or missing parameters ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 429 Rate limit exceeded for your tier ###### Content-Type: application/json - **`message`** `string` **Example:** ```json { "message": "" } ``` ##### Status: 500 Unhandled server error — file an issue with the request\_id from the error envelope. ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 502 Upstream dependency failed — gateway, key store, or downstream service unavailable. ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 503 Database query error or timeout — retry with backoff ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ### List filers with Schedule 13D/G data - **Method:** `GET` - **Path:** `/api/v1/beneficial-ownership/entities` - **Tags:** Beneficial Ownership Discovery endpoint — list distinct filers (holders) with Schedule 13D/G filings on file. SC 13 filings carry no `issuer_cik`, so the natural grouping is by filer (the holder making the disclosure). Returns one row per filer `cik` with: - Filer identifiers (CIK, modal name, ticker symbols when present) - `filing_count` — total Schedule 13D/G filings on file - `period_min` / `period_max` — earliest and latest period\_of\_report **Examples:** - All filers: `/beneficial-ownership/entities` - Search by name: `/beneficial-ownership/entities?search=berkshire` - Most-active filers first: `/beneficial-ownership/entities?sort=filing_count&order=desc` **See also:** `/api/v1/entities/{cik}` for the registry-level profile of any filer returned here. #### Responses ##### Status: 200 Successful Response ###### Content-Type: application/json - **`data` (required)** `array` — Page of filers (holders) with Schedule 13D/G data on file. **Items:** - **`cik` (required)** `string` — Required. Filer (holder) SEC Central Index Key (canonical short form). - **`filing_count` (required)** `integer` — Required. Total Schedule 13D/G filings on file for this filer. - **`company_name`** `object` — Optional. Modal filer name across the filer's Schedule 13 filings. - **`period_max`** `object` — Optional. Latest period\_of\_report observed for this filer. - **`period_min`** `object` — Optional. Earliest period\_of\_report observed for this filer. - **`tickers`** `object` — Optional. Filer ticker symbols sampled from one filing's \`filer\_tickers\`. - **`page_size` (required)** `integer` — Results per page - **`page`** `integer`, default: `1` — Current page number (1-indexed) - **`total`** `integer`, default: `0` — Total count of matching rows - **`total_pages`** `integer`, default: `1` — Total number of pages **Example:** ```json { "total": 0, "page": 1, "page_size": 1, "total_pages": 1, "data": [ { "cik": "1067983", "company_name": "BERKSHIRE HATHAWAY INC", "filing_count": 47, "period_max": "2024-03-31", "period_min": "2010-12-31", "tickers": [ "BRK-A", "BRK-B" ] } ] } ``` ##### Status: 401 Authentication failed - missing or invalid API key ###### Content-Type: application/json - **`message`** `string` **Example:** ```json { "message": "Missing API key in request" } ``` ##### Status: 422 Request validation failed - invalid or missing parameters ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 429 Rate limit exceeded for your tier ###### Content-Type: application/json - **`message`** `string` **Example:** ```json { "message": "" } ``` ##### Status: 500 Unhandled server error — file an issue with the request\_id from the error envelope. ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 502 Upstream dependency failed — gateway, key store, or downstream service unavailable. ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 503 Database query error or timeout — retry with backoff ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ### Get a Schedule 13D/13G beneficial-ownership filing - **Method:** `GET` - **Path:** `/api/v1/beneficial-ownership/{filing_id}` - **Tags:** Beneficial Ownership #### Responses ##### Status: 200 Successful Response ###### Content-Type: application/json - **`accession_num` (required)** `object` — EDGAR accession number derived from filing\_id (e.g., '0000320193-24-000123') - **`cik` (required)** `string` — Filer SEC Central Index Key - **`filing_id` (required)** `string` — Unique filing identifier - **`form_type` (required)** `string` — SEC form type (e.g., 'SC 13D', 'SC 13G/A') - **`source_url` (required)** `object` — Canonical SEC EDGAR Archives URL pointing at the filing's index page - **`accepted_time`** `object` — When the SEC accepted the filing - **`amendment_no`** `object` — Amendment number if this is an amendment ('/A' filing) - **`event_date`** `object` — Date of the event triggering the filing - **`exhibits`** `array` — All exhibits attached to this filing **Items:** - **`record_index` (required)** `integer` — Per-filing 0-based ordinal of this exhibit - **`letter`** `object` — Exhibit letter or designator (e.g., 'A', 'B', '99') - **`schedule_type`** `object` — Schedule variant the exhibit belongs to - **`title`** `object` — Exhibit title or description - **`filer_name`** `object` — Filer entity name - **`filer_tickers`** `object` — Ticker symbols associated with the filer - **`is_valid`** `object` — Whether the filing passed validation - **`issuer_class_title`** `object` — Title of the security class (e.g., 'Common Stock', 'Class A Common') - **`issuer_cusip`** `object` — 9-character CUSIP of the security covered by the filing - **`issuer_name`** `object` — Issuer (target company) legal name - **`period_of_report`** `object` — Reporting period end date - **`reporting_persons`** `array` — All reporting-person cover-page rows attached to this filing **Items:** - **`record_index` (required)** `integer` — Per-filing 0-based ordinal of this person row - **`aggregate_amount`** `object` — Item 11: aggregate beneficial ownership reported by this person - **`citizenship`** `object` — Citizenship or place of organization (Item 6 of the cover page) - **`cusip`** `object` — CUSIP repeated on the reporting-person cover page - **`excludes_certain_shares`** `object` — Item 12: row 11 excludes certain shares - **`group_member_a`** `object` — Item 2(a): person is part of a Section 13(d) group - **`group_member_b`** `object` — Item 2(b): person is excluded from the group - **`legal_proceedings_required`** `object` — Item 5: legal-proceedings disclosure required for this person - **`names`** `object` — Reporting person name (Item 1 of the cover page) - **`percent_of_class`** `object` — Item 13: percent of class represented by row 11 (whole number, e.g. 5.2) - **`reporting_person_type`** `object` — Cover-page Item 2 type code (e.g., IN individual, OO other, BD broker-dealer) - **`sec_use_only`** `object` — Item 3: SEC use only — typically blank in filings - **`shared_dispositive_power`** `object` — Item 10: shares with shared dispositive power - **`shared_voting_power`** `object` — Item 8: shares with shared voting power - **`sole_dispositive_power`** `object` — Item 9: shares with sole dispositive power - **`sole_voting_power`** `object` — Item 7: shares with sole voting power - **`source_of_funds`** `object` — Item 4 source-of-funds codes (e.g., 'WC' working capital, 'PF' personal funds, 'AF' affiliate funds) - **`rule_basis`** `object` — Filing-rule basis (e.g., '13d-1(a)', '13d-1(b)', '13d-1(c)', '13d-1(d)') - **`schedule_type`** `object` — Normalized schedule variant (see ScheduleType enum) - **`submission_type`** `object` — EDGAR submission type **Example:** ```json { "filing_id": "", "cik": "", "form_type": "", "schedule_type": "", "amendment_no": "", "accepted_time": "", "period_of_report": "", "is_valid": true, "filer_name": "", "filer_tickers": [ "" ], "submission_type": "", "issuer_cusip": "", "issuer_name": "", "issuer_class_title": "", "event_date": "", "rule_basis": "", "reporting_persons": [ { "record_index": 1, "cusip": "", "names": "", "citizenship": "", "reporting_person_type": "", "group_member_a": true, "group_member_b": true, "sec_use_only": "", "source_of_funds": "", "legal_proceedings_required": true, "sole_voting_power": "", "shared_voting_power": "", "sole_dispositive_power": "", "shared_dispositive_power": "", "aggregate_amount": "", "excludes_certain_shares": true, "percent_of_class": "" } ], "exhibits": [ { "record_index": 1, "schedule_type": "", "letter": "", "title": "" } ], "accession_num": "", "source_url": "" } ``` ##### Status: 401 Authentication failed - missing or invalid API key ###### Content-Type: application/json - **`message`** `string` **Example:** ```json { "message": "Missing API key in request" } ``` ##### Status: 404 Resource not found ###### Content-Type: application/json - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } ``` ##### Status: 422 Request validation failed - invalid or missing parameters ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 429 Rate limit exceeded for your tier ###### Content-Type: application/json - **`message`** `string` **Example:** ```json { "message": "" } ``` ##### Status: 500 Unhandled server error — file an issue with the request\_id from the error envelope. ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 502 Upstream dependency failed — gateway, key store, or downstream service unavailable. ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 503 Database query error or timeout — retry with backoff ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ### List Form 144 notices of proposed sale - **Method:** `GET` - **Path:** `/api/v1/proposed-sales` - **Tags:** Proposed Sales List Form 144 filings (notices of proposed sales of restricted/affiliate securities under SEC Rule 144). **Examples:** - All proposed sales for an issuer: `?issuer_cik=320193` - Big sales only: `?min_aggregate_market_value=1000000` - Sales by a particular seller: `?seller_name=Cook` #### Responses ##### Status: 200 Successful Response ###### Content-Type: application/json - **`data` (required)** `array` — Page of Form 144 filing rows **Items:** - **`accession_num` (required)** `object` — EDGAR accession number derived from filing\_id (e.g., '0000320193-24-000123') - **`cik` (required)** `string` — Filer SEC Central Index Key - **`filing_id` (required)** `string` — Unique filing identifier - **`form_type` (required)** `string` — SEC form type (e.g., '4', '13F-HR', 'D') - **`source_url` (required)** `object` — Canonical SEC EDGAR Archives URL pointing at the filing's index page - **`accepted_time`** `object` — When SEC accepted the filing - **`aggregate_market_value`** `object` — Aggregate market value of proposed sale (USD) - **`approx_sale_date`** `object` — Approximate date of proposed sale - **`filer_name`** `object` — Filer entity name - **`filer_tickers`** `object` — Ticker symbols associated with the filer - **`is_valid`** `object` — Whether the filing passed validation - **`issuer_cik`** `object` — Issuer CIK (the company whose securities are being sold) - **`issuer_name`** `object` — Issuer legal name - **`no_of_units_outstanding`** `object` — Total units of this class outstanding - **`no_of_units_sold`** `object` — Number of units proposed for sale - **`nothing_to_report_past_3_months`** `object` — True if filer reports no Rule 144 sales of this security in the past 3 months - **`notice_date`** `object` — Date the notice of proposed sale was given - **`period_of_report`** `object` — Reporting period end date - **`securities_class_title`** `object` — Class of securities proposed for sale (e.g., 'Common Stock', 'Class A Common') - **`securities_exchange_name`** `object` — Exchange where the sale will occur (e.g., 'NYSE', 'NASDAQ') - **`seller_name`** `object` — Seller name (typically an officer, director, or major holder) - **`submission_type`** `object` — EDGAR submission type - **`page_size` (required)** `integer` — Results per page - **`page`** `integer`, default: `1` — Current page number (1-indexed) - **`total`** `integer`, default: `0` — Total count of matching rows - **`total_pages`** `integer`, default: `1` — Total number of pages **Example:** ```json { "total": 0, "page": 1, "page_size": 1, "total_pages": 1, "data": [ { "filing_id": "", "cik": "", "form_type": "", "period_of_report": "", "accepted_time": "", "is_valid": true, "filer_name": "", "filer_tickers": [ "" ], "submission_type": "", "issuer_cik": "", "issuer_name": "", "seller_name": "", "securities_class_title": "", "no_of_units_sold": "", "aggregate_market_value": "", "no_of_units_outstanding": "", "approx_sale_date": "", "securities_exchange_name": "", "nothing_to_report_past_3_months": true, "notice_date": "", "accession_num": "", "source_url": "" } ] } ``` ##### Status: 401 Authentication failed - missing or invalid API key ###### Content-Type: application/json - **`message`** `string` **Example:** ```json { "message": "Missing API key in request" } ``` ##### Status: 422 Request validation failed - invalid or missing parameters ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 429 Rate limit exceeded for your tier ###### Content-Type: application/json - **`message`** `string` **Example:** ```json { "message": "" } ``` ##### Status: 500 Unhandled server error — file an issue with the request\_id from the error envelope. ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 502 Upstream dependency failed — gateway, key store, or downstream service unavailable. ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 503 Database query error or timeout — retry with backoff ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ### List issuers with Form 144 data - **Method:** `GET` - **Path:** `/api/v1/proposed-sales/entities` - **Tags:** Proposed Sales Discovery endpoint — list distinct issuers (companies whose stock is being sold) with Form 144 filings on file. Returns one row per `issuer_cik` with: - Issuer identifiers (CIK, modal name) - `filing_count` — total Form 144 filings on file naming this issuer - `period_min` / `period_max` — earliest and latest period\_of\_report **Examples:** - All issuers: `/proposed-sales/entities` - Search by name: `/proposed-sales/entities?search=apple` - Most-active issuers first: `/proposed-sales/entities?sort=filing_count&order=desc` **See also:** `/api/v1/entities/{cik}` for the registry-level profile of any issuer returned here. #### Responses ##### Status: 200 Successful Response ###### Content-Type: application/json - **`data` (required)** `array` — Page of issuers with Form 144 data on file. **Items:** - **`cik` (required)** `string` — Required. Issuer SEC Central Index Key (canonical short form, no leading zeros). - **`filing_count` (required)** `integer` — Required. Total Form 144 filings on file naming this issuer. - **`company_name`** `object` — Optional. Modal issuer name across the issuer's Form 144 filings. - **`period_max`** `object` — Optional. Latest period\_of\_report observed for this issuer. - **`period_min`** `object` — Optional. Earliest period\_of\_report observed for this issuer. - **`tickers`** `object` — Optional. Issuer ticker symbols sampled from one filing's \`filer\_tickers\`. - **`page_size` (required)** `integer` — Results per page - **`page`** `integer`, default: `1` — Current page number (1-indexed) - **`total`** `integer`, default: `0` — Total count of matching rows - **`total_pages`** `integer`, default: `1` — Total number of pages **Example:** ```json { "total": 0, "page": 1, "page_size": 1, "total_pages": 1, "data": [ { "cik": "", "company_name": "", "tickers": [ "" ], "filing_count": 1, "period_min": "", "period_max": "" } ] } ``` ##### Status: 401 Authentication failed - missing or invalid API key ###### Content-Type: application/json - **`message`** `string` **Example:** ```json { "message": "Missing API key in request" } ``` ##### Status: 422 Request validation failed - invalid or missing parameters ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 429 Rate limit exceeded for your tier ###### Content-Type: application/json - **`message`** `string` **Example:** ```json { "message": "" } ``` ##### Status: 500 Unhandled server error — file an issue with the request\_id from the error envelope. ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 502 Upstream dependency failed — gateway, key store, or downstream service unavailable. ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 503 Database query error or timeout — retry with backoff ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ### Get a Form 144 notice of proposed sale - **Method:** `GET` - **Path:** `/api/v1/proposed-sales/{filing_id}` - **Tags:** Proposed Sales #### Responses ##### Status: 200 Successful Response ###### Content-Type: application/json - **`accession_num` (required)** `object` — EDGAR accession number derived from filing\_id (e.g., '0000320193-24-000123') - **`cik` (required)** `string` — Filer SEC Central Index Key - **`filing_id` (required)** `string` — Unique filing identifier - **`form_type` (required)** `string` — SEC form type (e.g., '4', '13F-HR', 'D') - **`source_url` (required)** `object` — Canonical SEC EDGAR Archives URL pointing at the filing's index page - **`accepted_time`** `object` — When SEC accepted the filing - **`acquisitions`** `array` — Original-acquisition rows for the securities being proposed for sale **Items:** - **`record_index` (required)** `integer` — Per-filing 0-based ordinal of this acquisition row - **`acquired_date`** `object` — Date the securities were originally acquired - **`amount_of_securities_acquired`** `object` — Number of units acquired in the original transaction - **`is_gift_transaction`** `object` — True if the original acquisition was a gift - **`name_of_person_from_whom_acquired`** `object` — Name of the prior owner (where applicable, e.g., for gifts or inheritances) - **`nature_of_acquisition_transaction`** `object` — Free-text description of how the securities were acquired (e.g., 'Stock Option Exercise', 'Gift', 'Inheritance') - **`nature_of_payment`** `object` — Free-text description of how payment was made - **`payment_date`** `object` — Date payment was made for the securities - **`securities_class_title`** `object` — Class of securities acquired - **`aggregate_market_value`** `object` — Aggregate market value of proposed sale (USD) - **`approx_sale_date`** `object` — Approximate date of proposed sale - **`broker_city`** `object` — Broker city - **`broker_name`** `object` — Executing broker name - **`broker_state_or_country`** `object` — Broker state code or country - **`broker_street1`** `object` — Broker street address line 1 - **`broker_zip_code`** `object` — Broker postal code - **`filer_name`** `object` — Filer entity name - **`filer_tickers`** `object` — Ticker symbols associated with the filer - **`is_valid`** `object` — Whether the filing passed validation - **`issuer_cik`** `object` — Issuer CIK (the company whose securities are being sold) - **`issuer_city`** `object` — Issuer city - **`issuer_name`** `object` — Issuer legal name - **`issuer_phone`** `object` — Issuer contact phone number - **`issuer_state_or_country`** `object` — Issuer state code or country - **`issuer_street1`** `object` — Issuer street address line 1 - **`issuer_zip_code`** `object` — Issuer postal code - **`no_of_units_outstanding`** `object` — Total units of this class outstanding - **`no_of_units_sold`** `object` — Number of units proposed for sale - **`nothing_to_report_past_3_months`** `object` — True if filer reports no Rule 144 sales of this security in the past 3 months - **`notice_date`** `object` — Date the notice of proposed sale was given - **`period_of_report`** `object` — Reporting period end date - **`plan_adoption_dates`** `object` — Rule 10b5-1 trading plan adoption dates (where the sale is made under such a plan) - **`previous_accession_number`** `object` — Accession number of the seller's prior Form 144 (where applicable) - **`prior_sales`** `array` — Rule 144 prior-sale rows for the past 3 months (volume-limit context) **Items:** - **`record_index` (required)** `integer` — Per-filing 0-based ordinal of this prior-sale row - **`amount_of_securities_sold`** `object` — Number of units sold in the prior sale - **`gross_proceeds`** `object` — Gross proceeds from the prior sale (USD) - **`sale_date`** `object` — Date of the prior sale - **`securities_class_title`** `object` — Class of securities previously sold - **`seller_name`** `object` — Name of the seller for this prior sale - **`relationships_to_issuer`** `object` — Seller's relationship(s) to the issuer (e.g., 'Officer', 'Director', '10% Shareholder') - **`remarks`** `object` — Free-text remarks attached to the filing - **`sec_file_number`** `object` — SEC file number of the issuer - **`securities_class_title`** `object` — Class of securities proposed for sale (e.g., 'Common Stock', 'Class A Common') - **`securities_exchange_name`** `object` — Exchange where the sale will occur (e.g., 'NYSE', 'NASDAQ') - **`seller_name`** `object` — Seller name (typically an officer, director, or major holder) - **`signature`** `object` — Seller signature attestation - **`submission_type`** `object` — EDGAR submission type **Example:** ```json { "filing_id": "", "cik": "", "form_type": "", "period_of_report": "", "accepted_time": "", "is_valid": true, "filer_name": "", "filer_tickers": [ "" ], "submission_type": "", "issuer_cik": "", "issuer_name": "", "seller_name": "", "securities_class_title": "", "no_of_units_sold": "", "aggregate_market_value": "", "no_of_units_outstanding": "", "approx_sale_date": "", "securities_exchange_name": "", "nothing_to_report_past_3_months": true, "notice_date": "", "previous_accession_number": "", "sec_file_number": "", "issuer_phone": "", "issuer_street1": "", "issuer_city": "", "issuer_state_or_country": "", "issuer_zip_code": "", "relationships_to_issuer": null, "broker_name": "", "broker_street1": "", "broker_city": "", "broker_state_or_country": "", "broker_zip_code": "", "plan_adoption_dates": null, "remarks": "", "signature": "", "acquisitions": [ { "record_index": 1, "securities_class_title": "", "acquired_date": "", "nature_of_acquisition_transaction": "", "name_of_person_from_whom_acquired": "", "is_gift_transaction": true, "amount_of_securities_acquired": "", "payment_date": "", "nature_of_payment": "" } ], "prior_sales": [ { "record_index": 1, "seller_name": "", "securities_class_title": "", "sale_date": "", "amount_of_securities_sold": "", "gross_proceeds": "" } ], "accession_num": "", "source_url": "" } ``` ##### Status: 401 Authentication failed - missing or invalid API key ###### Content-Type: application/json - **`message`** `string` **Example:** ```json { "message": "Missing API key in request" } ``` ##### Status: 404 Resource not found ###### Content-Type: application/json - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } ``` ##### Status: 422 Request validation failed - invalid or missing parameters ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 429 Rate limit exceeded for your tier ###### Content-Type: application/json - **`message`** `string` **Example:** ```json { "message": "" } ``` ##### Status: 500 Unhandled server error — file an issue with the request\_id from the error envelope. ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 502 Upstream dependency failed — gateway, key store, or downstream service unavailable. ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 503 Database query error or timeout — retry with backoff ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ### List Form N-CEN annual investment company census filings - **Method:** `GET` - **Path:** `/api/v1/fund-census` - **Tags:** Fund Census List Form N-CEN filings — annual census reports from registered investment companies (mutual funds, ETFs, closed-end funds, BDCs, UITs). **Examples:** - All filings for a registrant: `?registrant_cik=1234567` - ETFs only: `?investment_company_type=N-1A` - Stub-period reports: `?is_report_period_lt_12=true` #### Responses ##### Status: 200 Successful Response ###### Content-Type: application/json - **`data` (required)** `array` — Page of N-CEN filing rows **Items:** - **`accession_num` (required)** `object` — EDGAR accession number derived from filing\_id (e.g., '0000320193-24-000123') - **`cik` (required)** `string` — Filer SEC Central Index Key - **`filing_id` (required)** `string` — Unique filing identifier - **`form_type` (required)** `string` — SEC form type (e.g., '4', '13F-HR', 'D') - **`source_url` (required)** `object` — Canonical SEC EDGAR Archives URL pointing at the filing's index page - **`accepted_time`** `object` — When SEC accepted the filing - **`filer_name`** `object` — Filer entity name - **`filer_tickers`** `object` — Ticker symbols associated with the filer - **`investment_company_type`** `object` — Investment company type code (see query-param doc) - **`is_report_period_lt_12`** `object` — True if the report covers less than 12 months - **`is_valid`** `object` — Whether the filing passed validation - **`period_of_report`** `object` — Reporting period end date - **`registrant_cik`** `object` — Fund registrant (registered investment company) CIK - **`registrant_lei`** `object` — Fund registrant Legal Entity Identifier (20 chars) - **`registrant_name`** `object` — Fund registrant legal name - **`submission_type`** `object` — EDGAR submission type - **`page_size` (required)** `integer` — Results per page - **`page`** `integer`, default: `1` — Current page number (1-indexed) - **`total`** `integer`, default: `0` — Total count of matching rows - **`total_pages`** `integer`, default: `1` — Total number of pages **Example:** ```json { "total": 0, "page": 1, "page_size": 1, "total_pages": 1, "data": [ { "filing_id": "", "cik": "", "form_type": "", "period_of_report": "", "accepted_time": "", "is_valid": true, "filer_name": "", "filer_tickers": [ "" ], "submission_type": "", "investment_company_type": "", "is_report_period_lt_12": true, "registrant_cik": "", "registrant_name": "", "registrant_lei": "", "accession_num": "", "source_url": "" } ] } ``` ##### Status: 401 Authentication failed - missing or invalid API key ###### Content-Type: application/json - **`message`** `string` **Example:** ```json { "message": "Missing API key in request" } ``` ##### Status: 422 Request validation failed - invalid or missing parameters ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 429 Rate limit exceeded for your tier ###### Content-Type: application/json - **`message`** `string` **Example:** ```json { "message": "" } ``` ##### Status: 500 Unhandled server error — file an issue with the request\_id from the error envelope. ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 502 Upstream dependency failed — gateway, key store, or downstream service unavailable. ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 503 Database query error or timeout — retry with backoff ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ### List registrants with N-CEN data - **Method:** `GET` - **Path:** `/api/v1/fund-census/entities` - **Tags:** Fund Census Discovery endpoint — list distinct registrants with Form N-CEN annual fund-census filings on file. Returns one row per `registrant_cik` with: - Registrant identifiers (CIK, modal name, ticker symbols when present) - `filing_count` — total N-CEN filings on file - `period_min` / `period_max` — earliest and latest period\_of\_report **Examples:** - All registrants: `/fund-census/entities` - Search by name: `/fund-census/entities?search=blackrock` - Most-active registrants first: `/fund-census/entities?sort=filing_count&order=desc` **See also:** `/api/v1/entities/{cik}` for the registry-level profile of any registrant returned here. #### Responses ##### Status: 200 Successful Response ###### Content-Type: application/json - **`data` (required)** `array` — Page of registrants with N-CEN data on file. **Items:** - **`cik` (required)** `string` — Required. Registrant SEC Central Index Key (canonical short form, no leading zeros). - **`filing_count` (required)** `integer` — Required. Total Form N-CEN filings on file for this registrant. - **`company_name`** `object` — Optional. Modal registrant name across the registrant's N-CEN filings. - **`period_max`** `object` — Optional. Latest period\_of\_report observed for this registrant. - **`period_min`** `object` — Optional. Earliest period\_of\_report observed for this registrant. - **`tickers`** `object` — Optional. Registrant ticker symbols sampled from one filing's \`filer\_tickers\`. - **`page_size` (required)** `integer` — Results per page - **`page`** `integer`, default: `1` — Current page number (1-indexed) - **`total`** `integer`, default: `0` — Total count of matching rows - **`total_pages`** `integer`, default: `1` — Total number of pages **Example:** ```json { "total": 0, "page": 1, "page_size": 1, "total_pages": 1, "data": [ { "cik": "", "company_name": "", "tickers": [ "" ], "filing_count": 1, "period_min": "", "period_max": "" } ] } ``` ##### Status: 401 Authentication failed - missing or invalid API key ###### Content-Type: application/json - **`message`** `string` **Example:** ```json { "message": "Missing API key in request" } ``` ##### Status: 422 Request validation failed - invalid or missing parameters ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 429 Rate limit exceeded for your tier ###### Content-Type: application/json - **`message`** `string` **Example:** ```json { "message": "" } ``` ##### Status: 500 Unhandled server error — file an issue with the request\_id from the error envelope. ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 502 Upstream dependency failed — gateway, key store, or downstream service unavailable. ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 503 Database query error or timeout — retry with backoff ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ### Get a Form N-CEN fund census filing - **Method:** `GET` - **Path:** `/api/v1/fund-census/{filing_id}` - **Tags:** Fund Census Returns the parent filing plus a flat `series[]` array and a flat `classes[]` array. Each class row carries `series_index` matching the parent series row's `record_index` so consumers can group client-side. #### Responses ##### Status: 200 Successful Response ###### Content-Type: application/json - **`accession_num` (required)** `object` — EDGAR accession number derived from filing\_id (e.g., '0000320193-24-000123') - **`cik` (required)** `string` — Filer SEC Central Index Key - **`filing_id` (required)** `string` — Unique filing identifier - **`form_type` (required)** `string` — SEC form type (e.g., '4', '13F-HR', 'D') - **`source_url` (required)** `object` — Canonical SEC EDGAR Archives URL pointing at the filing's index page - **`accepted_time`** `object` — When SEC accepted the filing - **`classes`** `array` — Flat list of share-class rows; group by \`series\[].record\_index == class.series\_index\` **Items:** - **`record_index` (required)** `integer` — Per-filing 0-based ordinal of this class row - **`series_index` (required)** `integer` — record\_index of the parent series row in the same filing's series\[] list - **`class_id`** `object` — SEC share class identifier (e.g., C000001234) - **`extra_data`** `object` — Additional class-level fields (varies by investment-company type) - **`series_id`** `object` — SEC fund series identifier the class belongs to - **`filer_name`** `object` — Filer entity name - **`filer_tickers`** `object` — Ticker symbols associated with the filer - **`form_data`** `object` — Full N-CEN form\_data JSON (omit by passing include\_form\_data=false on the request) - **`investment_comp_file_no`** `object` — Investment Company Act file number (e.g., 811-12345) - **`investment_company_type`** `object` — Investment company type code (see query-param doc) - **`is_report_period_lt_12`** `object` — True if the report covers less than 12 months - **`is_valid`** `object` — Whether the filing passed validation - **`period_of_report`** `object` — Reporting period end date - **`previous_accession_number`** `object` — Accession number of the prior year's N-CEN filing for this registrant - **`registrant_cik`** `object` — Fund registrant (registered investment company) CIK - **`registrant_lei`** `object` — Fund registrant Legal Entity Identifier (20 chars) - **`registrant_name`** `object` — Fund registrant legal name - **`series`** `array` — All fund series rows reported on this filing **Items:** - **`record_index` (required)** `integer` — Per-filing 0-based ordinal of this series row - **`include_all_classes_flag`** `object` — True if the filing reports for all share classes of this series - **`registrant_cik`** `object` — Fund registrant CIK - **`registrant_name`** `object` — Fund registrant legal name - **`series_id`** `object` — SEC fund series identifier (e.g., S000001234) - **`submission_type`** `object` — EDGAR submission type **Example:** ```json { "filing_id": "", "cik": "", "form_type": "", "period_of_report": "", "accepted_time": "", "is_valid": true, "filer_name": "", "filer_tickers": [ "" ], "submission_type": "", "investment_company_type": "", "is_report_period_lt_12": true, "registrant_cik": "", "registrant_name": "", "registrant_lei": "", "previous_accession_number": "", "investment_comp_file_no": "", "form_data": null, "series": [ { "record_index": 1, "series_id": "", "include_all_classes_flag": true, "registrant_cik": "", "registrant_name": "" } ], "classes": [ { "series_index": 1, "record_index": 1, "series_id": "", "class_id": "", "extra_data": null } ], "accession_num": "", "source_url": "" } ``` ##### Status: 401 Authentication failed - missing or invalid API key ###### Content-Type: application/json - **`message`** `string` **Example:** ```json { "message": "Missing API key in request" } ``` ##### Status: 404 Resource not found ###### Content-Type: application/json - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } ``` ##### Status: 422 Request validation failed - invalid or missing parameters ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 429 Rate limit exceeded for your tier ###### Content-Type: application/json - **`message`** `string` **Example:** ```json { "message": "" } ``` ##### Status: 500 Unhandled server error — file an issue with the request\_id from the error envelope. ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 502 Upstream dependency failed — gateway, key store, or downstream service unavailable. ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 503 Database query error or timeout — retry with backoff ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ### List Form N-MFP2 money market fund filings - **Method:** `GET` - **Path:** `/api/v1/money-market-funds` - **Tags:** Money Market Funds List Form N-MFP2 filings — monthly portfolio reports from money market funds. **Examples:** - All Government MMFs: `?money_market_fund_category=Government` - Filings for a registrant: `?registrant_cik=1234567` - Recent filings: `?accepted_start=2024-01-01` #### Responses ##### Status: 200 Successful Response ###### Content-Type: application/json - **`data` (required)** `array` — Page of N-MFP2 filing rows **Items:** - **`accession_num` (required)** `object` — EDGAR accession number derived from filing\_id (e.g., '0000320193-24-000123') - **`cik` (required)** `string` — Filer SEC Central Index Key - **`filing_id` (required)** `string` — Unique filing identifier - **`form_type` (required)** `string` — SEC form type (e.g., '4', '13F-HR', 'D') - **`source_url` (required)** `object` — Canonical SEC EDGAR Archives URL pointing at the filing's index page - **`accepted_time`** `object` — When SEC accepted the filing - **`feeder_fund_flag`** `object` — True if this is a feeder fund in a master-feeder structure - **`filer_name`** `object` — Filer entity name - **`filer_tickers`** `object` — Ticker symbols associated with the filer - **`is_final_filing`** `object` — True if this is a final (de-registration) filing - **`is_valid`** `object` — Whether the filing passed validation - **`master_fund_flag`** `object` — True if this is a master fund in a master-feeder structure - **`money_market_fund_category`** `object` — MMF category code (see query-param doc) - **`net_asset_of_series`** `object` — Net assets of the fund series at period end (USD) - **`period_of_report`** `object` — Reporting period end date - **`registrant_lei`** `object` — Fund registrant Legal Entity Identifier (20 chars) - **`registrant_name`** `object` — Fund registrant legal name - **`retail_money_market_fund_flag`** `object` — True if this is a retail (non-institutional) MMF - **`series_id`** `object` — SEC fund series identifier - **`series_lei`** `object` — Fund series LEI - **`series_name`** `object` — Fund series display name - **`seven_day_gross_yield`** `object` — Series-level 7-day gross yield (annualized) - **`submission_type`** `object` — EDGAR submission type - **`total_share_classes`** `object` — Total share classes belonging to this series - **`page_size` (required)** `integer` — Results per page - **`page`** `integer`, default: `1` — Current page number (1-indexed) - **`total`** `integer`, default: `0` — Total count of matching rows - **`total_pages`** `integer`, default: `1` — Total number of pages **Example:** ```json { "total": 0, "page": 1, "page_size": 1, "total_pages": 1, "data": [ { "filing_id": "", "cik": "", "form_type": "", "period_of_report": "", "accepted_time": "", "is_valid": true, "filer_name": "", "filer_tickers": [ "" ], "submission_type": "", "series_id": "", "registrant_name": "", "registrant_lei": "", "series_name": "", "series_lei": "", "total_share_classes": 1, "is_final_filing": true, "money_market_fund_category": "", "feeder_fund_flag": true, "master_fund_flag": true, "retail_money_market_fund_flag": true, "net_asset_of_series": "", "seven_day_gross_yield": "", "accession_num": "", "source_url": "" } ] } ``` ##### Status: 401 Authentication failed - missing or invalid API key ###### Content-Type: application/json - **`message`** `string` **Example:** ```json { "message": "Missing API key in request" } ``` ##### Status: 422 Request validation failed - invalid or missing parameters ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 429 Rate limit exceeded for your tier ###### Content-Type: application/json - **`message`** `string` **Example:** ```json { "message": "" } ``` ##### Status: 500 Unhandled server error — file an issue with the request\_id from the error envelope. ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 502 Upstream dependency failed — gateway, key store, or downstream service unavailable. ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 503 Database query error or timeout — retry with backoff ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ### Cross-filing N-MFP2 securities stream - **Method:** `GET` - **Path:** `/api/v1/money-market-funds/securities` - **Tags:** Money Market Funds Stream money-market fund holdings across many filings — supports fund-overlap by `cusip_member`/`isin_id`/`lei_id`, single-filing pull via `filing_id`, time-series via `registrant_cik` + period range. **Required:** at least one of `cusip_member`, `isin_id`, `lei_id`, `name_of_issuer`, `registrant_cik`, `filing_id`. Returns `400 MISSING_PARAMETER` otherwise. #### Responses ##### Status: 200 Successful Response ###### Content-Type: application/json - **`data` (required)** `array` — Page of N-MFP2 security rows **Items:** - **`filing_id` (required)** `string` — Filing this security belongs to - **`record_index` (required)** `integer` — Per-filing 0-based ordinal of this security row - **`coupon`** `object` — Coupon rate of the security (annualized) - **`cusip_member`** `object` — CUSIP of the held security - **`daily_liquid_asset_security_flag`** `object` — True if security counts as a daily-liquid asset - **`excluding_value_of_any_sponsor_support`** `object` — Security value excluding any sponsor support (USD) - **`final_legal_investment_maturity_date`** `object` — Final legal maturity date of the security - **`illiquid_security_flag`** `object` — True if security is classified as illiquid under Rule 2a-7 - **`including_value_of_any_sponsor_support`** `object` — Security value including any sponsor support (USD) - **`investment_category`** `object` — N-MFP2 investment category (see query-param doc) - **`investment_maturity_date_wal`** `object` — Days to maturity used for WAL calculation (regulatory definition) - **`investment_maturity_date_wam`** `object` — Days to maturity used for WAM calculation (regulatory definition) - **`isin_id`** `object` — ISIN of the held security (12 chars) - **`lei_id`** `object` — Issuer LEI (20 chars) - **`name_of_issuer`** `object` — Issuer name of the held security - **`percentage_of_money_market_fund_net_assets`** `object` — Security as a percent of fund net assets - **`period_of_report`** `object` — Reporting period end date - **`security_eligibility_flag`** `object` — Rule 2a-7 eligibility tier: 'First Tier' or 'Second Tier' - **`series_id`** `object` — SEC fund series identifier - **`series_name`** `object` — Fund series display name - **`title_of_issuer`** `object` — Title / description of the security - **`weekly_liquid_asset_security_flag`** `object` — True if security counts as a weekly-liquid asset - **`yield_of_the_security_as_of_reporting_date`** `object` — Security yield at the reporting date (annualized) - **`page_size` (required)** `integer` — Results per page - **`page`** `integer`, default: `1` — Current page number (1-indexed) - **`total`** `integer`, default: `0` — Total count of matching rows - **`total_pages`** `integer`, default: `1` — Total number of pages **Example:** ```json { "total": 0, "page": 1, "page_size": 1, "total_pages": 1, "data": [ { "filing_id": "", "record_index": 1, "period_of_report": "", "series_id": "", "series_name": "", "name_of_issuer": "", "title_of_issuer": "", "cusip_member": "", "isin_id": "", "lei_id": "", "investment_category": "", "security_eligibility_flag": "", "investment_maturity_date_wam": 1, "investment_maturity_date_wal": 1, "final_legal_investment_maturity_date": "", "yield_of_the_security_as_of_reporting_date": "", "including_value_of_any_sponsor_support": "", "excluding_value_of_any_sponsor_support": "", "percentage_of_money_market_fund_net_assets": "", "daily_liquid_asset_security_flag": true, "weekly_liquid_asset_security_flag": true, "illiquid_security_flag": true, "coupon": "" } ] } ``` ##### Status: 400 Request rejected — usually a missing required parameter or an at-least-one-of constraint not satisfied. ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 401 Authentication failed - missing or invalid API key ###### Content-Type: application/json - **`message`** `string` **Example:** ```json { "message": "Missing API key in request" } ``` ##### Status: 422 Request validation failed - invalid or missing parameters ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 429 Rate limit exceeded for your tier ###### Content-Type: application/json - **`message`** `string` **Example:** ```json { "message": "" } ``` ##### Status: 500 Unhandled server error — file an issue with the request\_id from the error envelope. ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 502 Upstream dependency failed — gateway, key store, or downstream service unavailable. ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 503 Database query error or timeout — retry with backoff ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ### Series-level N-MFP2 NAV time series - **Method:** `GET` - **Path:** `/api/v1/money-market-funds/series-nav` - **Tags:** Money Market Funds Series-level NAV history for a money-market fund. **Required:** at least one of `registrant_cik`, `series_id`, `filing_id`. Returns `400 MISSING_PARAMETER` otherwise. #### Responses ##### Status: 200 Successful Response ###### Content-Type: application/json - **`data` (required)** `array` — Page of series-NAV time-series points **Items:** - **`filing_id` (required)** `string` — Filing this point came from - **`record_index` (required)** `integer` — Per-filing 0-based ordinal of this point - **`date`** `object` — Date of this NAV observation - **`granularity`** `object` — 'monthly' (filing date) or 'daily' (intra-month) - **`series_id`** `object` — SEC fund series identifier - **`series_name`** `object` — Fund series display name - **`value`** `object` — NAV value at this date (USD) - **`page_size` (required)** `integer` — Results per page - **`page`** `integer`, default: `1` — Current page number (1-indexed) - **`total`** `integer`, default: `0` — Total count of matching rows - **`total_pages`** `integer`, default: `1` — Total number of pages **Example:** ```json { "total": 0, "page": 1, "page_size": 1, "total_pages": 1, "data": [ { "filing_id": "", "record_index": 1, "series_id": "", "series_name": "", "date": "", "value": "", "granularity": "" } ] } ``` ##### Status: 400 Request rejected — usually a missing required parameter or an at-least-one-of constraint not satisfied. ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 401 Authentication failed - missing or invalid API key ###### Content-Type: application/json - **`message`** `string` **Example:** ```json { "message": "Missing API key in request" } ``` ##### Status: 422 Request validation failed - invalid or missing parameters ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 429 Rate limit exceeded for your tier ###### Content-Type: application/json - **`message`** `string` **Example:** ```json { "message": "" } ``` ##### Status: 500 Unhandled server error — file an issue with the request\_id from the error envelope. ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 502 Upstream dependency failed — gateway, key store, or downstream service unavailable. ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 503 Database query error or timeout — retry with backoff ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ### Series-level N-MFP2 liquid-assets time series - **Method:** `GET` - **Path:** `/api/v1/money-market-funds/liquid-assets` - **Tags:** Money Market Funds Series-level daily/weekly liquid-asset percentages. **Required:** at least one of `registrant_cik`, `series_id`, `filing_id`. Returns `400 MISSING_PARAMETER` otherwise. #### Responses ##### Status: 200 Successful Response ###### Content-Type: application/json - **`data` (required)** `array` — Page of liquid-assets time-series points **Items:** - **`filing_id` (required)** `string` — Filing this point came from - **`record_index` (required)** `integer` — Per-filing 0-based ordinal of this point - **`date`** `object` — Date of this observation - **`granularity`** `object` — 'monthly' (filing date) or 'daily' (intra-month) - **`percentage_daily_liquid_assets`** `object` — Daily-liquid assets as a percent of total assets - **`percentage_weekly_liquid_assets`** `object` — Weekly-liquid assets as a percent of total assets - **`series_id`** `object` — SEC fund series identifier - **`series_name`** `object` — Fund series display name - **`total_value_daily_liquid_assets`** `object` — Total daily-liquid assets at this date (USD) - **`total_value_weekly_liquid_assets`** `object` — Total weekly-liquid assets at this date (USD) - **`page_size` (required)** `integer` — Results per page - **`page`** `integer`, default: `1` — Current page number (1-indexed) - **`total`** `integer`, default: `0` — Total count of matching rows - **`total_pages`** `integer`, default: `1` — Total number of pages **Example:** ```json { "total": 0, "page": 1, "page_size": 1, "total_pages": 1, "data": [ { "filing_id": "", "record_index": 1, "series_id": "", "series_name": "", "date": "", "total_value_daily_liquid_assets": "", "total_value_weekly_liquid_assets": "", "percentage_daily_liquid_assets": "", "percentage_weekly_liquid_assets": "", "granularity": "" } ] } ``` ##### Status: 400 Request rejected — usually a missing required parameter or an at-least-one-of constraint not satisfied. ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 401 Authentication failed - missing or invalid API key ###### Content-Type: application/json - **`message`** `string` **Example:** ```json { "message": "Missing API key in request" } ``` ##### Status: 422 Request validation failed - invalid or missing parameters ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 429 Rate limit exceeded for your tier ###### Content-Type: application/json - **`message`** `string` **Example:** ```json { "message": "" } ``` ##### Status: 500 Unhandled server error — file an issue with the request\_id from the error envelope. ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 502 Upstream dependency failed — gateway, key store, or downstream service unavailable. ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 503 Database query error or timeout — retry with backoff ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ### Class-level N-MFP2 NAV time series - **Method:** `GET` - **Path:** `/api/v1/money-market-funds/class-nav` - **Tags:** Money Market Funds Class-level NAV history for a money-market fund share class. **Required:** at least one of `registrant_cik`, `series_id`, `classes_id`, `filing_id`. Returns `400 MISSING_PARAMETER` otherwise. #### Responses ##### Status: 200 Successful Response ###### Content-Type: application/json - **`data` (required)** `array` — Page of class-NAV time-series points **Items:** - **`class_index` (required)** `integer` — record\_index of the parent share class in the same filing's classes\[] list - **`filing_id` (required)** `string` — Filing this point came from - **`record_index` (required)** `integer` — Per-filing 0-based ordinal of this point - **`class_full_name`** `object` — Share class display name - **`classes_id`** `object` — SEC share-class identifier - **`date`** `object` — Date of this NAV observation - **`granularity`** `object` — 'monthly' or 'daily' - **`series_id`** `object` — SEC fund series identifier - **`series_name`** `object` — Fund series display name - **`value`** `object` — Class-level NAV value at this date (USD) - **`page_size` (required)** `integer` — Results per page - **`page`** `integer`, default: `1` — Current page number (1-indexed) - **`total`** `integer`, default: `0` — Total count of matching rows - **`total_pages`** `integer`, default: `1` — Total number of pages **Example:** ```json { "total": 0, "page": 1, "page_size": 1, "total_pages": 1, "data": [ { "filing_id": "", "class_index": 1, "record_index": 1, "series_id": "", "series_name": "", "classes_id": "", "class_full_name": "", "date": "", "value": "", "granularity": "" } ] } ``` ##### Status: 400 Request rejected — usually a missing required parameter or an at-least-one-of constraint not satisfied. ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 401 Authentication failed - missing or invalid API key ###### Content-Type: application/json - **`message`** `string` **Example:** ```json { "message": "Missing API key in request" } ``` ##### Status: 422 Request validation failed - invalid or missing parameters ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 429 Rate limit exceeded for your tier ###### Content-Type: application/json - **`message`** `string` **Example:** ```json { "message": "" } ``` ##### Status: 500 Unhandled server error — file an issue with the request\_id from the error envelope. ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 502 Upstream dependency failed — gateway, key store, or downstream service unavailable. ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 503 Database query error or timeout — retry with backoff ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ### Class-level N-MFP2 subscriptions/redemptions time series - **Method:** `GET` - **Path:** `/api/v1/money-market-funds/class-flows` - **Tags:** Money Market Funds Class-level gross subscriptions and redemptions history. **Required:** at least one of `registrant_cik`, `series_id`, `classes_id`, `filing_id`. Returns `400 MISSING_PARAMETER` otherwise. #### Responses ##### Status: 200 Successful Response ###### Content-Type: application/json - **`data` (required)** `array` — Page of class subscriptions/redemptions time-series points **Items:** - **`class_index` (required)** `integer` — record\_index of the parent share class in the same filing's classes\[] list - **`filing_id` (required)** `string` — Filing this point came from - **`record_index` (required)** `integer` — Per-filing 0-based ordinal of this point - **`class_full_name`** `object` — Share class display name - **`classes_id`** `object` — SEC share-class identifier - **`date`** `object` — Date of this flow observation - **`granularity`** `object` — 'monthly' or 'daily' - **`gross_redemptions`** `object` — Gross redemptions on this date (USD) - **`gross_subscriptions`** `object` — Gross subscriptions on this date (USD) - **`series_id`** `object` — SEC fund series identifier - **`series_name`** `object` — Fund series display name - **`page_size` (required)** `integer` — Results per page - **`page`** `integer`, default: `1` — Current page number (1-indexed) - **`total`** `integer`, default: `0` — Total count of matching rows - **`total_pages`** `integer`, default: `1` — Total number of pages **Example:** ```json { "total": 0, "page": 1, "page_size": 1, "total_pages": 1, "data": [ { "filing_id": "", "class_index": 1, "record_index": 1, "series_id": "", "series_name": "", "classes_id": "", "class_full_name": "", "date": "", "gross_subscriptions": "", "gross_redemptions": "", "granularity": "" } ] } ``` ##### Status: 400 Request rejected — usually a missing required parameter or an at-least-one-of constraint not satisfied. ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 401 Authentication failed - missing or invalid API key ###### Content-Type: application/json - **`message`** `string` **Example:** ```json { "message": "Missing API key in request" } ``` ##### Status: 422 Request validation failed - invalid or missing parameters ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 429 Rate limit exceeded for your tier ###### Content-Type: application/json - **`message`** `string` **Example:** ```json { "message": "" } ``` ##### Status: 500 Unhandled server error — file an issue with the request\_id from the error envelope. ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 502 Upstream dependency failed — gateway, key store, or downstream service unavailable. ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 503 Database query error or timeout — retry with backoff ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ### List N-MFP2 registrants with money-market-fund data - **Method:** `GET` - **Path:** `/api/v1/money-market-funds/entities` - **Tags:** Money Market Funds Discovery endpoint — list distinct N-MFP2 registrants with filings on file. Grouped by `form_cik` (the established registrant proxy on this view). Returns one row per registrant CIK with: - Registrant identifiers (CIK, modal name, ticker symbols when present) - `filing_count` — total N-MFP2 filings on file - `period_min` / `period_max` — earliest and latest period\_of\_report **Examples:** - All registrants: `/money-market-funds/entities` - Search by name: `/money-market-funds/entities?search=fidelity` - Most-active registrants first: `/money-market-funds/entities?sort=filing_count&order=desc` **See also:** `/api/v1/entities/{cik}` for the registry-level profile of any registrant returned here. #### Responses ##### Status: 200 Successful Response ###### Content-Type: application/json - **`data` (required)** `array` — Page of N-MFP2 registrants with money-market-fund data on file. **Items:** - **`cik` (required)** `string` — Required. Form\_cik (registrant CIK on N-MFP2; canonical short form). - **`filing_count` (required)** `integer` — Required. Total N-MFP2 filings on file for this registrant. - **`company_name`** `object` — Optional. Modal registrant name across the registrant's N-MFP2 filings. - **`period_max`** `object` — Optional. Latest period\_of\_report observed for this registrant. - **`period_min`** `object` — Optional. Earliest period\_of\_report observed for this registrant. - **`tickers`** `object` — Optional. Registrant ticker symbols sampled from one filing's \`filer\_tickers\`. - **`page_size` (required)** `integer` — Results per page - **`page`** `integer`, default: `1` — Current page number (1-indexed) - **`total`** `integer`, default: `0` — Total count of matching rows - **`total_pages`** `integer`, default: `1` — Total number of pages **Example:** ```json { "total": 0, "page": 1, "page_size": 1, "total_pages": 1, "data": [ { "cik": "", "company_name": "", "tickers": [ "" ], "filing_count": 1, "period_min": "", "period_max": "" } ] } ``` ##### Status: 401 Authentication failed - missing or invalid API key ###### Content-Type: application/json - **`message`** `string` **Example:** ```json { "message": "Missing API key in request" } ``` ##### Status: 422 Request validation failed - invalid or missing parameters ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 429 Rate limit exceeded for your tier ###### Content-Type: application/json - **`message`** `string` **Example:** ```json { "message": "" } ``` ##### Status: 500 Unhandled server error — file an issue with the request\_id from the error envelope. ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 502 Upstream dependency failed — gateway, key store, or downstream service unavailable. ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 503 Database query error or timeout — retry with backoff ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ### Get a Form N-MFP2 money market fund filing - **Method:** `GET` - **Path:** `/api/v1/money-market-funds/{filing_id}` - **Tags:** Money Market Funds Returns the parent filing plus bundled `classes[]` (small per filing). Securities (avg 92/filing) and the four time-series children are NOT bundled — each comes with a `*_count` and a `*_url` pointing at its dedicated cross-filing endpoint with the right `filing_id` filter. #### Responses ##### Status: 200 Successful Response ###### Content-Type: application/json - **`accession_num` (required)** `object` — EDGAR accession number derived from filing\_id (e.g., '0000320193-24-000123') - **`cik` (required)** `string` — Filer SEC Central Index Key - **`filing_id` (required)** `string` — Unique filing identifier - **`form_type` (required)** `string` — SEC form type (e.g., '4', '13F-HR', 'D') - **`source_url` (required)** `object` — Canonical SEC EDGAR Archives URL pointing at the filing's index page - **`accepted_time`** `object` — When SEC accepted the filing - **`administrator`** `object` — Fund administrator details - **`adviser`** `object` — Investment adviser firm details (one or more) - **`amortized_cost_portfolio_securities`** `object` — Amortized-cost value of portfolio securities (USD) - **`average_life_maturity`** `object` — Weighted average life maturity (WAL) in days, dollar-weighted - **`average_portfolio_maturity`** `object` — Weighted average portfolio maturity (WAM) in days, dollar-weighted - **`cash`** `object` — Total cash held by the fund (USD) - **`cash_mgmt_vehicle_affliated_fund_flag`** `object` — True if the fund is used as a cash-management vehicle by affiliated funds - **`class_flows_timeseries_count`** `object` — Total class-flows time-series points for this filing - **`class_flows_timeseries_url`** `object` — Convenience link to fetch class subscription/redemption time-series points - **`class_nav_timeseries_count`** `object` — Total class-NAV time-series points for this filing - **`class_nav_timeseries_url`** `object` — Convenience link to fetch class NAV time-series points - **`classes`** `array` — All share classes of this fund series **Items:** - **`record_index` (required)** `integer` — Per-filing 0-based ordinal of this class row - **`beneficial_record_owner_category`** `object` — Category of beneficial owner (e.g., 'Retail', 'NaturalPerson', 'Other') - **`class_full_name`** `object` — Share class display name (e.g., 'Institutional Class') - **`classes_id`** `object` — SEC share-class identifier (e.g., C000001234) - **`min_initial_investment`** `object` — Minimum initial investment for this share class (USD) - **`name_of_person_desc_expense_pay`** `object` — Name of the person paying expenses (where person\_pay\_for\_fund\_flag is true) - **`net_assets_of_class`** `object` — Net assets of the share class at period end (USD) - **`number_of_shares_outstanding`** `object` — Total shares outstanding for this class - **`person_pay_for_fund_flag`** `object` — True if a person (sponsor) is paying for fund expenses on behalf of this class - **`series_id`** `object` — SEC fund series identifier the class belongs to - **`series_name`** `object` — Fund series display name - **`seven_day_net_yield`** `object` — Class-level 7-day net yield (annualized, after fees) - **`shareholder_flows_monthly_redemptions`** `object` — Class-level total redemptions in the month (USD) - **`shareholder_flows_monthly_subscriptions`** `object` — Class-level total subscriptions in the month (USD) - **`feeder_fund_flag`** `object` — True if this is a feeder fund in a master-feeder structure - **`filer_name`** `object` — Filer entity name - **`filer_tickers`** `object` — Ticker symbols associated with the filer - **`fund_merged_or_acquired`** `object` — True if the fund merged with or was acquired by another fund - **`indp_pub_accountant`** `object` — Independent public accountant details - **`is_final_filing`** `object` — True if this is a final (de-registration) filing - **`is_valid`** `object` — Whether the filing passed validation - **`liquid_assets_timeseries_count`** `object` — Total liquid-assets time-series points for this filing - **`liquid_assets_timeseries_url`** `object` — Convenience link to fetch liquid-assets time-series points - **`liquidity_fee_fund_apply_flag`** `object` — True if the fund applied a liquidity fee in the period - **`master_fund_flag`** `object` — True if this is a master fund in a master-feeder structure - **`money_market_fund_category`** `object` — MMF category code (see query-param doc) - **`nav_timeseries_count`** `object` — Total series-NAV time-series points for this filing - **`nav_timeseries_url`** `object` — Convenience link to fetch series NAV time-series points - **`net_asset_of_series`** `object` — Net assets of the fund series at period end (USD) - **`period_of_report`** `object` — Reporting period end date - **`portfolio_dispositions`** `object` — JSON array of portfolio disposition events during the period - **`registrant_lei`** `object` — Fund registrant Legal Entity Identifier (20 chars) - **`registrant_name`** `object` — Fund registrant legal name - **`retail_money_market_fund_flag`** `object` — True if this is a retail (non-institutional) MMF - **`securities_act_file_number`** `object` — Securities Act file number (e.g., '333-12345') - **`securities_count`** `object` — Total portfolio securities reported on this filing - **`securities_url`** `object` — Convenience link to fetch this filing's securities rows - **`seek_stable_price_per_share`** `object` — True if the fund seeks to maintain a stable share price (versus a floating NAV) - **`series_id`** `object` — SEC fund series identifier - **`series_lei`** `object` — Fund series LEI - **`series_name`** `object` — Fund series display name - **`series_shares_outstanding`** `object` — Total shares outstanding across all classes of the series - **`seven_day_gross_yield`** `object` — Series-level 7-day gross yield (annualized) - **`signature`** `object` — Filing signature payload (signing officer + date) - **`stable_price_per_share`** `object` — Stable price per share if the fund seeks one (typically $1.0000) - **`sub_adviser`** `object` — Sub-adviser firm details (where applicable) - **`submission_type`** `object` — EDGAR submission type - **`total_share_classes`** `object` — Total share classes belonging to this series - **`total_value_liabilities`** `object` — Total liabilities of the fund (USD) - **`total_value_other_assets`** `object` — Total value of other assets (non-portfolio, non-cash) (USD) - **`total_value_portfolio_securities`** `object` — Total market value of portfolio securities (USD) - **`transfer_agent`** `object` — Transfer agent details **Example:** ```json { "filing_id": "", "cik": "", "form_type": "", "period_of_report": "", "accepted_time": "", "is_valid": true, "filer_name": "", "filer_tickers": [ "" ], "submission_type": "", "series_id": "", "registrant_name": "", "registrant_lei": "", "series_name": "", "series_lei": "", "total_share_classes": 1, "is_final_filing": true, "money_market_fund_category": "", "feeder_fund_flag": true, "master_fund_flag": true, "retail_money_market_fund_flag": true, "net_asset_of_series": "", "seven_day_gross_yield": "", "average_portfolio_maturity": "", "average_life_maturity": "", "cash": "", "total_value_portfolio_securities": "", "amortized_cost_portfolio_securities": "", "total_value_other_assets": "", "total_value_liabilities": "", "series_shares_outstanding": "", "stable_price_per_share": "", "seek_stable_price_per_share": true, "cash_mgmt_vehicle_affliated_fund_flag": true, "liquidity_fee_fund_apply_flag": true, "fund_merged_or_acquired": true, "securities_act_file_number": "", "portfolio_dispositions": null, "signature": null, "adviser": null, "sub_adviser": null, "indp_pub_accountant": null, "transfer_agent": null, "administrator": null, "classes": [ { "record_index": 1, "series_id": "", "series_name": "", "classes_id": "", "class_full_name": "", "min_initial_investment": "", "net_assets_of_class": "", "number_of_shares_outstanding": "", "seven_day_net_yield": "", "person_pay_for_fund_flag": true, "name_of_person_desc_expense_pay": "", "beneficial_record_owner_category": "", "shareholder_flows_monthly_subscriptions": "", "shareholder_flows_monthly_redemptions": "" } ], "securities_count": 1, "securities_url": "", "nav_timeseries_count": 1, "nav_timeseries_url": "", "liquid_assets_timeseries_count": 1, "liquid_assets_timeseries_url": "", "class_nav_timeseries_count": 1, "class_nav_timeseries_url": "", "class_flows_timeseries_count": 1, "class_flows_timeseries_url": "", "accession_num": "", "source_url": "" } ``` ##### Status: 401 Authentication failed - missing or invalid API key ###### Content-Type: application/json - **`message`** `string` **Example:** ```json { "message": "Missing API key in request" } ``` ##### Status: 404 Resource not found ###### Content-Type: application/json - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } ``` ##### Status: 422 Request validation failed - invalid or missing parameters ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 429 Rate limit exceeded for your tier ###### Content-Type: application/json - **`message`** `string` **Example:** ```json { "message": "" } ``` ##### Status: 500 Unhandled server error — file an issue with the request\_id from the error envelope. ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 502 Upstream dependency failed — gateway, key store, or downstream service unavailable. ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 503 Database query error or timeout — retry with backoff ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ### List Form N-PX annual proxy voting record filings - **Method:** `GET` - **Path:** `/api/v1/proxy-votes` - **Tags:** Proxy Votes List Form N-PX filings — annual proxy voting records from registered investment companies and certain institutional investment managers. **Examples:** - All filings for a manager: `?cik=1067983` - Reports for 2024: `?report_calendar_year=2024` - Confidential filings only: `?confidential_treatment=true` #### Responses ##### Status: 200 Successful Response ###### Content-Type: application/json - **`data` (required)** `array` — Page of N-PX filing rows **Items:** - **`accession_num` (required)** `object` — EDGAR accession number derived from filing\_id (e.g., '0000320193-24-000123') - **`cik` (required)** `string` — Filer SEC Central Index Key - **`filing_id` (required)** `string` — Unique filing identifier - **`form_type` (required)** `string` — SEC form type (e.g., '4', '13F-HR', 'D') - **`source_url` (required)** `object` — Canonical SEC EDGAR Archives URL pointing at the filing's index page - **`accepted_time`** `object` — When SEC accepted the filing - **`amendment_no`** `object` — Amendment number for amendment filings - **`confidential_treatment`** `object` — True if filing requested confidential treatment - **`file_number`** `object` — Investment Company Act file number - **`filer_name`** `object` — Filer entity name - **`filer_tickers`** `object` — Ticker symbols associated with the filer - **`is_amendment`** `object` — True if this filing is an amendment - **`is_valid`** `object` — Whether the filing passed validation - **`period_of_report`** `object` — Reporting period end date - **`registrant_type`** `object` — Registrant type code (see query-param doc) - **`report_calendar_year`** `object` — Calendar year of the proxy-voting report - **`report_quarter_year`** `object` — Quarter / year designator (e.g., 'Q4 2024') - **`report_type`** `object` — N-PX report type code - **`reporting_person_name`** `object` — Reporting-person name (where the filing is made on behalf of someone) - **`submission_type`** `object` — EDGAR submission type - **`year_or_quarter`** `object` — Period type the filing covers ('annual' or quarterly tag) - **`page_size` (required)** `integer` — Results per page - **`page`** `integer`, default: `1` — Current page number (1-indexed) - **`total`** `integer`, default: `0` — Total count of matching rows - **`total_pages`** `integer`, default: `1` — Total number of pages **Example:** ```json { "total": 0, "page": 1, "page_size": 1, "total_pages": 1, "data": [ { "filing_id": "", "cik": "", "form_type": "", "period_of_report": "", "accepted_time": "", "is_valid": true, "filer_name": "", "filer_tickers": [ "" ], "submission_type": "", "year_or_quarter": "", "report_calendar_year": 1, "report_quarter_year": "", "report_type": "", "confidential_treatment": true, "is_amendment": true, "amendment_no": "", "registrant_type": "", "reporting_person_name": "", "file_number": "", "accession_num": "", "source_url": "" } ] } ``` ##### Status: 401 Authentication failed - missing or invalid API key ###### Content-Type: application/json - **`message`** `string` **Example:** ```json { "message": "Missing API key in request" } ``` ##### Status: 422 Request validation failed - invalid or missing parameters ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 429 Rate limit exceeded for your tier ###### Content-Type: application/json - **`message`** `string` **Example:** ```json { "message": "" } ``` ##### Status: 500 Unhandled server error — file an issue with the request\_id from the error envelope. ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 502 Upstream dependency failed — gateway, key store, or downstream service unavailable. ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 503 Database query error or timeout — retry with backoff ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ### List funds with N-PX data - **Method:** `GET` - **Path:** `/api/v1/proxy-votes/entities` - **Tags:** Proxy Votes Discovery endpoint — list distinct funds with Form N-PX proxy-voting filings on file. Returns one row per `filer_cik` with: - Fund identifiers (CIK, modal name, ticker symbols when present) - `filing_count` — total N-PX filings on file - `period_min` / `period_max` — earliest and latest period\_of\_report **Examples:** - All funds: `/proxy-votes/entities` - Search by name: `/proxy-votes/entities?search=vanguard` - Most-active funds first: `/proxy-votes/entities?sort=filing_count&order=desc` **See also:** `/api/v1/entities/{cik}` for the registry-level profile of any fund returned here. #### Responses ##### Status: 200 Successful Response ###### Content-Type: application/json - **`data` (required)** `array` — Page of funds with N-PX data on file. **Items:** - **`cik` (required)** `string` — Required. Reporting fund SEC Central Index Key (canonical short form, no leading zeros). - **`filing_count` (required)** `integer` — Required. Total Form N-PX filings on file for this fund. - **`company_name`** `object` — Optional. Modal filer name across the fund's N-PX filings. - **`period_max`** `object` — Optional. Latest period\_of\_report observed for this fund. - **`period_min`** `object` — Optional. Earliest period\_of\_report observed for this fund. - **`tickers`** `object` — Optional. Filer ticker symbols sampled from one filing's \`filer\_tickers\`. - **`page_size` (required)** `integer` — Results per page - **`page`** `integer`, default: `1` — Current page number (1-indexed) - **`total`** `integer`, default: `0` — Total count of matching rows - **`total_pages`** `integer`, default: `1` — Total number of pages **Example:** ```json { "total": 0, "page": 1, "page_size": 1, "total_pages": 1, "data": [ { "cik": "", "company_name": "", "tickers": [ "" ], "filing_count": 1, "period_min": "", "period_max": "" } ] } ``` ##### Status: 401 Authentication failed - missing or invalid API key ###### Content-Type: application/json - **`message`** `string` **Example:** ```json { "message": "Missing API key in request" } ``` ##### Status: 422 Request validation failed - invalid or missing parameters ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 429 Rate limit exceeded for your tier ###### Content-Type: application/json - **`message`** `string` **Example:** ```json { "message": "" } ``` ##### Status: 500 Unhandled server error — file an issue with the request\_id from the error envelope. ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 502 Upstream dependency failed — gateway, key store, or downstream service unavailable. ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 503 Database query error or timeout — retry with backoff ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ### Get a Form N-PX proxy voting record - **Method:** `GET` - **Path:** `/api/v1/proxy-votes/{filing_id}` - **Tags:** Proxy Votes #### Responses ##### Status: 200 Successful Response ###### Content-Type: application/json - **`accession_num` (required)** `object` — EDGAR accession number derived from filing\_id (e.g., '0000320193-24-000123') - **`cik` (required)** `string` — Filer SEC Central Index Key - **`filing_id` (required)** `string` — Unique filing identifier - **`form_type` (required)** `string` — SEC form type (e.g., '4', '13F-HR', 'D') - **`source_url` (required)** `object` — Canonical SEC EDGAR Archives URL pointing at the filing's index page - **`accepted_time`** `object` — When SEC accepted the filing - **`amendment_no`** `object` — Amendment number for amendment filings - **`amendment_type`** `object` — Type of amendment for amendment filings - **`confidential_treatment`** `object` — True if filing requested confidential treatment - **`file_number`** `object` — Investment Company Act file number - **`filer_name`** `object` — Filer entity name - **`filer_tickers`** `object` — Ticker symbols associated with the filer - **`form_data`** `object` — Full N-PX form\_data JSON (omit by passing include\_form\_data=false on the request) - **`is_amendment`** `object` — True if this filing is an amendment - **`is_valid`** `object` — Whether the filing passed validation - **`period_of_report`** `object` — Reporting period end date - **`registrant_type`** `object` — Registrant type code (see query-param doc) - **`report_calendar_year`** `object` — Calendar year of the proxy-voting report - **`report_quarter_year`** `object` — Quarter / year designator (e.g., 'Q4 2024') - **`report_type`** `object` — N-PX report type code - **`reporting_crd_number`** `object` — FINRA CRD number of the reporting entity - **`reporting_person_name`** `object` — Reporting-person name (where the filing is made on behalf of someone) - **`reporting_sec_file_number`** `object` — SEC file number of the reporting entity (e.g., '801-12345' for advisers) - **`submission_type`** `object` — EDGAR submission type - **`votes`** `array` — All vote records reported on this filing **Items:** - **`record_index` (required)** `integer` — Per-filing 0-based ordinal of this vote row - **`cusip`** `object` — 9-character CUSIP of the security being voted - **`isin`** `object` — 12-character ISIN of the security being voted - **`issuer_name`** `object` — Issuer name (the company holding the meeting) - **`meeting_date`** `object` — Date of the shareholder meeting - **`shares_on_loan`** `object` — Shares of this security on loan (and therefore not available to vote) - **`shares_voted`** `object` — Number of shares the reporting fund voted - **`vote_categories`** `object` — Structured vote-category tags assigned to this proposal - **`vote_description`** `object` — Description of the proposal being voted on - **`vote_records`** `object` — Per-fund vote records (one filing may report votes for multiple funds) - **`vote_source`** `object` — Source of the vote decision (e.g., 'M' management recommendation, 'S' shareholder, 'B' both) - **`year_or_quarter`** `object` — Period type the filing covers ('annual' or quarterly tag) **Example:** ```json { "filing_id": "", "cik": "", "form_type": "", "period_of_report": "", "accepted_time": "", "is_valid": true, "filer_name": "", "filer_tickers": [ "" ], "submission_type": "", "year_or_quarter": "", "report_calendar_year": 1, "report_quarter_year": "", "report_type": "", "confidential_treatment": true, "is_amendment": true, "amendment_no": "", "registrant_type": "", "reporting_person_name": "", "file_number": "", "amendment_type": "", "reporting_crd_number": "", "reporting_sec_file_number": "", "form_data": null, "votes": [ { "record_index": 1, "meeting_date": "", "issuer_name": "", "cusip": "", "isin": "", "vote_description": "", "shares_voted": "", "shares_on_loan": "", "vote_source": "", "vote_categories": null, "vote_records": null } ], "accession_num": "", "source_url": "" } ``` ##### Status: 401 Authentication failed - missing or invalid API key ###### Content-Type: application/json - **`message`** `string` **Example:** ```json { "message": "Missing API key in request" } ``` ##### Status: 404 Resource not found ###### Content-Type: application/json - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } ``` ##### Status: 422 Request validation failed - invalid or missing parameters ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 429 Rate limit exceeded for your tier ###### Content-Type: application/json - **`message`** `string` **Example:** ```json { "message": "" } ``` ##### Status: 500 Unhandled server error — file an issue with the request\_id from the error envelope. ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 502 Upstream dependency failed — gateway, key store, or downstream service unavailable. ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 503 Database query error or timeout — retry with backoff ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ### List Form 1-A Regulation A+ offerings - **Method:** `GET` - **Path:** `/api/v1/reg-a-offerings` - **Tags:** Reg A+ Offerings List Reg A+ filings (Form 1-A, 1-K, 1-U, 1-Z) — small-company public offerings exempt from full SEC registration. **Examples:** - All Tier 2 offerings: `?tier=Tier 2` - Filings by industry: `?issuer_industry_group=Technology` - Big offerings: `?min_aggregate_offering=20000000` #### Responses ##### Status: 200 Successful Response ###### Content-Type: application/json - **`data` (required)** `array` — Page of Reg A+ filing rows **Items:** - **`accession_num` (required)** `object` — EDGAR accession number derived from filing\_id (e.g., '0000320193-24-000123') - **`cik` (required)** `string` — Filer SEC Central Index Key - **`filing_id` (required)** `string` — Unique filing identifier - **`form_type` (required)** `string` — SEC form type (e.g., '4', '13F-HR', 'D') - **`source_url` (required)** `object` — Canonical SEC EDGAR Archives URL pointing at the filing's index page - **`accepted_time`** `object` — When SEC accepted the filing - **`audit_status`** `object` — Audit status of the issuer's financial statements - **`estimated_net_amount`** `object` — Estimated net amount to issuer after fees (USD) - **`filer_name`** `object` — Filer entity name - **`filer_tickers`** `object` — Ticker symbols associated with the filer - **`is_valid`** `object` — Whether the filing passed validation - **`issuer_industry_group`** `object` — Issuer industry group classification - **`issuer_name`** `object` — Issuer legal name - **`jurisdiction_of_organization`** `object` — Issuer state or country of organization - **`net_income`** `object` — Issuer net income for the reporting period (USD) - **`offering_file_number`** `object` — Reg A+ offering file number (e.g., '024-12345') - **`period_of_report`** `object` — Reporting period end date - **`sic_code`** `object` — Issuer Standard Industrial Classification code - **`submission_type`** `object` — EDGAR submission type - **`tier`** `object` — Reg A+ tier ('Tier 1' or 'Tier 2'); see query-param doc - **`total_aggregate_offering`** `object` — Total aggregate offering amount (USD) - **`total_assets`** `object` — Issuer total assets at period end (USD) - **`total_revenues`** `object` — Issuer total revenues for the reporting period (USD) - **`year_of_incorporation`** `object` — Year the issuer was incorporated / organized - **`page_size` (required)** `integer` — Results per page - **`page`** `integer`, default: `1` — Current page number (1-indexed) - **`total`** `integer`, default: `0` — Total count of matching rows - **`total_pages`** `integer`, default: `1` — Total number of pages **Example:** ```json { "total": 0, "page": 1, "page_size": 1, "total_pages": 1, "data": [ { "filing_id": "", "cik": "", "form_type": "", "period_of_report": "", "accepted_time": "", "is_valid": true, "filer_name": "", "filer_tickers": [ "" ], "submission_type": "", "offering_file_number": "", "issuer_name": "", "jurisdiction_of_organization": "", "year_of_incorporation": 1, "sic_code": "", "issuer_industry_group": "", "tier": "", "audit_status": "", "total_aggregate_offering": "", "estimated_net_amount": "", "total_assets": "", "total_revenues": "", "net_income": "", "accession_num": "", "source_url": "" } ] } ``` ##### Status: 401 Authentication failed - missing or invalid API key ###### Content-Type: application/json - **`message`** `string` **Example:** ```json { "message": "Missing API key in request" } ``` ##### Status: 422 Request validation failed - invalid or missing parameters ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 429 Rate limit exceeded for your tier ###### Content-Type: application/json - **`message`** `string` **Example:** ```json { "message": "" } ``` ##### Status: 500 Unhandled server error — file an issue with the request\_id from the error envelope. ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 502 Upstream dependency failed — gateway, key store, or downstream service unavailable. ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 503 Database query error or timeout — retry with backoff ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ### List issuers with Reg A+ offering data - **Method:** `GET` - **Path:** `/api/v1/reg-a-offerings/entities` - **Tags:** Reg A+ Offerings Discovery endpoint — list distinct issuers with Form 1-A (Regulation A+) offerings on file. Form 1-A is filed by the issuer itself, so each row groups by `cik` with: - Issuer identifiers (CIK, modal name, ticker symbols when present) - `filing_count` — total Form 1-A filings on file - `period_min` / `period_max` — earliest and latest period\_of\_report **Examples:** - All issuers: `/reg-a-offerings/entities` - Search by name: `/reg-a-offerings/entities?search=acme` - Most-active issuers first: `/reg-a-offerings/entities?sort=filing_count&order=desc` **See also:** `/api/v1/entities/{cik}` for the registry-level profile of any issuer returned here. #### Responses ##### Status: 200 Successful Response ###### Content-Type: application/json - **`data` (required)** `array` — Page of issuers with Form 1-A data on file. **Items:** - **`cik` (required)** `string` — Required. Issuer SEC Central Index Key (canonical short form, no leading zeros). - **`filing_count` (required)** `integer` — Required. Total Form 1-A filings on file for this issuer. - **`company_name`** `object` — Optional. Modal issuer name across the issuer's Form 1-A filings. - **`period_max`** `object` — Optional. Latest period\_of\_report observed for this issuer. - **`period_min`** `object` — Optional. Earliest period\_of\_report observed for this issuer. - **`tickers`** `object` — Optional. Issuer ticker symbols sampled from one filing's \`filer\_tickers\`. - **`page_size` (required)** `integer` — Results per page - **`page`** `integer`, default: `1` — Current page number (1-indexed) - **`total`** `integer`, default: `0` — Total count of matching rows - **`total_pages`** `integer`, default: `1` — Total number of pages **Example:** ```json { "total": 0, "page": 1, "page_size": 1, "total_pages": 1, "data": [ { "cik": "", "company_name": "", "tickers": [ "" ], "filing_count": 1, "period_min": "", "period_max": "" } ] } ``` ##### Status: 401 Authentication failed - missing or invalid API key ###### Content-Type: application/json - **`message`** `string` **Example:** ```json { "message": "Missing API key in request" } ``` ##### Status: 422 Request validation failed - invalid or missing parameters ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 429 Rate limit exceeded for your tier ###### Content-Type: application/json - **`message`** `string` **Example:** ```json { "message": "" } ``` ##### Status: 500 Unhandled server error — file an issue with the request\_id from the error envelope. ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 502 Upstream dependency failed — gateway, key store, or downstream service unavailable. ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 503 Database query error or timeout — retry with backoff ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ### Get a Regulation A+ offering filing - **Method:** `GET` - **Path:** `/api/v1/reg-a-offerings/{filing_id}` - **Tags:** Reg A+ Offerings #### Responses ##### Status: 200 Successful Response ###### Content-Type: application/json - **`accession_num` (required)** `object` — EDGAR accession number derived from filing\_id (e.g., '0000320193-24-000123') - **`cik` (required)** `string` — Filer SEC Central Index Key - **`filing_id` (required)** `string` — Unique filing identifier - **`form_type` (required)** `string` — SEC form type (e.g., '4', '13F-HR', 'D') - **`source_url` (required)** `object` — Canonical SEC EDGAR Archives URL pointing at the filing's index page - **`accepted_time`** `object` — When SEC accepted the filing - **`accounts_payable`** `object` — Accounts payable (USD) - **`accounts_receivable`** `object` — Accounts receivable (USD) - **`audit_status`** `object` — Audit status of the issuer's financial statements - **`auditor_fees`** `object` — Auditor fees (USD) - **`auditor_name`** `object` — Auditor name (offering-related) - **`bad_actor`** `object` — True if any 'bad-actor' disqualification disclosed - **`blue_sky_fees`** `object` — Blue-sky compliance fees (USD) - **`blue_sky_name`** `object` — Blue-sky compliance counsel name - **`cash_equivalents`** `object` — Cash and cash equivalents (USD) - **`concurrent_offering_aggregate`** `object` — Aggregate of concurrent offerings (USD) - **`cost_and_expenses_appl_to_revenues`** `object` — Cost and expenses applicable to revenues (USD) - **`deposits`** `object` — Deposits (USD) - **`depreciation_and_amortization`** `object` — Depreciation and amortization (USD) - **`earnings_per_share_basic`** `object` — Basic earnings per share (USD) - **`earnings_per_share_diluted`** `object` — Diluted earnings per share (USD) - **`equity_classes`** `array` — All equity-class rows for this filing **Items:** - **`record_index` (required)** `integer` — Per-filing 0-based ordinal of this class row - **`class_name`** `object` — Class name (e.g., 'Class A Common Stock') - **`cusip`** `object` — CUSIP of the class (where assigned) - **`equity_type`** `object` — Equity type (e.g., 'Common Equity', 'Preferred Equity') - **`outstanding`** `object` — Shares outstanding for this class - **`publicly_traded`** `object` — Public-trading designation (e.g., 'Yes' / 'No' / exchange name) - **`estimated_net_amount`** `object` — Estimated net amount to issuer after fees (USD) - **`filer_name`** `object` — Filer entity name - **`filer_tickers`** `object` — Ticker symbols associated with the filer - **`finders_fees_fees`** `object` — Finder fees (USD) - **`finders_fees_name`** `object` — Finder name - **`full_time_employees`** `object` — Issuer full-time employee count - **`investment_securities`** `object` — Investment securities (USD) - **`irs_num`** `object` — Issuer IRS Employer Identification Number (EIN) - **`is_valid`** `object` — Whether the filing passed validation - **`issuer_aggregate_offering`** `object` — Aggregate offering amount by issuer (USD) - **`issuer_auditor_name`** `object` — Name of issuer's external auditor - **`issuer_city`** `object` — Issuer city - **`issuer_contact_name`** `object` — Issuer contact person name - **`issuer_eligible`** `object` — True if issuer is eligible to use Regulation A+ - **`issuer_industry_group`** `object` — Issuer industry group classification - **`issuer_name`** `object` — Issuer legal name - **`issuer_phone_number`** `object` — Issuer contact phone number - **`issuer_state_or_country`** `object` — Issuer state code or country - **`issuer_street1`** `object` — Issuer street address line 1 - **`issuer_zip_code`** `object` — Issuer postal code - **`jurisdiction_of_organization`** `object` — Issuer state or country of organization - **`jurisdictions_dealers`** `object` — List of state / territory codes where dealers are located - **`jurisdictions_none`** `object` — True if offering is not made in any specific jurisdiction - **`jurisdictions_offered`** `object` — List of state / territory codes where the offering is made - **`jurisdictions_same_as_offering`** `object` — True if dealer jurisdictions are the same as offering jurisdictions - **`legal_fees`** `object` — Legal fees (USD) - **`legal_name`** `object` — Legal counsel name - **`loans_net`** `object` — Loans, net of allowance (USD) - **`long_term_debt`** `object` — Long-term debt (USD) - **`net_income`** `object` — Issuer net income for the reporting period (USD) - **`not_disqualified`** `object` — True if issuer is not disqualified under Rule 262 - **`offer_delayed_continuous`** `object` — True if offering is on a delayed or continuous basis - **`offering_after_qualification`** `object` — True if offering will commence after qualification - **`offering_best_efforts`** `object` — True if offering is on a best-efforts basis - **`offering_file_number`** `object` — Reg A+ offering file number (e.g., '024-12345') - **`offering_year`** `object` — True if offering will be made within one year - **`outstanding_securities`** `object` — Outstanding securities of this class - **`part_time_employees`** `object` — Issuer part-time employee count - **`period_of_report`** `object` — Reporting period end date - **`policy_liabilities_and_accruals`** `object` — Insurance policy liabilities and accruals (USD) - **`price_per_security`** `object` — Price per security (USD) - **`promoters_fees`** `object` — Promoter fees (USD) - **`promoters_name`** `object` — Promoter name - **`property_and_equipment`** `object` — Property and equipment (alternate label, USD) - **`property_plant_equipment`** `object` — Property, plant, and equipment (USD) - **`qualification_offering_aggregate`** `object` — Aggregate offering amount qualified to date (USD) - **`resale_affiliates`** `object` — True if offering includes resales by affiliates of the issuer - **`sales_commissions_fees`** `object` — Sales-commission fees (USD) - **`sales_commissions_name`** `object` — Name of party receiving sales commissions - **`securities_offered`** `object` — Number of securities offered - **`securities_offered_types`** `object` — List of security types offered (e.g., \['Equity', 'Debt', 'Other']) - **`security_holder_aggregate`** `object` — Aggregate offering amount by selling security holders (USD) - **`sic_code`** `object` — Issuer Standard Industrial Classification code - **`solicitation`** `object` — True if testing-the-waters / general solicitation occurred - **`submission_type`** `object` — EDGAR submission type - **`tier`** `object` — Reg A+ tier ('Tier 1' or 'Tier 2'); see query-param doc - **`total_aggregate_offering`** `object` — Total aggregate offering amount (USD) - **`total_assets`** `object` — Issuer total assets at period end (USD) - **`total_interest_expenses`** `object` — Total interest expense (USD) - **`total_interest_income`** `object` — Total interest income (USD) - **`total_investments`** `object` — Total investments (USD) - **`total_liabilities`** `object` — Total liabilities (USD) - **`total_liabilities_and_equity`** `object` — Total liabilities and stockholders' equity (USD) - **`total_revenues`** `object` — Issuer total revenues for the reporting period (USD) - **`total_stockholder_equity`** `object` — Total stockholders' equity (USD) - **`underwriters_fees`** `object` — Underwriter fees (USD) - **`underwriters_name`** `object` — Underwriter name (where applicable) - **`unregistered_act_exemption`** `object` — Securities Act exemption claimed for unregistered sales (e.g., 'Section 4(a)(2)', 'Rule 506') - **`unregistered_none`** `object` — True if no unregistered securities sold in the past year - **`unregistered_securities`** `array` — All unregistered-security rows for this filing (Item 6 disclosures) **Items:** - **`record_index` (required)** `integer` — Per-filing 0-based ordinal of this row - **`aggregate_amount`** `object` — Aggregate amount as reported (free-text; may include narrative) - **`issuer_name`** `object` — Name of the issuer of the unregistered securities - **`principal_holder_amount`** `object` — Amount sold to principal holders - **`title`** `object` — Security title (e.g., 'Series A Preferred Stock') - **`total_amount`** `object` — Total amount of unregistered securities sold - **`year_of_incorporation`** `object` — Year the issuer was incorporated / organized **Example:** ```json { "filing_id": "", "cik": "", "form_type": "", "period_of_report": "", "accepted_time": "", "is_valid": true, "filer_name": "", "filer_tickers": [ "" ], "submission_type": "", "offering_file_number": "", "issuer_name": "", "jurisdiction_of_organization": "", "year_of_incorporation": 1, "sic_code": "", "issuer_industry_group": "", "tier": "", "audit_status": "", "total_aggregate_offering": "", "estimated_net_amount": "", "total_assets": "", "total_revenues": "", "net_income": "", "irs_num": "", "full_time_employees": 1, "part_time_employees": 1, "issuer_street1": "", "issuer_city": "", "issuer_state_or_country": "", "issuer_zip_code": "", "issuer_phone_number": "", "issuer_contact_name": "", "issuer_auditor_name": "", "cash_equivalents": "", "investment_securities": "", "total_investments": "", "accounts_receivable": "", "loans_net": "", "property_plant_equipment": "", "property_and_equipment": "", "accounts_payable": "", "policy_liabilities_and_accruals": "", "deposits": "", "long_term_debt": "", "total_liabilities": "", "total_stockholder_equity": "", "total_liabilities_and_equity": "", "total_interest_income": "", "total_interest_expenses": "", "cost_and_expenses_appl_to_revenues": "", "depreciation_and_amortization": "", "earnings_per_share_basic": "", "earnings_per_share_diluted": "", "issuer_eligible": true, "not_disqualified": true, "bad_actor": true, "securities_offered_types": null, "offer_delayed_continuous": true, "offering_year": true, "offering_after_qualification": true, "offering_best_efforts": true, "solicitation": true, "resale_affiliates": true, "securities_offered": "", "outstanding_securities": "", "price_per_security": "", "issuer_aggregate_offering": "", "security_holder_aggregate": "", "qualification_offering_aggregate": "", "concurrent_offering_aggregate": "", "sales_commissions_name": "", "sales_commissions_fees": "", "auditor_name": "", "auditor_fees": "", "legal_name": "", "legal_fees": "", "blue_sky_name": "", "blue_sky_fees": "", "underwriters_name": "", "underwriters_fees": "", "promoters_name": "", "promoters_fees": "", "finders_fees_name": "", "finders_fees_fees": "", "jurisdictions_none": true, "jurisdictions_same_as_offering": true, "jurisdictions_offered": null, "jurisdictions_dealers": null, "unregistered_none": true, "unregistered_act_exemption": "", "equity_classes": [ { "record_index": 1, "equity_type": "", "class_name": "", "outstanding": "", "cusip": "", "publicly_traded": "" } ], "unregistered_securities": [ { "record_index": 1, "issuer_name": "", "title": "", "total_amount": "", "principal_holder_amount": "", "aggregate_amount": "" } ], "accession_num": "", "source_url": "" } ``` ##### Status: 401 Authentication failed - missing or invalid API key ###### Content-Type: application/json - **`message`** `string` **Example:** ```json { "message": "Missing API key in request" } ``` ##### Status: 404 Resource not found ###### Content-Type: application/json - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } ``` ##### Status: 422 Request validation failed - invalid or missing parameters ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 429 Rate limit exceeded for your tier ###### Content-Type: application/json - **`message`** `string` **Example:** ```json { "message": "" } ``` ##### Status: 500 Unhandled server error — file an issue with the request\_id from the error envelope. ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 502 Upstream dependency failed — gateway, key store, or downstream service unavailable. ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 503 Database query error or timeout — retry with backoff ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ### List registration-statement prospectus filings - **Method:** `GET` - **Path:** `/api/v1/narratives` - **Tags:** Narratives List S-1 / S-3 / S-3ASR / S-4 / S-11 / F-1 / F-3 / F-4 filings (and their /A amendments) from the narrative pipeline. Each row is a prospectus filing — section content is fetched separately via `/narratives/sections?filing_id=...` or `/narratives/{filing_id}`. **Examples:** - All S-1 filings (original + amendments): `?form_type=S-1` or `?form_type=S-1/A` - Filings by an issuer: `?cik=320193` - Filings by ticker: `?ticker=AAPL` #### Responses ##### Status: 200 Successful Response ###### Content-Type: application/json - **`data` (required)** `array` — Page of registration-statement filing rows **Items:** - **`accession_num` (required)** `object` — EDGAR accession number derived from filing\_id (e.g., '0000320193-24-000123') - **`cik` (required)** `string` — Filer SEC Central Index Key - **`filing_id` (required)** `string` — Unique filing identifier - **`form_type` (required)** `string` — SEC form type (e.g., 'S-1', 'S-1/A', 'F-3') - **`source_url` (required)** `object` — Canonical SEC EDGAR Archives URL pointing at the filing's index page - **`accepted_time`** `object` — When the SEC accepted the filing - **`filer_name`** `object` — Filer entity name - **`filer_sic`** `object` — Filer Standard Industrial Classification (SIC) code (e.g., '7372' Prepackaged Software) - **`filer_tickers`** `object` — Ticker symbols associated with the filer - **`is_valid`** `object` — Whether the filing passed validation - **`period_of_report`** `object` — Reporting period end (datetime for prospectus filings) - **`section_count`** `object` — Total prospectus sections extracted from this filing - **`page_size` (required)** `integer` — Results per page - **`page`** `integer`, default: `1` — Current page number (1-indexed) - **`total`** `integer`, default: `0` — Total count of matching rows - **`total_pages`** `integer`, default: `1` — Total number of pages **Example:** ```json { "total": 0, "page": 1, "page_size": 1, "total_pages": 1, "data": [ { "filing_id": "", "cik": "", "form_type": "", "period_of_report": "", "accepted_time": "", "is_valid": true, "filer_name": "", "filer_tickers": [ "" ], "filer_sic": "", "section_count": 1, "accession_num": "", "source_url": "" } ] } ``` ##### Status: 401 Authentication failed - missing or invalid API key ###### Content-Type: application/json - **`message`** `string` **Example:** ```json { "message": "Missing API key in request" } ``` ##### Status: 422 Request validation failed - invalid or missing parameters ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 429 Rate limit exceeded for your tier ###### Content-Type: application/json - **`message`** `string` **Example:** ```json { "message": "" } ``` ##### Status: 500 Unhandled server error — file an issue with the request\_id from the error envelope. ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 502 Upstream dependency failed — gateway, key store, or downstream service unavailable. ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 503 Database query error or timeout — retry with backoff ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ### Cross-filing prospectus sections stream - **Method:** `GET` - **Path:** `/api/v1/narratives/sections` - **Tags:** Narratives Stream prospectus sections across many filings — Risk Factors, Use of Proceeds, Plan of Distribution, Business Description, MD\&A, etc. **Required:** at least one of `filing_id`, `cik`, `ticker`, `form_type`. Returns `400 MISSING_PARAMETER` otherwise. **Examples:** - All sections of one filing: `?filing_id=...` - All Risk Factors across S-1s: `?form_type=S-1§ion_title=Risk Factors` - Lightweight listing (titles + lengths, no body): `?form_type=S-1&include_text=false` Heavy JSON columns (`text_json`, `table_json`, `validated_json`) ship by default; toggle `include_text=false` for a metadata-only listing. #### Responses ##### Status: 200 Successful Response ###### Content-Type: application/json - **`data` (required)** `array` — Page of prospectus section rows **Items:** - **`filing_id` (required)** `string` — Filing this section belongs to - **`section_id` (required)** `string`, format: `uuid` — Unique section identifier (UUID v4) - **`accepted_time`** `object` — When the parent filing was accepted by the SEC - **`cik`** `object` — Filer CIK - **`filer_name`** `object` — Filer entity name - **`form_type`** `object` — SEC form type of the parent filing - **`is_valid`** `object` — Whether the parent filing passed validation - **`page_number`** `object` — Source page number(s) where this section appears in the filed PDF - **`period_of_report`** `object` — Reporting period of the parent filing - **`section_order`** `object` — 0-based ordinal of this section within the filing - **`section_title`** `object` — Section title as extracted from the prospectus (e.g., 'Risk Factors') - **`table_count`** `object` — Count of tables extracted from this section - **`table_json`** `object` — Structured tables extracted from the section (omitted when include\_text=false) - **`text_json`** `object` — Structured narrative text — paragraphs, lists, headings (omitted when include\_text=false) - **`text_length`** `object` — Total character length of the section's narrative text - **`validated_json`** `object` — Validated / normalized JSON extraction of the section's structured content - **`page_size` (required)** `integer` — Results per page - **`page`** `integer`, default: `1` — Current page number (1-indexed) - **`total`** `integer`, default: `0` — Total count of matching rows - **`total_pages`** `integer`, default: `1` — Total number of pages **Example:** ```json { "total": 0, "page": 1, "page_size": 1, "total_pages": 1, "data": [ { "section_id": "", "filing_id": "", "cik": "", "form_type": "", "accepted_time": "", "period_of_report": "", "is_valid": true, "filer_name": "", "section_title": "", "section_order": 1, "page_number": "", "text_length": 1, "table_count": 1, "text_json": null, "table_json": null, "validated_json": null } ] } ``` ##### Status: 400 Request rejected — usually a missing required parameter or an at-least-one-of constraint not satisfied. ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 401 Authentication failed - missing or invalid API key ###### Content-Type: application/json - **`message`** `string` **Example:** ```json { "message": "Missing API key in request" } ``` ##### Status: 422 Request validation failed - invalid or missing parameters ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 429 Rate limit exceeded for your tier ###### Content-Type: application/json - **`message`** `string` **Example:** ```json { "message": "" } ``` ##### Status: 500 Unhandled server error — file an issue with the request\_id from the error envelope. ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 502 Upstream dependency failed — gateway, key store, or downstream service unavailable. ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 503 Database query error or timeout — retry with backoff ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ### Get a single prospectus section by UUID - **Method:** `GET` - **Path:** `/api/v1/narratives/sections/{section_id}` - **Tags:** Narratives Returns a single section's full content — heavy JSON columns always populated. #### Responses ##### Status: 200 Successful Response ###### Content-Type: application/json - **`filing_id` (required)** `string` — Filing this section belongs to - **`section_id` (required)** `string`, format: `uuid` — Unique section identifier (UUID v4) - **`accepted_time`** `object` — When the parent filing was accepted by the SEC - **`cik`** `object` — Filer CIK - **`filer_name`** `object` — Filer entity name - **`form_type`** `object` — SEC form type of the parent filing - **`is_valid`** `object` — Whether the parent filing passed validation - **`page_number`** `object` — Source page number(s) where this section appears in the filed PDF - **`period_of_report`** `object` — Reporting period of the parent filing - **`section_order`** `object` — 0-based ordinal of this section within the filing - **`section_title`** `object` — Section title as extracted from the prospectus (e.g., 'Risk Factors') - **`table_count`** `object` — Count of tables extracted from this section - **`table_json`** `object` — Structured tables extracted from the section (omitted when include\_text=false) - **`text_json`** `object` — Structured narrative text — paragraphs, lists, headings (omitted when include\_text=false) - **`text_length`** `object` — Total character length of the section's narrative text - **`validated_json`** `object` — Validated / normalized JSON extraction of the section's structured content **Example:** ```json { "section_id": "", "filing_id": "", "cik": "", "form_type": "", "accepted_time": "", "period_of_report": "", "is_valid": true, "filer_name": "", "section_title": "", "section_order": 1, "page_number": "", "text_length": 1, "table_count": 1, "text_json": null, "table_json": null, "validated_json": null } ``` ##### Status: 401 Authentication failed - missing or invalid API key ###### Content-Type: application/json - **`message`** `string` **Example:** ```json { "message": "Missing API key in request" } ``` ##### Status: 404 Resource not found ###### Content-Type: application/json - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } ``` ##### Status: 422 Request validation failed - invalid or missing parameters ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 429 Rate limit exceeded for your tier ###### Content-Type: application/json - **`message`** `string` **Example:** ```json { "message": "" } ``` ##### Status: 500 Unhandled server error — file an issue with the request\_id from the error envelope. ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 502 Upstream dependency failed — gateway, key store, or downstream service unavailable. ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 503 Database query error or timeout — retry with backoff ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ### List issuers with registration-statement narrative data - **Method:** `GET` - **Path:** `/api/v1/narratives/entities` - **Tags:** Narratives Discovery endpoint — list distinct issuers with registration-statement filings (S-1 / S-3 / F-1 / etc.) on file. Each row groups by `cik` (registration statements are filed by the issuer itself) with: - Issuer identifiers (CIK, modal name, ticker symbols when present) - `filing_count` — total registration-statement filings on file - `period_min` / `period_max` — earliest and latest period\_of\_report **Examples:** - All issuers: `/narratives/entities` - Search by name: `/narratives/entities?search=apple` - Most-active issuers first: `/narratives/entities?sort=filing_count&order=desc` **See also:** `/api/v1/entities/{cik}` for the registry-level profile of any issuer returned here. #### Responses ##### Status: 200 Successful Response ###### Content-Type: application/json - **`data` (required)** `array` — Page of issuers with registration-statement narrative data on file. **Items:** - **`cik` (required)** `string` — Required. Issuer SEC Central Index Key (canonical short form, no leading zeros). - **`filing_count` (required)** `integer` — Required. Total registration-statement filings on file for this issuer. - **`company_name`** `object` — Optional. Modal issuer name across the issuer's narrative filings. - **`period_max`** `object` — Optional. Latest period\_of\_report observed for this issuer. - **`period_min`** `object` — Optional. Earliest period\_of\_report observed for this issuer. - **`tickers`** `object` — Optional. Issuer ticker symbols sampled from one filing's \`filer\_tickers\`. - **`page_size` (required)** `integer` — Results per page - **`page`** `integer`, default: `1` — Current page number (1-indexed) - **`total`** `integer`, default: `0` — Total count of matching rows - **`total_pages`** `integer`, default: `1` — Total number of pages **Example:** ```json { "total": 0, "page": 1, "page_size": 1, "total_pages": 1, "data": [ { "cik": "", "company_name": "", "tickers": [ "" ], "filing_count": 1, "period_min": "", "period_max": "" } ] } ``` ##### Status: 401 Authentication failed - missing or invalid API key ###### Content-Type: application/json - **`message`** `string` **Example:** ```json { "message": "Missing API key in request" } ``` ##### Status: 422 Request validation failed - invalid or missing parameters ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 429 Rate limit exceeded for your tier ###### Content-Type: application/json - **`message`** `string` **Example:** ```json { "message": "" } ``` ##### Status: 500 Unhandled server error — file an issue with the request\_id from the error envelope. ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 502 Upstream dependency failed — gateway, key store, or downstream service unavailable. ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 503 Database query error or timeout — retry with backoff ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ### Get a registration-statement filing - **Method:** `GET` - **Path:** `/api/v1/narratives/{filing_id}` - **Tags:** Narratives Returns the parent filing only. Sections are NOT bundled (S-1 filings can have 20-50 sections of multi-KB JSON each). Use the `sections_url` field to fetch them via `/narratives/sections?filing_id={filing_id}`. #### Responses ##### Status: 200 Successful Response ###### Content-Type: application/json - **`accession_num` (required)** `object` — EDGAR accession number derived from filing\_id (e.g., '0000320193-24-000123') - **`cik` (required)** `string` — Filer SEC Central Index Key - **`filing_id` (required)** `string` — Unique filing identifier - **`form_type` (required)** `string` — SEC form type (e.g., 'S-1', 'S-1/A', 'F-3') - **`source_url` (required)** `object` — Canonical SEC EDGAR Archives URL pointing at the filing's index page - **`accepted_time`** `object` — When the SEC accepted the filing - **`filer_name`** `object` — Filer entity name - **`filer_sic`** `object` — Filer Standard Industrial Classification (SIC) code (e.g., '7372' Prepackaged Software) - **`filer_tickers`** `object` — Ticker symbols associated with the filer - **`is_valid`** `object` — Whether the filing passed validation - **`period_of_report`** `object` — Reporting period end (datetime for prospectus filings) - **`section_count`** `object` — Total prospectus sections extracted from this filing - **`sections_url`** `object` — Link to /narratives/sections?filing\_id={filing\_id} for the per-filing section drill-down **Example:** ```json { "filing_id": "", "cik": "", "form_type": "", "period_of_report": "", "accepted_time": "", "is_valid": true, "filer_name": "", "filer_tickers": [ "" ], "filer_sic": "", "section_count": 1, "sections_url": "", "accession_num": "", "source_url": "" } ``` ##### Status: 401 Authentication failed - missing or invalid API key ###### Content-Type: application/json - **`message`** `string` **Example:** ```json { "message": "Missing API key in request" } ``` ##### Status: 404 Resource not found ###### Content-Type: application/json - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } ``` ##### Status: 422 Request validation failed - invalid or missing parameters ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 429 Rate limit exceeded for your tier ###### Content-Type: application/json - **`message`** `string` **Example:** ```json { "message": "" } ``` ##### Status: 500 Unhandled server error — file an issue with the request\_id from the error envelope. ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 502 Upstream dependency failed — gateway, key store, or downstream service unavailable. ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 503 Database query error or timeout — retry with backoff ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ### Detect insider buying clusters (≥N insiders / M-day windows) - **Method:** `GET` - **Path:** `/api/v1/signals/insider-clusters` - **Tags:** Insider Signals Stream Form 4 cluster events: ≥`min_insiders` distinct insiders making open-market purchases of one issuer within `window_days`. Defaults follow the academic convention (≥3 insiders / 5 days). Detection is greedy and non-overlapping per issuer; the highest-dollar clusters surface first. #### Responses ##### Status: 200 Successful Response ###### Content-Type: application/json - **`data` (required)** `array` — Page of cluster-buying events **Items:** - **`aggregate_dollars` (required)** `string` — Total USD value of insider transactions in the cluster - **`has_senior_member` (required)** `boolean` — True if at least one cluster member is a director, officer, or ≥10% owner - **`issuer_cik` (required)** `string` — Issuer (company) CIK - **`member_count` (required)** `integer` — Distinct insiders contributing to the cluster - **`members` (required)** `array` — Per-insider rollup **Items:** - **`aggregate_dollars` (required)** `string` — Total USD value of this insider's transactions in the cluster window - **`is_senior` (required)** `boolean` — True if the insider is a director, officer, or ≥10% owner - **`rpt_owner_cik` (required)** `string` — Reporting owner (insider) CIK - **`transaction_count` (required)** `integer` — Distinct transactions this insider made within the cluster window - **`rpt_owner_name`** `object` — Reporting owner name - **`window_end` (required)** `string`, format: `date` — Cluster window end (latest transaction date) - **`window_start` (required)** `string`, format: `date` — Cluster window start (earliest transaction date) - **`issuer_trading_symbol`** `object` — Issuer ticker symbol - **`page_size` (required)** `integer` — Results per page - **`page`** `integer`, default: `1` — Current page number (1-indexed) - **`total`** `integer`, default: `0` — Total count of matching rows - **`total_pages`** `integer`, default: `1` — Total number of pages **Example:** ```json { "total": 0, "page": 1, "page_size": 1, "total_pages": 1, "data": [ { "issuer_cik": "", "issuer_trading_symbol": "", "window_start": "", "window_end": "", "member_count": 1, "members": [], "aggregate_dollars": "", "has_senior_member": true } ] } ``` ##### Status: 401 Authentication failed - missing or invalid API key ###### Content-Type: application/json - **`message`** `string` **Example:** ```json { "message": "Missing API key in request" } ``` ##### Status: 422 Request validation failed - invalid or missing parameters ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 429 Rate limit exceeded for your tier ###### Content-Type: application/json - **`message`** `string` **Example:** ```json { "message": "" } ``` ##### Status: 500 Unhandled server error — file an issue with the request\_id from the error envelope. ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 502 Upstream dependency failed — gateway, key store, or downstream service unavailable. ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 503 Database query error or timeout — retry with backoff ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ### Classify an issuer's insider dispositions over a window - **Method:** `GET` - **Path:** `/api/v1/signals/insider-trade-classification` - **Tags:** Insider Signals Returns dollar rollups + percentages for one issuer's insider dispositions (Form 4 'D' transactions) over a window: - **discretionary** — open-market sales (S code) without 10b5-1 affiliation - **plan** — trades flagged with `aff10b5_one` - **tax** — tax withholding (F) or exercise-related (M) - **other** — anything else **Required:** at least one of `issuer_cik`, `issuer_ticker`. Returns `400 MISSING_PARAMETER` otherwise. `since` defaults to 90 days before `until`; `until` defaults to today. #### Responses ##### Status: 200 Successful Response ###### Content-Type: application/json - **`breakdown` (required)** `object` — Per-bucket dollar and percent rollup - **`dollar_total` (required)** `string` — Total USD value of dispositions in the window - **`since` (required)** `string`, format: `date` — Window start applied - **`transaction_count` (required)** `integer` — Total disposition transactions in the window - **`until` (required)** `string`, format: `date` — Window end applied - **`issuer_cik`** `object` — Issuer CIK - **`issuer_trading_symbol`** `object` — Issuer ticker symbol **Example:** ```json { "issuer_cik": "", "issuer_trading_symbol": "", "since": "", "until": "", "transaction_count": 1, "dollar_total": "", "breakdown": { "discretionary_dollars": "", "discretionary_pct": 1, "plan_dollars": "", "plan_pct": 1, "tax_dollars": "", "tax_pct": 1, "other_dollars": "", "other_pct": 1 } } ``` ##### Status: 401 Authentication failed - missing or invalid API key ###### Content-Type: application/json - **`message`** `string` **Example:** ```json { "message": "Missing API key in request" } ``` ##### Status: 422 Request validation failed - invalid or missing parameters ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 429 Rate limit exceeded for your tier ###### Content-Type: application/json - **`message`** `string` **Example:** ```json { "message": "" } ``` ##### Status: 500 Unhandled server error — file an issue with the request\_id from the error envelope. ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 502 Upstream dependency failed — gateway, key store, or downstream service unavailable. ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 503 Database query error or timeout — retry with backoff ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ### Top issuers by discretionary-disposition activity - **Method:** `GET` - **Path:** `/api/v1/signals/insider-trade-classification/leaders` - **Tags:** Insider Signals Cross-issuer pivot of the insider-trade classifier — ranks issuers by either absolute discretionary disposition dollars or by discretionary share-of-disposition. **Examples:** - Top discretionary sellers in absolute USD: `?rank_by=discretionary_dollars` - Top discretionary-share names (high % of disposals are open-market sells): `?rank_by=discretionary_pct&min_dollars=100000` `min_dollars` filters out issuers whose total disposition activity in the window is too small to interpret a percentage. #### Responses ##### Status: 200 Successful Response ###### Content-Type: application/json - **`data` (required)** `array` — Issuers ranked by the chosen \`rank\_by\` metric, descending. **Items:** - **`cik` (required)** `string` — Issuer SEC Central Index Key (short form). - **`discretionary_dollars` (required)** `string` — Discretionary disposed-share value (USD) — code 'S' AND aff10b5\_one=false. - **`discretionary_pct` (required)** `number` — discretionary\_dollars / sum(all classes), clamped to \[0, 1]. - **`other_dollars` (required)** `string` — Other disposed-share value (USD) — neither discretionary, plan, nor tax. - **`plan_dollars` (required)** `string` — Plan-driven disposed-share value (USD) — aff10b5\_one=true. - **`rank` (required)** `integer` — 1-indexed rank in this leaderboard. - **`tax_dollars` (required)** `string` — Tax-related disposed-share value (USD) — codes F, M. - **`transaction_count` (required)** `integer` — Total disposition transactions counted in the window. - **`company_name`** `object` — Modal issuer name across the window's filings. - **`tickers`** `object` — Issuer ticker symbols when known. - **`rank_by` (required)** `string`, possible values: `"discretionary_dollars", "discretionary_pct"` — Whether the leaderboard ranks by absolute USD or by ratio. - **`window` (required)** `object` — Window the leaderboard ranks over. - **`lookback_days` (required)** `integer` — Window length in days (until - since). - **`since` (required)** `string`, format: `date` — Window start (inclusive). - **`until` (required)** `string`, format: `date` — Window end (inclusive). **Example:** ```json { "window": { "since": "", "until": "", "lookback_days": 1 }, "rank_by": "discretionary_dollars", "data": [ { "rank": 1, "cik": "", "company_name": "", "tickers": [ "" ], "discretionary_dollars": "", "plan_dollars": "", "tax_dollars": "", "other_dollars": "", "discretionary_pct": 1, "transaction_count": 1 } ] } ``` ##### Status: 401 Authentication failed - missing or invalid API key ###### Content-Type: application/json - **`message`** `string` **Example:** ```json { "message": "Missing API key in request" } ``` ##### Status: 422 Request validation failed - invalid or missing parameters ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 429 Rate limit exceeded for your tier ###### Content-Type: application/json - **`message`** `string` **Example:** ```json { "message": "" } ``` ##### Status: 500 Unhandled server error — file an issue with the request\_id from the error envelope. ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 502 Upstream dependency failed — gateway, key store, or downstream service unavailable. ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 503 Database query error or timeout — retry with backoff ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ### Top-N issuers by insider conviction score - **Method:** `GET` - **Path:** `/api/v1/signals/insider-conviction/leaders` - **Tags:** Insider Signals Cross-sectional ranking of issuers by composite insider-conviction score over a trailing window. Issuers with fewer than 3 distinct contributing insiders are excluded. Set `direction=bearish` to surface the lowest-scoring issuers (insiders selling at scale). #### Responses ##### Status: 200 Successful Response ###### Content-Type: application/json - **`as_of` (required)** `string`, format: `date` — Anchor date used - **`direction` (required)** `string` — Ranking direction (bullish or bearish) - **`results` (required)** `array` — Top-N issuer scores **Items:** - **`as_of` (required)** `string`, format: `date` — Anchor date for the trailing window - **`components` (required)** `object` — Component breakdown - **`distinct_insiders` (required)** `integer` — Distinct insiders contributing transactions in the window - **`score` (required)** `number` — Composite conviction score in \[-1, 1]; positive = bullish insider activity, negative = bearish - **`total_dollars` (required)** `string` — Total USD value of insider activity in the window - **`window_days` (required)** `integer` — Window length in days - **`issuer_cik`** `object` — Issuer CIK - **`issuer_trading_symbol`** `object` — Issuer ticker symbol - **`window_days` (required)** `integer` — Trailing window applied **Example:** ```json { "as_of": "", "window_days": 1, "direction": "", "results": [ { "as_of": "2024-04-01", "components": { "breadth": 0.38, "dollar_imbalance": 0.65, "seniority_weight": 0.55 }, "distinct_insiders": 7, "issuer_cik": "0000320193", "issuer_trading_symbol": "AAPL", "score": 0.42, "total_dollars": "8420000.00", "window_days": 90 } ] } ``` ##### Status: 401 Authentication failed - missing or invalid API key ###### Content-Type: application/json - **`message`** `string` **Example:** ```json { "message": "Missing API key in request" } ``` ##### Status: 422 Request validation failed - invalid or missing parameters ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 429 Rate limit exceeded for your tier ###### Content-Type: application/json - **`message`** `string` **Example:** ```json { "message": "" } ``` ##### Status: 500 Unhandled server error — file an issue with the request\_id from the error envelope. ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 502 Upstream dependency failed — gateway, key store, or downstream service unavailable. ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 503 Database query error or timeout — retry with backoff ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ### Composite insider conviction score for one issuer - **Method:** `GET` - **Path:** `/api/v1/signals/insider-conviction` - **Tags:** Insider Signals Returns a single composite score in \[-1, 1] for one issuer over a trailing window. **Required:** at least one of `issuer_cik` or `issuer_ticker`. Returns `400 MISSING_PARAMETER` otherwise. The score combines three components: - **dollar\_imbalance**: (acquired − disposed) / total, in \[-1, 1] - **breadth**: distinct contributing insiders, sigmoid-normalized - **seniority\_weight**: mean per-insider seniority (director / officer / 10% owner) A positive score indicates net insider accumulation; a negative score indicates net distribution. Magnitude reflects breadth × seniority amplification. #### Responses ##### Status: 200 Successful Response ###### Content-Type: application/json - **`as_of` (required)** `string`, format: `date` — Anchor date for the trailing window - **`components` (required)** `object` — Component breakdown - **`distinct_insiders` (required)** `integer` — Distinct insiders contributing transactions in the window - **`score` (required)** `number` — Composite conviction score in \[-1, 1]; positive = bullish insider activity, negative = bearish - **`total_dollars` (required)** `string` — Total USD value of insider activity in the window - **`window_days` (required)** `integer` — Window length in days - **`issuer_cik`** `object` — Issuer CIK - **`issuer_trading_symbol`** `object` — Issuer ticker symbol **Example:** ```json { "as_of": "2024-04-01", "components": { "breadth": 0.38, "dollar_imbalance": 0.65, "seniority_weight": 0.55 }, "distinct_insiders": 7, "issuer_cik": "0000320193", "issuer_trading_symbol": "AAPL", "score": 0.42, "total_dollars": "8420000.00", "window_days": 90 } ``` ##### Status: 401 Authentication failed - missing or invalid API key ###### Content-Type: application/json - **`message`** `string` **Example:** ```json { "message": "Missing API key in request" } ``` ##### Status: 422 Request validation failed - invalid or missing parameters ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 429 Rate limit exceeded for your tier ###### Content-Type: application/json - **`message`** `string` **Example:** ```json { "message": "" } ``` ##### Status: 500 Unhandled server error — file an issue with the request\_id from the error envelope. ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 502 Upstream dependency failed — gateway, key store, or downstream service unavailable. ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 503 Database query error or timeout — retry with backoff ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ### Amendment-resolved 13F holdings for one (manager, period) - **Method:** `GET` - **Path:** `/api/v1/signals/13f-positions` - **Tags:** 13F Analytics Returns the canonical post-amendment-resolution holdings for one (filing\_manager\_cik, period\_of\_report). Walks RESTATEMENT and NEW HOLDINGS amendment chains so the returned position list reflects positions as currently understood — including positions released from confidential treatment after the original filing. `amendment_chain` lists the filing\_ids walked, oldest first. #### Responses ##### Status: 200 Successful Response ###### Content-Type: application/json - **`aggregate_value` (required)** `string` — Total portfolio value across all positions (thousands of USD) - **`amendment_chain` (required)** `array` — filing\_ids walked in chronological order (original first, amendments after). Empty list means no filings found for the (manager, period). **Items:** `string` - **`data` (required)** `array` — Canonical envelope alias of \`positions\`. Prefer this key for new code — \`positions\` is retained for backward compatibility and slated for removal in a future release. **Items:** - **`cusip`** `object` — Security CUSIP - **`figi`** `object` — OpenFIGI identifier (12 chars) - **`investment_discretion`** `object` — 'SOLE', 'DFND' (defined), or 'OTR' (other shared) - **`name_of_issuer`** `object` — Issuer name - **`ssh_prnamt`** `object` — Number of shares or principal amount - **`ssh_prnamt_type`** `object` — Type of ssh\_prnamt: 'SH' = shares, 'PRN' = principal - **`title_of_class`** `object` — Title of class (e.g., 'COM', 'CL A') - **`value`** `object` — Position value (in thousands of USD per Form 13F) - **`voting_none`** `object` — Shares with no voting authority - **`voting_shared`** `object` — Shares with shared voting authority - **`voting_sole`** `object` — Shares with sole voting authority - **`filing_manager_cik` (required)** `string` — Filing manager CIK - **`period_of_report` (required)** `string`, format: `date` — 13F period - **`position_count` (required)** `integer` — Total positions after amendment resolution - **`positions` (required)** `array` — Amendment-resolved position rows **Items:** - **`cusip`** `object` — Security CUSIP - **`figi`** `object` — OpenFIGI identifier (12 chars) - **`investment_discretion`** `object` — 'SOLE', 'DFND' (defined), or 'OTR' (other shared) - **`name_of_issuer`** `object` — Issuer name - **`ssh_prnamt`** `object` — Number of shares or principal amount - **`ssh_prnamt_type`** `object` — Type of ssh\_prnamt: 'SH' = shares, 'PRN' = principal - **`title_of_class`** `object` — Title of class (e.g., 'COM', 'CL A') - **`value`** `object` — Position value (in thousands of USD per Form 13F) - **`voting_none`** `object` — Shares with no voting authority - **`voting_shared`** `object` — Shares with shared voting authority - **`voting_sole`** `object` — Shares with sole voting authority - **`summary` (required)** `object` — Endpoint-specific aggregates. Mirrors the top-level \`filing\_manager\_\*\`, \`period\_of\_report\`, \`position\_count\`, \`aggregate\_value\`, and \`amendment\_chain\` fields. - **`filing_manager_name`** `object` — Filing manager legal name **Example:** ```json { "filing_manager_cik": "", "filing_manager_name": "", "period_of_report": "", "amendment_chain": [ "" ], "position_count": 1, "aggregate_value": "", "positions": [ { "cusip": "", "figi": "", "name_of_issuer": "", "title_of_class": "", "value": "", "ssh_prnamt": "", "ssh_prnamt_type": "", "voting_sole": "", "voting_shared": "", "voting_none": "", "investment_discretion": "" } ], "data": [ { "cusip": "", "figi": "", "name_of_issuer": "", "title_of_class": "", "value": "", "ssh_prnamt": "", "ssh_prnamt_type": "", "voting_sole": "", "voting_shared": "", "voting_none": "", "investment_discretion": "" } ], "summary": {} } ``` ##### Status: 401 Authentication failed - missing or invalid API key ###### Content-Type: application/json - **`message`** `string` **Example:** ```json { "message": "Missing API key in request" } ``` ##### Status: 422 Request validation failed - invalid or missing parameters ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 429 Rate limit exceeded for your tier ###### Content-Type: application/json - **`message`** `string` **Example:** ```json { "message": "" } ``` ##### Status: 500 Unhandled server error — file an issue with the request\_id from the error envelope. ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 502 Upstream dependency failed — gateway, key store, or downstream service unavailable. ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 503 Database query error or timeout — retry with backoff ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ### Two-manager 13F portfolio overlap - **Method:** `GET` - **Path:** `/api/v1/signals/13f-positions/overlap` - **Tags:** 13F Analytics Compare two filing managers' amendment-resolved 13F portfolios at one period. Returns: - per-manager aggregate value + position counts - intersection: CUSIPs both managers hold - per-CUSIP value and share-of-portfolio for each manager - a Czekanowski / Bray-Curtis overlap score in \[0, 1] (sum of min-share-of-portfolio across overlapping CUSIPs) **Example:** - Berkshire vs Pershing Square at 2024-09-30: `?manager_a=1067983&manager_b=1336528&period=2024-09-30` #### Responses ##### Status: 200 Successful Response ###### Content-Type: application/json - **`manager_a_aggregate_value` (required)** `string` — Manager A's total portfolio value at the period (thousands of USD). - **`manager_a_cik` (required)** `string` — Manager A CIK (canonical short form). - **`manager_a_position_count` (required)** `integer` — Manager A's total position count at the period. - **`manager_b_aggregate_value` (required)** `string` — Manager B's total portfolio value at the period (thousands of USD). - **`manager_b_cik` (required)** `string` — Manager B CIK (canonical short form). - **`manager_b_position_count` (required)** `integer` — Manager B's total position count at the period. - **`overlap_position_count` (required)** `integer` — Number of CUSIPs both managers hold at the period. - **`overlap_score` (required)** `number` — Czekanowski / Bray-Curtis-style overlap: sum(min(share\_a, share\_b)) across overlapping positions, in \[0, 1]. 1.0 = identical portfolios; 0 = no overlap. - **`overlap_share_a` (required)** `number` — overlap\_value\_a / manager\_a\_aggregate\_value, in \[0, 1]. - **`overlap_share_b` (required)** `number` — overlap\_value\_b / manager\_b\_aggregate\_value, in \[0, 1]. - **`overlap_value_a` (required)** `string` — Value held by manager A in overlapping positions (thousands of USD). - **`overlap_value_b` (required)** `string` — Value held by manager B in overlapping positions (thousands of USD). - **`period_of_report` (required)** `string`, format: `date` — 13F period analyzed. - **`positions` (required)** `array` — Per-CUSIP overlap rows, sorted by min\_share\_of\_portfolio descending. **Items:** - **`manager_a_share_of_portfolio` (required)** `number` — manager\_a\_value / manager\_a\_aggregate\_value, in \[0, 1]. - **`manager_a_value` (required)** `string` — Position value held by manager A (thousands of USD). - **`manager_b_share_of_portfolio` (required)** `number` — manager\_b\_value / manager\_b\_aggregate\_value, in \[0, 1]. - **`manager_b_value` (required)** `string` — Position value held by manager B (thousands of USD). - **`min_share_of_portfolio` (required)** `number` — min(manager\_a\_share\_of\_portfolio, manager\_b\_share\_of\_portfolio) — the natural overlap weight (Czekanowski / Bray-Curtis denominator). - **`cusip`** `object` — Security CUSIP. - **`name_of_issuer`** `object` — Modal issuer name across the two managers' rows. - **`title_of_class`** `object` — Title of class (modal across the two managers' rows). - **`manager_a_name`** `object` — Manager A name (modal across their rows). - **`manager_b_name`** `object` — Manager B name (modal across their rows). **Example:** ```json { "period_of_report": "", "manager_a_cik": "", "manager_a_name": "", "manager_a_aggregate_value": "", "manager_a_position_count": 1, "manager_b_cik": "", "manager_b_name": "", "manager_b_aggregate_value": "", "manager_b_position_count": 1, "overlap_position_count": 1, "overlap_value_a": "", "overlap_value_b": "", "overlap_share_a": 1, "overlap_share_b": 1, "overlap_score": 1, "positions": [ { "cusip": "", "name_of_issuer": "", "title_of_class": "", "manager_a_value": "", "manager_b_value": "", "manager_a_share_of_portfolio": 1, "manager_b_share_of_portfolio": 1, "min_share_of_portfolio": 1 } ] } ``` ##### Status: 401 Authentication failed - missing or invalid API key ###### Content-Type: application/json - **`message`** `string` **Example:** ```json { "message": "Missing API key in request" } ``` ##### Status: 422 Request validation failed - invalid or missing parameters ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 429 Rate limit exceeded for your tier ###### Content-Type: application/json - **`message`** `string` **Example:** ```json { "message": "" } ``` ##### Status: 500 Unhandled server error — file an issue with the request\_id from the error envelope. ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 502 Upstream dependency failed — gateway, key store, or downstream service unavailable. ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 503 Database query error or timeout — retry with backoff ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ### Top-N securities by 13F holder concentration - **Method:** `GET` - **Path:** `/api/v1/signals/13f-crowding/leaders` - **Tags:** 13F Analytics Cross-security ranking at one period\_of\_report. Defaults to **most\_crowded** by distinct manager count, with a $100M minimum aggregate-value floor to keep the leaderboard from being dominated by illiquid names. `direction=rising` / `falling` adds a second query for prior-quarter holder counts and ranks by QoQ delta — slower but useful for identifying securities seeing fresh institutional interest or exits. #### Responses ##### Status: 200 Successful Response ###### Content-Type: application/json - **`direction` (required)** `string` — Ranking direction applied (see query-param doc) - **`period_of_report` (required)** `string`, format: `date` — 13F period ranked - **`results` (required)** `array` — Top-N results **Items:** - **`aggregate_shares` (required)** `string` — Total reported shares across all holders - **`aggregate_value` (required)** `string` — Total reported value across all holders (in thousands of USD per Form 13F convention) - **`cusip` (required)** `string` — Security CUSIP - **`n_holders` (required)** `integer` — Distinct managers reporting this position at the period end - **`pct_of_filers` (required)** `number` — n\_holders / total\_filers\_in\_period, range \[0, 1] - **`period_of_report` (required)** `string`, format: `date` — 13F period analyzed - **`top_10_share_pct` (required)** `number` — Share of aggregate\_value held by the top-10 managers (concentration proxy) - **`total_filers_in_period` (required)** `integer` — Distinct managers with any 13F holding in this period (denominator) - **`hhi`** `object` — Herfindahl-Hirschman Index over manager value shares, scaled to the standard \[0, 10000] range (sum of squared percentage shares). Higher = more concentrated holder base. Null when aggregate\_value is zero. - **`name_of_issuer`** `object` — Issuer name resolved from holdings - **`qoq_holders_delta`** `object` — Change in n\_holders vs prior calendar quarter; null if no prior-period data available **Example:** ```json { "period_of_report": "", "direction": "", "results": [ { "aggregate_shares": "3187420800", "aggregate_value": "548320500", "cusip": "037833100", "n_holders": 4218, "name_of_issuer": "APPLE INC", "pct_of_filers": 0.748, "period_of_report": "2024-03-31", "qoq_holders_delta": 47, "top_10_share_pct": 0.31, "total_filers_in_period": 5640 } ] } ``` ##### Status: 401 Authentication failed - missing or invalid API key ###### Content-Type: application/json - **`message`** `string` **Example:** ```json { "message": "Missing API key in request" } ``` ##### Status: 422 Request validation failed - invalid or missing parameters ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 429 Rate limit exceeded for your tier ###### Content-Type: application/json - **`message`** `string` **Example:** ```json { "message": "" } ``` ##### Status: 500 Unhandled server error — file an issue with the request\_id from the error envelope. ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 502 Upstream dependency failed — gateway, key store, or downstream service unavailable. ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 503 Database query error or timeout — retry with backoff ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ### 13F holder concentration metrics for one cusip - **Method:** `GET` - **Path:** `/api/v1/signals/13f-crowding` - **Tags:** 13F Analytics Per-security holder concentration at one period: distinct manager count, aggregate value/shares, top-10 manager share of aggregate value, and QoQ change in holder count vs. the prior calendar quarter. Crowded long positions are a known liquidation-risk signal; this endpoint gives the raw metrics to identify them. #### Responses ##### Status: 200 Successful Response ###### Content-Type: application/json - **`aggregate_shares` (required)** `string` — Total reported shares across all holders - **`aggregate_value` (required)** `string` — Total reported value across all holders (in thousands of USD per Form 13F convention) - **`cusip` (required)** `string` — Security CUSIP - **`n_holders` (required)** `integer` — Distinct managers reporting this position at the period end - **`pct_of_filers` (required)** `number` — n\_holders / total\_filers\_in\_period, range \[0, 1] - **`period_of_report` (required)** `string`, format: `date` — 13F period analyzed - **`top_10_share_pct` (required)** `number` — Share of aggregate\_value held by the top-10 managers (concentration proxy) - **`total_filers_in_period` (required)** `integer` — Distinct managers with any 13F holding in this period (denominator) - **`hhi`** `object` — Herfindahl-Hirschman Index over manager value shares, scaled to the standard \[0, 10000] range (sum of squared percentage shares). Higher = more concentrated holder base. Null when aggregate\_value is zero. - **`name_of_issuer`** `object` — Issuer name resolved from holdings - **`qoq_holders_delta`** `object` — Change in n\_holders vs prior calendar quarter; null if no prior-period data available **Example:** ```json { "aggregate_shares": "3187420800", "aggregate_value": "548320500", "cusip": "037833100", "n_holders": 4218, "name_of_issuer": "APPLE INC", "pct_of_filers": 0.748, "period_of_report": "2024-03-31", "qoq_holders_delta": 47, "top_10_share_pct": 0.31, "total_filers_in_period": 5640 } ``` ##### Status: 401 Authentication failed - missing or invalid API key ###### Content-Type: application/json - **`message`** `string` **Example:** ```json { "message": "Missing API key in request" } ``` ##### Status: 422 Request validation failed - invalid or missing parameters ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 429 Rate limit exceeded for your tier ###### Content-Type: application/json - **`message`** `string` **Example:** ```json { "message": "" } ``` ##### Status: 500 Unhandled server error — file an issue with the request\_id from the error envelope. ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 502 Upstream dependency failed — gateway, key store, or downstream service unavailable. ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 503 Database query error or timeout — retry with backoff ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ### 13F new / exit / upsize / downsize flows for a manager or security - **Method:** `GET` - **Path:** `/api/v1/signals/13f-flows` - **Tags:** 13F Analytics **Required:** provide exactly one of `filing_manager_cik` or `cusip`, plus `period`. Returns `400 MISSING_PARAMETER` otherwise. Two query modes; provide exactly one filter: - **`filing_manager_cik`** — flows for one manager across all positions vs. prior calendar quarter (uses amendment-resolved holdings on both sides). - **`cusip`** — flows for one security across all managers vs. prior calendar quarter (uses raw holdings GROUP BY manager — fast but does not resolve per-manager amendment chains). Hold rows excluded by default; pass `include_holds=true` to surface positions whose value didn't change. #### Responses ##### Status: 200 Successful Response ###### Content-Type: application/json - **`flows` (required)** `array` — Per-position flow rows **Items:** - **`classification` (required)** `object` — Flow classification (see FlowClassification enum) - **`current_value` (required)** `string` — Current-period position value (in thousands of USD) - **`delta_value` (required)** `string` — current\_value − prior\_value (in thousands of USD) - **`prior_value` (required)** `string` — Prior-period position value (in thousands of USD) - **`cusip`** `object` — Security CUSIP - **`filing_manager_cik`** `object` — Filing manager CIK - **`filing_manager_name`** `object` — Filing manager legal name - **`name_of_issuer`** `object` — Issuer name - **`pct_change`** `object` — (current − prior) / prior. Null for new positions where prior is zero (avoids +inf). - **`period_of_report` (required)** `string`, format: `date` — Current 13F period analyzed - **`summary` (required)** `object` — Counts per classification — keys: new, exit, upsize, downsize, hold - **`cusip`** `object` — Security CUSIP if request was filtered by security - **`filing_manager_cik`** `object` — Filing manager CIK if request was filtered by manager - **`prior_period`** `object` — Calendar-quarter end before \`period\_of\_report\`. Null if no prior holdings could be resolved. **Example:** ```json { "filing_manager_cik": "", "cusip": "", "period_of_report": "", "prior_period": "", "flows": [ { "cusip": "", "name_of_issuer": "", "filing_manager_cik": "", "filing_manager_name": "", "classification": null, "current_value": "", "prior_value": "", "delta_value": "", "pct_change": 1 } ], "summary": { "additionalProperty": 1 } } ``` ##### Status: 401 Authentication failed - missing or invalid API key ###### Content-Type: application/json - **`message`** `string` **Example:** ```json { "message": "Missing API key in request" } ``` ##### Status: 422 Request validation failed - invalid or missing parameters ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 429 Rate limit exceeded for your tier ###### Content-Type: application/json - **`message`** `string` **Example:** ```json { "message": "" } ``` ##### Status: 500 Unhandled server error — file an issue with the request\_id from the error envelope. ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 502 Upstream dependency failed — gateway, key store, or downstream service unavailable. ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 503 Database query error or timeout — retry with backoff ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ### Classify a manager's 13F positions as passive / active / transitioned - **Method:** `GET` - **Path:** `/api/v1/signals/manager-stance` - **Tags:** 13F Analytics For one manager at one period, classifies each 13F position by the manager's own SC13 (Schedule 13D / 13G) filings against the same issuer: - **passive** — manager filed 13G (intent: no control) - **active** — manager filed 13D (intent: influence/control) - **transitioned** — both schedule types in history (e.g., switched from passive 13G to active 13D) - **unclassified** — manager didn't cross 5%, no SC13 filing on this issuer Useful for distinguishing index-tracking holdings (overwhelmingly passive) from activist managers (high active share) within a 13F portfolio. #### Responses ##### Status: 200 Successful Response ###### Content-Type: application/json - **`filing_manager_cik` (required)** `string` — Filing manager CIK - **`pct_active` (required)** `number` — Share of total\_value classified active (0-1) - **`pct_passive` (required)** `number` — Share of total\_value classified passive (0-1) - **`pct_transitioned` (required)** `number` — Share of total\_value classified transitioned (0-1) - **`pct_unclassified` (required)** `number` — Share of total\_value classified unclassified (0-1) - **`period_of_report` (required)** `string`, format: `date` — 13F period analyzed - **`positions` (required)** `array` — Per-position rows **Items:** - **`classification` (required)** `object` — Stance classification (see StanceClassification enum) - **`cusip`** `object` — Security CUSIP - **`has_historical_13d`** `boolean`, default: `false` — True if the manager has ever filed a 13D on this issuer - **`has_historical_13g`** `boolean`, default: `false` — True if the manager has ever filed a 13G on this issuer - **`most_recent_schedule_date`** `object` — event\_date of the most recent SC13 filing - **`most_recent_schedule_type`** `object` — 'D' or 'G' from the manager's most recent SC13 filing on this issuer - **`name_of_issuer`** `object` — Issuer name - **`value`** `object` — 13F-reported position value (thousands of USD) - **`total_value` (required)** `string` — Total portfolio value across all positions (thousands of USD) - **`filing_manager_name`** `object` — Filing manager legal name **Example:** ```json { "filing_manager_cik": "", "filing_manager_name": "", "period_of_report": "", "total_value": "", "pct_passive": 1, "pct_active": 1, "pct_transitioned": 1, "pct_unclassified": 1, "positions": [ { "cusip": "", "name_of_issuer": "", "value": "", "classification": null, "most_recent_schedule_type": "", "most_recent_schedule_date": "", "has_historical_13d": false, "has_historical_13g": false } ] } ``` ##### Status: 401 Authentication failed - missing or invalid API key ###### Content-Type: application/json - **`message`** `string` **Example:** ```json { "message": "Missing API key in request" } ``` ##### Status: 422 Request validation failed - invalid or missing parameters ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 429 Rate limit exceeded for your tier ###### Content-Type: application/json - **`message`** `string` **Example:** ```json { "message": "" } ``` ##### Status: 500 Unhandled server error — file an issue with the request\_id from the error envelope. ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 502 Upstream dependency failed — gateway, key store, or downstream service unavailable. ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 503 Database query error or timeout — retry with backoff ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ### Position-level stance transitions between two 13F periods - **Method:** `GET` - **Path:** `/api/v1/signals/manager-stance/transitions` - **Tags:** 13F Analytics Compares stance classifications for one manager between two periods and returns the per-CUSIP transitions (excluding `unclassified → unclassified`, which is noise). The signal is in the *change*: a position moving from `passive` to `active`, or from `unclassified` to `active`, surfaces a strategy shift the per-period number doesn't. **Examples:** - Berkshire transitions across two quarters: `?filing_manager_cik=1067983&prior_period=2024-06-30¤t_period=2024-09-30` #### Responses ##### Status: 200 Successful Response ###### Content-Type: application/json - **`current_period` (required)** `string`, format: `date` — Current 13F period compared. - **`filing_manager_cik` (required)** `string` — Filing manager CIK queried. - **`prior_period` (required)** `string`, format: `date` — Prior 13F period compared. - **`transitions` (required)** `array` — Positions whose classification changed between the two periods (excluding \`unclassified → unclassified\`). Sorted by absolute current\_value descending. **Items:** - **`current_classification` (required)** `object` — Stance at the current period. - **`prior_classification` (required)** `object` — Stance at the prior period. - **`current_value`** `object` — Position value at the current period (thousands of USD). - **`cusip`** `object` — Security CUSIP. - **`name_of_issuer`** `object` — Issuer name (modal across the two periods' rows). - **`prior_value`** `object` — Position value at the prior period (thousands of USD). - **`filing_manager_name`** `object` — Filing manager legal name. **Example:** ```json { "filing_manager_cik": "", "filing_manager_name": "", "prior_period": "", "current_period": "", "transitions": [ { "cusip": "", "name_of_issuer": "", "prior_classification": null, "current_classification": null, "prior_value": "", "current_value": "" } ] } ``` ##### Status: 401 Authentication failed - missing or invalid API key ###### Content-Type: application/json - **`message`** `string` **Example:** ```json { "message": "Missing API key in request" } ``` ##### Status: 422 Request validation failed - invalid or missing parameters ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 429 Rate limit exceeded for your tier ###### Content-Type: application/json - **`message`** `string` **Example:** ```json { "message": "" } ``` ##### Status: 500 Unhandled server error — file an issue with the request\_id from the error envelope. ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 502 Upstream dependency failed — gateway, key store, or downstream service unavailable. ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 503 Database query error or timeout — retry with backoff ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ### Inverse N-PORT index — funds holding a security - **Method:** `GET` - **Path:** `/api/v1/signals/fund-x-ray` - **Tags:** Cross-Holder Views "Which mutual funds and ETFs hold this security?" Inverse of the standard fund→holdings view. Answers via N-PORT holdings filtered by cusip or isin at one period. Returns paginated holdings ranked by USD value, plus summary counts (distinct fund families via registrant\_cik, distinct individual funds via series\_id, aggregate USD across all holders). **Required:** provide exactly one of `cusip` or `isin`, plus `period`. Returns `400 MISSING_PARAMETER` if neither identifier (or both) is supplied. #### Responses ##### Status: 200 Successful Response ###### Content-Type: application/json - **`aggregate_value_usd` (required)** `string` — Total USD value held across all fund series - **`data` (required)** `array` — Per-fund holding rows (paginated) **Items:** - **`filing_id` (required)** `string` — N-PORT filing this position came from - **`period_of_report` (required)** `string`, format: `date` — N-PORT reporting period end date - **`accepted_time`** `object` — When the SEC accepted the parent N-PORT filing - **`asset_cat`** `object` — N-PORT asset category code (e.g., 'EC', 'DBT') - **`balance`** `object` — Position size in N-PORT units (shares, principal, contracts) - **`fair_val_level`** `object` — FAS 157 fair-value hierarchy level (1 quoted / 2 observable / 3 unobservable). NOT the Rule 22e-4 liquidity buckets. - **`is_restricted_sec`** `object` — True if this is a restricted security - **`issuer_cat`** `object` — N-PORT issuer category code (e.g., 'CORP', 'TREA') - **`payoff_profile`** `object` — Payoff direction: 'Long', 'Short', or 'N/A' - **`pct_val`** `object` — Position as a percent of fund portfolio (0-100) - **`registrant_cik`** `object` — Fund registrant CIK - **`registrant_name`** `object` — Fund registrant legal name - **`series_id`** `object` — SEC fund series identifier - **`series_name`** `object` — Fund series display name - **`val_usd`** `object` — Position value in USD at period end - **`fund_count` (required)** `integer` — Distinct fund registrants (registrant\_cik) holding the security - **`meta` (required)** `object` — Canonical pagination block. Mirrors top-level \`total\`, \`page\`, \`page\_size\`, \`total\_pages\` for clients that consume the {data, meta, summary} envelope. - **`page_size` (required)** `integer` — Results per page - **`period_of_report` (required)** `string`, format: `date` — N-PORT period analyzed - **`series_count` (required)** `integer` — Distinct fund series (series\_id) holding the security - **`summary` (required)** `object` — Endpoint-specific aggregates. Mirrors \`cusip\`, \`isin\`, \`security\_name\`, \`period\_of\_report\`, \`fund\_count\`, \`series\_count\`, and \`aggregate\_value\_usd\`. - **`cusip`** `object` — CUSIP queried - **`isin`** `object` — ISIN queried - **`page`** `integer`, default: `1` — Current page number (1-indexed) - **`security_name`** `object` — Security name from the first holding row - **`total`** `integer`, default: `0` — Total count of matching rows - **`total_pages`** `integer`, default: `1` — Total number of pages **Example:** ```json { "total": 0, "page": 1, "page_size": 1, "total_pages": 1, "cusip": "", "isin": "", "security_name": "", "period_of_report": "", "fund_count": 1, "series_count": 1, "aggregate_value_usd": "", "data": [ { "filing_id": "", "period_of_report": "", "accepted_time": "", "registrant_cik": "", "registrant_name": "", "series_id": "", "series_name": "", "balance": "", "val_usd": "", "pct_val": "", "payoff_profile": "", "asset_cat": "", "issuer_cat": "", "fair_val_level": 1, "is_restricted_sec": true } ], "meta": {}, "summary": {} } ``` ##### Status: 401 Authentication failed - missing or invalid API key ###### Content-Type: application/json - **`message`** `string` **Example:** ```json { "message": "Missing API key in request" } ``` ##### Status: 422 Request validation failed - invalid or missing parameters ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 429 Rate limit exceeded for your tier ###### Content-Type: application/json - **`message`** `string` **Example:** ```json { "message": "" } ``` ##### Status: 500 Unhandled server error — file an issue with the request\_id from the error envelope. ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 502 Upstream dependency failed — gateway, key store, or downstream service unavailable. ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 503 Database query error or timeout — retry with backoff ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ### Schedule 13D / 13G coordinated-filing detection - **Method:** `GET` - **Path:** `/api/v1/signals/13d-groups` - **Tags:** Activism & Governance Surfaces SC13 filings where two or more reporting persons are flagged as members of a group via the SC13's `group_member_a` / `group_member_b` booleans. Common pattern when activists coordinate or when family offices file jointly. Returns paginated groups, each with member detail (CIKs, names, voting/dispositive power, percent\_of\_class) and aggregate stake (sum of `aggregate_amount` and `percent_of_class` across flagged members). **Required:** provide `issuer_cusip`, `issuer_name`, or both `since`+`until`. Returns `400 MISSING_PARAMETER` otherwise. #### Responses ##### Status: 200 Successful Response ###### Content-Type: application/json - **`data` (required)** `array` — Page of coordinated-filing groups **Items:** - **`filing_id` (required)** `string` — Source SC13 filing identifier - **`member_count` (required)** `integer` — Number of flagged group members on this filing - **`members` (required)** `array` — Flagged group-member rows **Items:** - **`record_index` (required)** `integer` — Per-filing 0-based ordinal of this person row - **`aggregate_amount`** `object` — Aggregate beneficial ownership reported (Item 11) - **`cik`** `object` — Reporting person CIK (where assigned) - **`citizenship`** `object` — Citizenship or place of organization (Item 6) - **`group_member_a`** `object` — Item 2(a): person is a member of a Section 13(d) group - **`group_member_b`** `object` — Item 2(b): person is excluded from the group - **`names`** `object` — Reporting person name (Item 1 on the cover page) - **`percent_of_class`** `object` — Percent of class reported (Item 13) - **`reporting_person_type`** `object` — Cover-page Item 2 type code (e.g., IN, OO, BD) - **`shared_voting_power`** `object` — Shared voting power (Item 8) - **`sole_voting_power`** `object` — Sole voting power (Item 7) - **`accepted_time`** `object` — When the SEC accepted the filing - **`aggregate_amount`** `object` — Sum of \`aggregate\_amount\` across all flagged group members - **`aggregate_percent_of_class`** `object` — Sum of \`percent\_of\_class\` across all flagged group members on this filing - **`amendment_no`** `object` — Amendment number for amendment filings - **`event_date`** `object` — Triggering event date for this filing - **`is_likely_double_counted`** `boolean`, default: `false` — True when \`aggregate\_percent\_of\_class > 100\` — a strong signal that the same shares are being reported by multiple members of the group (legitimate under SC 13 rules but should not be displayed as a literal ownership stake). - **`issuer_cusip`** `object` — Issuer CUSIP from the filing - **`issuer_name`** `object` — Issuer (target company) legal name - **`schedule_type`** `object` — Schedule variant (SC 13D / 13D/A / 13G / 13G/A) - **`page_size` (required)** `integer` — Results per page - **`page`** `integer`, default: `1` — Current page number (1-indexed) - **`total`** `integer`, default: `0` — Total count of matching rows - **`total_pages`** `integer`, default: `1` — Total number of pages **Example:** ```json { "total": 0, "page": 1, "page_size": 1, "total_pages": 1, "data": [ { "filing_id": "", "schedule_type": "", "issuer_cusip": "", "issuer_name": "", "event_date": "", "accepted_time": "", "amendment_no": "", "member_count": 1, "aggregate_percent_of_class": "", "aggregate_amount": "", "is_likely_double_counted": false, "members": [] } ] } ``` ##### Status: 400 Request rejected — usually a missing required parameter or an at-least-one-of constraint not satisfied. ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 401 Authentication failed - missing or invalid API key ###### Content-Type: application/json - **`message`** `string` **Example:** ```json { "message": "Missing API key in request" } ``` ##### Status: 422 Request validation failed - invalid or missing parameters ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 429 Rate limit exceeded for your tier ###### Content-Type: application/json - **`message`** `string` **Example:** ```json { "message": "" } ``` ##### Status: 500 Unhandled server error — file an issue with the request\_id from the error envelope. ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 502 Upstream dependency failed — gateway, key store, or downstream service unavailable. ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 503 Database query error or timeout — retry with backoff ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ### Form D quarterly capital-formation index - **Method:** `GET` - **Path:** `/api/v1/signals/private-capital` - **Tags:** Capital Markets Aggregates Form D (Reg D) exempt-offering filings into quarterly buckets over a window. Returns per-quarter filing counts, distinct issuer counts, total offering amounts, total amounts sold, and a 40-Act flag count. Set `include_industry_breakdown=true` to emit one bucket per (quarter × industry); otherwise one bucket per quarter is returned. Filter to one industry with `industry=...` (e.g., `Pooled Investment Fund`, `Real Estate`, `Technology`). The only systematic public view of US private capital formation — useful for VC/PE benchmarking and macro-level fundraising trends. #### Responses ##### Status: 200 Successful Response ###### Content-Type: application/json - **`aggregate_distinct_issuers` (required)** `integer` — Distinct issuers across the window - **`aggregate_filing_count` (required)** `integer` — Total Form D filings across the entire window - **`aggregate_total_offering` (required)** `string` — Total offering amount across the window (USD) - **`aggregate_total_sold` (required)** `string` — Total amount sold across the window (USD) - **`buckets` (required)** `array` — Quarterly (and optionally per-industry) buckets **Items:** - **`filing_count` (required)** `integer` — Form D filings in this bucket - **`is_40_act_count` (required)** `integer` — Filings flagged as Investment Company Act of 1940 funds - **`issuer_count` (required)** `integer` — Distinct issuers (issuer\_cik) in this bucket - **`period_end` (required)** `string`, format: `date` — Quarter end (e.g., '2025-09-30') - **`period_start` (required)** `string`, format: `date` — Quarter start (e.g., '2025-07-01') - **`total_amount_sold` (required)** `string` — Sum of total amount sold to date in this bucket (USD) - **`total_offering_amount` (required)** `string` — Sum of total offering amounts in this bucket (USD) - **`avg_offering_size`** `object` — Mean offering amount (total\_offering\_amount / filing\_count) - **`industry_group_type`** `object` — Industry bucket; null when include\_industry\_breakdown=false - **`include_industry_breakdown` (required)** `boolean` — Whether buckets are split per (quarter × industry) or per quarter only - **`since` (required)** `string`, format: `date` — Window start applied - **`until` (required)** `string`, format: `date` — Window end applied - **`industry_filter`** `object` — industry\_group\_type filter applied (if any) - **`is_40_act_filter`** `object` — 40 Act filter applied (true / false / null) **Example:** ```json { "since": "", "until": "", "industry_filter": "", "is_40_act_filter": true, "include_industry_breakdown": true, "aggregate_filing_count": 1, "aggregate_total_offering": "", "aggregate_total_sold": "", "aggregate_distinct_issuers": 1, "buckets": [ { "period_start": "", "period_end": "", "industry_group_type": "", "filing_count": 1, "issuer_count": 1, "total_offering_amount": "", "total_amount_sold": "", "avg_offering_size": "", "is_40_act_count": 1 } ] } ``` ##### Status: 401 Authentication failed - missing or invalid API key ###### Content-Type: application/json - **`message`** `string` **Example:** ```json { "message": "Missing API key in request" } ``` ##### Status: 422 Request validation failed - invalid or missing parameters ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 429 Rate limit exceeded for your tier ###### Content-Type: application/json - **`message`** `string` **Example:** ```json { "message": "" } ``` ##### Status: 500 Unhandled server error — file an issue with the request\_id from the error envelope. ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 502 Upstream dependency failed — gateway, key store, or downstream service unavailable. ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 503 Database query error or timeout — retry with backoff ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ### Form 4 × SC13 governance feature vector for one issuer - **Method:** `GET` - **Path:** `/api/v1/signals/governance-features` - **Tags:** Activism & Governance Combines insider-trading patterns and Schedule 13D/G activity for one issuer over a window. Suitable as a feature vector for downstream classifiers (proxy-fight prediction, settlement modeling) — also emits a coarse `governance_pressure_score` for quick triage. Bridge: Form 4 (`issuer_cik`) → SC13 (`issuer_name`) via case-insensitive name match. The response's `matched_issuer_names` field counts the distinct issuer-name spellings used; 1 = clean unique match, ≥2 indicates the issuer's filings used multiple spellings (still works, but lower precision). #### Responses ##### Status: 200 Successful Response ###### Content-Type: application/json - **`governance_pressure_score` (required)** `number` — Coarse composite combining net insider distribution rate, distinct SC13 filer count, and 13D-vs-13G mix. Range \[0, 1]; ≥0.6 means significant governance-pressure signals are stacking - **`insider` (required)** `object` — Insider (Form 4) features - **`issuer_cik` (required)** `string` — Issuer CIK queried - **`matched_issuer_names` (required)** `integer` — Distinct issuer\_name spellings used to match SC13 filings to this issuer — confidence proxy (1 = clean unique match; >1 = potential disambiguation noise) - **`period_end` (required)** `string`, format: `date` — Window end (inclusive) - **`period_start` (required)** `string`, format: `date` — Window start (inclusive) - **`sc13` (required)** `object` — Schedule 13D/G features - **`issuer_name`** `object` — Issuer name resolved from Form 4 / SC13 records **Example:** ```json { "issuer_cik": "", "issuer_name": "", "matched_issuer_names": 1, "period_start": "", "period_end": "", "insider": { "distinct_insiders_selling": 1, "distinct_insiders_buying": 1, "insider_dispositions_dollars": "", "insider_acquisitions_dollars": "", "discretionary_sale_dollars": "" }, "sc13": { "sc13_filings_count": 1, "sc13d_filings_count": 1, "sc13g_filings_count": 1, "distinct_filers": 1, "most_recent_event_date": "", "max_percent_of_class": "", "has_group_member_flag": true }, "governance_pressure_score": 1 } ``` ##### Status: 401 Authentication failed - missing or invalid API key ###### Content-Type: application/json - **`message`** `string` **Example:** ```json { "message": "Missing API key in request" } ``` ##### Status: 422 Request validation failed - invalid or missing parameters ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 429 Rate limit exceeded for your tier ###### Content-Type: application/json - **`message`** `string` **Example:** ```json { "message": "" } ``` ##### Status: 500 Unhandled server error — file an issue with the request\_id from the error envelope. ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 502 Upstream dependency failed — gateway, key store, or downstream service unavailable. ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 503 Database query error or timeout — retry with backoff ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ### Combined 13F + N-PORT ownership view for one cusip - **Method:** `GET` - **Path:** `/api/v1/signals/ownership-atlas` - **Tags:** Cross-Holder Views Cross-source ownership atlas: 13F holders (institutional managers) and N-PORT holders (registered investment companies) for one cusip at one period. Both views key on cusip directly, so this is a true structural join — no name match required. Response includes per-source holder counts, aggregate values, and top-10 concentration share on each side. Useful for spotting concentration risk: a security with 80%+ top-10 share on either side has a thin holder base; large redemption events in any of those holders can create forced selling. #### Responses ##### Status: 200 Successful Response ###### Content-Type: application/json - **`breakdowns` (required)** `array` — Per-holder-type breakdowns (13F + N-PORT) **Items:** - **`aggregate_value` (required)** `string` — Total reported value (USD) - **`holder_count` (required)** `integer` — Distinct holders in this bucket - **`holder_type` (required)** `string` — 'institutional\_manager\_13f' (13F filers) or 'registered\_fund\_nport' (N-PORT registered investment companies). These overlap conceptually but disclosure regimes differ: 13F captures investment managers at the firm level; N-PORT captures individual fund series. - **`aggregate_shares`** `object` — Total reported shares (where comparable) - **`cusip` (required)** `string` — Security CUSIP queried - **`period_of_report` (required)** `string`, format: `date` — Period analyzed - **`top_10_share_pct_13f` (required)** `number` — Top-10 13F managers' share of 13F aggregate value (0-1) - **`top_10_share_pct_nport` (required)** `number` — Top-10 N-PORT funds' share of N-PORT aggregate value (0-1) - **`total_aggregate_value` (required)** `string` — Sum of aggregate\_value across types - **`total_holders` (required)** `integer` — Sum of holder\_count across types - **`name_of_issuer`** `object` — Issuer name **Example:** ```json { "cusip": "", "name_of_issuer": "", "period_of_report": "", "breakdowns": [ { "holder_type": "", "holder_count": 1, "aggregate_value": "", "aggregate_shares": "" } ], "total_holders": 1, "total_aggregate_value": "", "top_10_share_pct_13f": 1, "top_10_share_pct_nport": 1 } ``` ##### Status: 401 Authentication failed - missing or invalid API key ###### Content-Type: application/json - **`message`** `string` **Example:** ```json { "message": "Missing API key in request" } ``` ##### Status: 422 Request validation failed - invalid or missing parameters ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 429 Rate limit exceeded for your tier ###### Content-Type: application/json - **`message`** `string` **Example:** ```json { "message": "" } ``` ##### Status: 500 Unhandled server error — file an issue with the request\_id from the error envelope. ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 502 Upstream dependency failed — gateway, key store, or downstream service unavailable. ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 503 Database query error or timeout — retry with backoff ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ### Per-issuer short-term + long-term funding sources (N-MFP × N-PORT) - **Method:** `GET` - **Path:** `/api/v1/signals/funding-map` - **Tags:** Capital Markets Per-issuer funding map: short-term sources (commercial paper, repo, CDs visible in N-MFP money-market holdings) plus long-term sources (bonds and equity in N-PORT registered-fund holdings). **Required:** provide exactly one of `cusip` or `security_cik`. Returns `400 MISSING_PARAMETER` otherwise. Two query modes; provide exactly one: - **`cusip`** — one specific security, joined cleanly across both views - **`security_cik`** — one issuer entity. Captures all of the issuer's debt securities held by money-market funds (N-MFP), since N-MFP exposes `security_cik` directly. N-PORT side falls back to issuer name match for this mode. Short-term bucket includes WAL-weighted average maturity and illiquid share — useful for identifying issuers with concentrated rollover risk in stressed segments of the money-market universe. #### Responses ##### Status: 200 Successful Response ###### Content-Type: application/json - **`long_term_funding` (required)** `object` — N-PORT-derived long-term funding (bonds, equity) - **`period_of_report` (required)** `string`, format: `date` — Reference period end - **`short_term_funding` (required)** `object` — N-MFP-derived short-term funding (commercial paper, repo, CDs) - **`short_term_share_pct` (required)** `number` — Short-term share of total visible funding in \[0, 1]. High values flag rollover-risk concentration. - **`total_aggregate_value` (required)** `string` — Sum of short\_term + long\_term aggregate values (USD) - **`cusip`** `object` — Security CUSIP queried - **`name_of_issuer`** `object` — Issuer name resolved from the holdings - **`security_cik`** `object` — Issuer CIK queried **Example:** ```json { "cusip": "", "security_cik": "", "name_of_issuer": "", "period_of_report": "", "short_term_funding": { "source_type": "", "holder_count": 1, "aggregate_value": "", "avg_maturity_days": 1, "illiquid_share_pct": 1 }, "long_term_funding": { "source_type": "", "holder_count": 1, "aggregate_value": "", "avg_maturity_days": 1, "illiquid_share_pct": 1 }, "total_aggregate_value": "", "short_term_share_pct": 1 } ``` ##### Status: 401 Authentication failed - missing or invalid API key ###### Content-Type: application/json - **`message`** `string` **Example:** ```json { "message": "Missing API key in request" } ``` ##### Status: 422 Request validation failed - invalid or missing parameters ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 429 Rate limit exceeded for your tier ###### Content-Type: application/json - **`message`** `string` **Example:** ```json { "message": "" } ``` ##### Status: 500 Unhandled server error — file an issue with the request\_id from the error envelope. ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 502 Upstream dependency failed — gateway, key store, or downstream service unavailable. ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 503 Database query error or timeout — retry with backoff ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ### Insider × institutional alignment for one cusip + period - **Method:** `GET` - **Path:** `/api/v1/signals/smart-money` - **Tags:** Activism & Governance Equal-weight v1 of the smart-money convergence/divergence signal. Joins insider activity (Form 4, by issuer\_cik) with institutional flows (13F, by cusip) over a trailing window. Returns: - **alignment\_score** in \[-1, 1] — magnitude tracks insider conviction; sign tracks alignment of the two flows. - **alignment\_classification** — `aligned_bullish`, `aligned_bearish`, `divergent_insider_buying`, `divergent_insider_selling`, or `neutral`. - **confidence** — bridge match quality (1.0 = exact unique name match, 0.8 = ambiguous match, 0.0 = no Form 4 issuer found for this cusip). Manager-quality weighting (per the strategy doc's priority #4) is out of scope for v1 — needs external return data. This v1 treats all 13F managers equally; weight by quality once that data lands. #### Responses ##### Status: 200 Successful Response ###### Content-Type: application/json - **`alignment_classification` (required)** `object` — Categorical alignment label (see AlignmentClassification enum) - **`alignment_score` (required)** `number` — Composite alignment score in \[-1, 1]. Magnitude reflects signal strength; sign reflects direction (positive = bullish alignment, negative = bearish, magnitude near 0 = neutral or divergent) - **`confidence` (required)** `number` — Bridge confidence between 13F (cusip-keyed) and Form 4 (CIK-keyed): 1.0 = exact name match with single CIK; 0.8 = name match with multiple CIK candidates (most-active chosen); 0.0 = no Form 4 match (insider features zeroed) - **`cusip` (required)** `string` — CUSIP of the analyzed security - **`distinct_insiders` (required)** `integer` — Distinct insiders transacting during the window - **`insider_acquired_dollars` (required)** `string` — Total insider acquisitions during the trailing window (USD) - **`insider_disposed_dollars` (required)** `string` — Total insider dispositions during the trailing window (USD) - **`insider_dollar_imbalance` (required)** `number` — (acquired − disposed) / total. Range \[-1, 1]; positive = net buying - **`insider_window_days` (required)** `integer` — Trailing window for Form 4 aggregation - **`institution_aggregate_value` (required)** `string` — Aggregate 13F-reported holding value (in thousands of USD per Form 13F convention) - **`institution_direction` (required)** `string` — Institutional positioning direction based on QoQ holder delta: 'accumulating', 'distributing', or 'neutral' - **`institution_n_holders` (required)** `integer` — Distinct 13F holders of this security at \`period\` - **`period` (required)** `string`, format: `date` — Reference date for the analysis - **`institution_qoq_holders_delta`** `object` — Change in distinct 13F holder count vs. the prior quarter (positive = accumulating) - **`matched_issuer_cik`** `object` — Form 4 issuer CIK matched to the 13F-listed \`name\_of\_issuer\` - **`name_of_issuer`** `object` — Issuer name resolved from 13F holdings **Example:** ```json { "alignment_classification": "divergent_insider_selling", "alignment_score": -0.35, "confidence": 1, "cusip": "037833100", "distinct_insiders": 4, "insider_acquired_dollars": "0", "insider_disposed_dollars": "12450000", "insider_dollar_imbalance": -1, "insider_window_days": 90, "institution_aggregate_value": "548320500", "institution_direction": "accumulating", "institution_n_holders": 4218, "institution_qoq_holders_delta": 47, "matched_issuer_cik": "0000320193", "name_of_issuer": "APPLE INC", "period": "2024-03-31" } ``` ##### Status: 401 Authentication failed - missing or invalid API key ###### Content-Type: application/json - **`message`** `string` **Example:** ```json { "message": "Missing API key in request" } ``` ##### Status: 422 Request validation failed - invalid or missing parameters ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 429 Rate limit exceeded for your tier ###### Content-Type: application/json - **`message`** `string` **Example:** ```json { "message": "" } ``` ##### Status: 500 Unhandled server error — file an issue with the request\_id from the error envelope. ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 502 Upstream dependency failed — gateway, key store, or downstream service unavailable. ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 503 Database query error or timeout — retry with backoff ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ### Insiders buying what funds aren't yet — bullish conviction × low 13F crowding - **Method:** `GET` - **Path:** `/api/v1/signals/conviction-x-crowding` - **Tags:** Composite Signals The contrarian intersection of insider-conviction leaders (bullish direction) and 13F crowding (low end). Returns issuers with: - Strong bullish insider-conviction score over the window, AND - 13F crowding (`pct_of_filers`) at or below `max_pct_of_filers` at the comparison period (default the most recent 13F period in the database). Cross-walk between Form 4 and 13F is by issuer-name match — the views don't share a CUSIP/CIK column. Rows where the cross-walk fails return `cusip=null` and `crowding_*=null`; they're retained in the response because they still satisfy the conviction half (callers can decide whether to treat null crowding as "no funds know about this name yet" or filter them out). #### Responses ##### Status: 200 Successful Response ###### Content-Type: application/json - **`as_of` (required)** `string`, format: `date` — Anchor date used for the conviction window. - **`data` (required)** `array` — Issuers satisfying both \`direction='bullish'\` insider conviction AND \`pct\_of\_filers <= max\_pct\_of\_filers\`. Sorted by \`insider\_conviction\_score\` descending. **Items:** - **`distinct_insiders` (required)** `integer` — Distinct insiders contributing to the conviction signal. - **`insider_conviction_score` (required)** `number` — Insider conviction score (bullish-direction; higher = stronger). - **`crowding_aggregate_value`** `object` — Total reported 13F value across all holders (thousands of USD); null when no 13F match. - **`crowding_n_holders`** `object` — Distinct 13F managers holding this CUSIP at the comparison period; null when no 13F match. - **`crowding_pct_of_filers`** `object` — n\_holders / total\_filers\_in\_period, range \[0, 1]; null when no 13F match. - **`cusip`** `object` — Resolved CUSIP via name match; null when no 13F match was found. - **`issuer_cik`** `object` — Issuer CIK (canonical short form, no leading zeros). - **`issuer_name`** `object` — Modal issuer name across the matched 13F holdings rows. - **`issuer_trading_symbol`** `object` — Issuer ticker symbol from Form 4. - **`max_pct_of_filers` (required)** `number` — Maximum \`pct\_of\_filers\` to qualify as 'low crowding'. Default 0.10 — only issuers held by ≤10% of 13F filers qualify. - **`window_days` (required)** `integer` — Insider-conviction trailing window in days. - **`crowding_period`** `object` — 13F period\_of\_report used for the crowding lookup. **Example:** ```json { "as_of": "", "window_days": 1, "crowding_period": "", "max_pct_of_filers": 1, "data": [ { "issuer_cik": "", "issuer_trading_symbol": "", "issuer_name": "", "cusip": "", "insider_conviction_score": 1, "distinct_insiders": 1, "crowding_n_holders": 1, "crowding_pct_of_filers": 1, "crowding_aggregate_value": "" } ] } ``` ##### Status: 401 Authentication failed - missing or invalid API key ###### Content-Type: application/json - **`message`** `string` **Example:** ```json { "message": "Missing API key in request" } ``` ##### Status: 422 Request validation failed - invalid or missing parameters ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 429 Rate limit exceeded for your tier ###### Content-Type: application/json - **`message`** `string` **Example:** ```json { "message": "" } ``` ##### Status: 500 Unhandled server error — file an issue with the request\_id from the error envelope. ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 502 Upstream dependency failed — gateway, key store, or downstream service unavailable. ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ##### Status: 503 Database query error or timeout — retry with backoff ###### Content-Type: application/json - **`error` (required)** `object` — Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) - **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) - **`message` (required)** `string` — Human-readable error message - **`details`** `object`, default: `null` — Additional error context - **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "error": { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } } ``` ## Schemas ### APILatestStatementsResponse - **Type:**`object` Response for /statements/latest/{identifier} endpoint. Returns the most recent statement of each type (bs, inc, cf). - **`cik` (required)** `string` — Company CIK - **`balance_sheet`** `object` — Most recent balance sheet - **`cash_flow`** `object` — Most recent cash flow statement - **`company_name`** `object` — Company name - **`income_statement`** `object` — Most recent income statement - **`tickers`** `object` — Ticker symbols **Example:** ```json { "balance_sheet": { "block_id": "...", "fiscal_year": 2024, "statement_type": "bs" }, "cash_flow": { "block_id": "...", "fiscal_year": 2024, "statement_type": "cf" }, "cik": "0000320193", "company_name": "Apple Inc.", "income_statement": { "block_id": "...", "fiscal_year": 2024, "statement_type": "inc" }, "tickers": [ "AAPL" ] } ``` ### APIRatioListResponse - **Type:**`object` Paginated list of ratios. - **`data` (required)** `array` — Array of ratios **Items:** - **`cik` (required)** `string` — SEC Central Index Key - **`fiscal_quarter` (required)** `integer` — Fiscal quarter: 0=FY, 1-4=quarters - **`fiscal_year` (required)** `integer` — Fiscal year - **`quality` (required)** `number` — Data-completeness score in \[0, 1]. Computed as the share of non-null source statements (balance sheet / income / cash flow) the ratio was derived from. 1.0 means all three sources were present; 0.67 means two of three; 0.33 means one of three. - **`ratio_category` (required)** `string` — Category: liquidity, profitability, leverage, etc. - **`ratio_id` (required)** `integer` — Unique ratio identifier - **`ratio_name` (required)** `string` — Ratio name (e.g., 'current\_ratio', 'roe') - **`company_name`** `object` — Company name - **`period_label`** `object` — Period label (e.g., 'Q1', 'FY') - **`ratio_value`** `object` — Calculated ratio value - **`tickers`** `object` — Ticker symbols - **`page` (required)** `integer` — Current page number - **`page_size` (required)** `integer` — Results per page - **`total` (required)** `integer` — Total count of matching ratios - **`total_pages` (required)** `integer` — Total pages **Example:** ```json { "data": [ { "cik": "0000320193", "company_name": "Apple Inc.", "fiscal_quarter": 1, "fiscal_year": 2024, "period_label": "Q1", "ratio_category": "liquidity", "ratio_id": 12345, "ratio_name": "current_ratio", "ratio_value": 2.45, "tickers": [ "AAPL" ] } ], "page": 1, "page_size": 100, "total": 150, "total_pages": 2 } ``` ### APIRatioResponse - **Type:**`object` Single financial ratio response from vw\_api\_ratios. - **`cik` (required)** `string` — SEC Central Index Key - **`fiscal_quarter` (required)** `integer` — Fiscal quarter: 0=FY, 1-4=quarters - **`fiscal_year` (required)** `integer` — Fiscal year - **`quality` (required)** `number` — Data-completeness score in \[0, 1]. Computed as the share of non-null source statements (balance sheet / income / cash flow) the ratio was derived from. 1.0 means all three sources were present; 0.67 means two of three; 0.33 means one of three. - **`ratio_category` (required)** `string` — Category: liquidity, profitability, leverage, etc. - **`ratio_id` (required)** `integer` — Unique ratio identifier - **`ratio_name` (required)** `string` — Ratio name (e.g., 'current\_ratio', 'roe') - **`company_name`** `object` — Company name - **`period_label`** `object` — Period label (e.g., 'Q1', 'FY') - **`ratio_value`** `object` — Calculated ratio value - **`tickers`** `object` — Ticker symbols **Example:** ```json { "cik": "0000320193", "company_name": "Apple Inc.", "fiscal_quarter": 1, "fiscal_year": 2024, "period_label": "Q1", "quality": 1, "ratio_category": "liquidity", "ratio_id": 12345, "ratio_name": "current_ratio", "ratio_value": 2.45, "tickers": [ "AAPL" ] } ``` ### APIStatementListResponse - **Type:**`object` Paginated list of statements. - **`data` (required)** `array` — Array of statements **Items:** - **`accession_num` (required)** `object` — EDGAR accession number derived from filing\_id (e.g., '0000320193-24-000123') - **`block_id` (required)** `string` — Unique statement identifier (UUID) - **`cik` (required)** `string` — SEC Central Index Key (10 digits) - **`filing_id` (required)** `string` — Unique filing identifier - **`fiscal_quarter` (required)** `integer` — Fiscal quarter: 0=FY, 1-4=quarters - **`fiscal_year` (required)** `integer` — Fiscal year the statement covers - **`source_url` (required)** `object` — Canonical SEC EDGAR Archives URL pointing at the filing's index page - **`statement_type` (required)** `string` — Statement type: 'inc', 'bs', 'cf' - **`company_name`** `object` — Company name - **`is_comparative`** `object` — Whether this is comparative data - **`period_label`** `object` — Human-readable label (e.g., 'Q1', 'FY') - **`period_length`** `object` — Period length in months - **`period_type`** `object` — Period type: 'quarterly' or 'annual' - **`statement`** `object` — Complete financial statement JSON (omitted if include\_statement=false) - **`statement_date`** `object` — Statement period end date - **`tickers`** `object` — Ticker symbols - **`page_size` (required)** `integer` — Results per page - **`page`** `integer`, default: `1` — Current page number (1-indexed) - **`total`** `integer`, default: `0` — Total count of matching statements - **`total_pages`** `integer`, default: `1` — Total number of pages **Example:** ```json { "data": [ { "block_id": "550e8400-e29b-41d4-a716-446655440000", "cik": "0000320193", "company_name": "Apple Inc.", "filing_id": "0000320193_0000320193-24-000123", "fiscal_quarter": 1, "fiscal_year": 2024, "is_comparative": false, "period_label": "Q1", "period_type": "quarterly", "statement": { "Assets": 360836000000, "Liabilities": 279281000000 }, "statement_date": "2024-03-30T00:00:00Z", "statement_type": "bs", "tickers": [ "AAPL" ] } ], "page": 1, "page_size": 50, "total": 45, "total_pages": 1 } ``` ### APIStatementResponse - **Type:**`object` Single financial statement response from vw\_api\_statements. Includes full statement JSON by default, or metadata-only if requested. `accession_num` and `source_url` are derived from `filing_id` via FilingSourceMixin. - **`accession_num` (required)** `object` — EDGAR accession number derived from filing\_id (e.g., '0000320193-24-000123') - **`block_id` (required)** `string` — Unique statement identifier (UUID) - **`cik` (required)** `string` — SEC Central Index Key (10 digits) - **`filing_id` (required)** `string` — Unique filing identifier - **`fiscal_quarter` (required)** `integer` — Fiscal quarter: 0=FY, 1-4=quarters - **`fiscal_year` (required)** `integer` — Fiscal year the statement covers - **`source_url` (required)** `object` — Canonical SEC EDGAR Archives URL pointing at the filing's index page - **`statement_type` (required)** `string` — Statement type: 'inc', 'bs', 'cf' - **`company_name`** `object` — Company name - **`is_comparative`** `object` — Whether this is comparative data - **`period_label`** `object` — Human-readable label (e.g., 'Q1', 'FY') - **`period_length`** `object` — Period length in months - **`period_type`** `object` — Period type: 'quarterly' or 'annual' - **`statement`** `object` — Complete financial statement JSON (omitted if include\_statement=false) - **`statement_date`** `object` — Statement period end date - **`tickers`** `object` — Ticker symbols **Example:** ```json { "block_id": "550e8400-e29b-41d4-a716-446655440000", "cik": "0000320193", "company_name": "Apple Inc.", "filing_id": "0000320193_0000320193-24-000123", "fiscal_quarter": 1, "fiscal_year": 2024, "is_comparative": false, "period_label": "Q1", "period_type": "quarterly", "statement": { "Assets": 360836000000, "Liabilities": 279281000000, "Stockholders' Equity": 81555000000 }, "statement_date": "2024-03-30T00:00:00Z", "statement_type": "bs", "tickers": [ "AAPL" ] } ``` ### APITextSectionListResponse - **Type:**`object` Paginated list of text sections. - **`data` (required)** `array` — Array of text sections **Items:** - **`accession_num` (required)** `object` — EDGAR accession number derived from filing\_id (e.g., '0000320193-24-000123') - **`cik` (required)** `string` — SEC Central Index Key - **`filing_id` (required)** `string` — Filing identifier - **`section_id` (required)** `string` — Unique section identifier (UUID) - **`source_url` (required)** `object` — Canonical SEC EDGAR Archives URL pointing at the filing's index page - **`accepted_time`** `object` — SEC acceptance timestamp - **`block_id`** `object` — Parent block identifier - **`clean_title`** `object` — Cleaned section title - **`company_name`** `object` — Company name - **`date`** `object` — Filing date - **`form_type`** `object` — Form type (10-K, 10-Q) - **`item_label`** `object` — Item label - **`item_number`** `object` — Item number - **`part`** `object` — Part number (1-4) - **`tickers`** `object` — Ticker symbols - **`validated_tables`** `object` — Extracted tables - **`validated_text`** `object` — Cleaned text content - **`page` (required)** `integer` — Current page number - **`page_size` (required)** `integer` — Results per page - **`total` (required)** `integer` — Total count of matching sections - **`total_pages` (required)** `integer` — Total pages **Example:** ```json { "data": [ { "block_id": "block456-789", "cik": "0000320193", "clean_title": "Management's Discussion and Analysis", "company_name": "Apple Inc.", "date": "2024-11-01T00:00:00Z", "filing_id": "0000320193_0000320193-24-000123", "form_type": "10-K", "item_label": "Item 7", "item_number": "7", "part": 2, "section_id": "sec123-456-789", "tickers": [ "AAPL" ], "validated_text": "The following discussion should be read..." } ], "page": 1, "page_size": 100, "total": 25, "total_pages": 1 } ``` ### APITextSectionResponse - **Type:**`object` Single text section response from vw\_api\_text\_sections. Contains text content and metadata for a filing section. `accession_num` and `source_url` are derived from `filing_id` via FilingSourceMixin. - **`accession_num` (required)** `object` — EDGAR accession number derived from filing\_id (e.g., '0000320193-24-000123') - **`cik` (required)** `string` — SEC Central Index Key - **`filing_id` (required)** `string` — Filing identifier - **`section_id` (required)** `string` — Unique section identifier (UUID) - **`source_url` (required)** `object` — Canonical SEC EDGAR Archives URL pointing at the filing's index page - **`accepted_time`** `object` — SEC acceptance timestamp - **`block_id`** `object` — Parent block identifier - **`clean_title`** `object` — Cleaned section title - **`company_name`** `object` — Company name - **`date`** `object` — Filing date - **`form_type`** `object` — Form type (10-K, 10-Q) - **`item_label`** `object` — Item label - **`item_number`** `object` — Item number - **`part`** `object` — Part number (1-4) - **`tickers`** `object` — Ticker symbols - **`validated_tables`** `object` — Extracted tables - **`validated_text`** `object` — Cleaned text content **Example:** ```json { "accepted_time": "2024-11-01T16:30:00Z", "block_id": "block456-789", "cik": "0000320193", "clean_title": "Management's Discussion and Analysis", "company_name": "Apple Inc.", "date": "2024-11-01T00:00:00Z", "filing_id": "0000320193_0000320193-24-000123", "form_type": "10-K", "item_label": "Item 7", "item_number": "7", "part": 2, "section_id": "sec123-456-789", "tickers": [ "AAPL" ], "validated_text": "The following discussion should be read..." } ``` ### AlignmentClassification - **Type:**`string` Joint insider × institutional alignment label. - `aligned_bullish` — insiders buying AND institutions accumulating - `aligned_bearish` — insiders selling AND institutions distributing - `divergent_insider_buying` — insiders buying, institutions selling - `divergent_insider_selling` — insiders selling, institutions buying - `neutral` — one or both sides inactive **Example:** ### AvailableEntitiesResponse - **Type:**`object` Paginated list of available entities with statement data. Response for GET /statements/entities endpoint. - **`data` (required)** `array` — Array of entities **Items:** - **`cik` (required)** `string` — SEC Central Index Key - **`fiscal_year_max` (required)** `integer` — Latest fiscal year with data - **`fiscal_year_min` (required)** `integer` — Earliest fiscal year with data - **`statement_count` (required)** `integer` — Total number of statements available - **`statement_types` (required)** `array` — Available statement types (e.g., \['bs', 'inc', 'cf']) **Items:** `string` - **`company_name`** `object` — Company name - **`tickers`** `object` — Ticker symbols - **`page` (required)** `integer` — Current page number (1-indexed) - **`page_size` (required)** `integer` — Results per page - **`total` (required)** `integer` — Total count of matching entities - **`total_pages` (required)** `integer` — Total number of pages **Example:** ```json { "data": [ { "cik": "320193", "company_name": "Apple Inc.", "fiscal_year_max": 2024, "fiscal_year_min": 2020, "statement_count": 45, "statement_types": [ "bs", "inc", "cf" ], "tickers": [ "AAPL" ] } ], "page": 1, "page_size": 100, "total": 5000, "total_pages": 50 } ``` ### AvailableEntityResponse - **Type:**`object` Single entity with data availability information. Used in the /statements/entities endpoint to show what companies have statement data available and summary statistics. - **`cik` (required)** `string` — SEC Central Index Key - **`fiscal_year_max` (required)** `integer` — Latest fiscal year with data - **`fiscal_year_min` (required)** `integer` — Earliest fiscal year with data - **`statement_count` (required)** `integer` — Total number of statements available - **`statement_types` (required)** `array` — Available statement types (e.g., \['bs', 'inc', 'cf']) **Items:** `string` - **`company_name`** `object` — Company name - **`tickers`** `object` — Ticker symbols **Example:** ```json { "cik": "320193", "company_name": "Apple Inc.", "fiscal_year_max": 2024, "fiscal_year_min": 2020, "statement_count": 45, "statement_types": [ "bs", "inc", "cf" ], "tickers": [ "AAPL" ] } ``` ### AvailableMetricsResponse - **Type:**`object` Response for GET /companies/metrics — standardized cross-company tags. - **`data` (required)** `array` — Standardized metric names available for screening **Items:** `string` - **`total` (required)** `integer` — Number of metrics returned **Example:** ```json { "data": [ "" ], "total": 1 } ``` ### BeneficialOwnershipEntitiesListResponse - **Type:**`object` * **`data` (required)** `array` — Page of filers (holders) with Schedule 13D/G data on file. **Items:** - **`cik` (required)** `string` — Required. Filer (holder) SEC Central Index Key (canonical short form). - **`filing_count` (required)** `integer` — Required. Total Schedule 13D/G filings on file for this filer. - **`company_name`** `object` — Optional. Modal filer name across the filer's Schedule 13 filings. - **`period_max`** `object` — Optional. Latest period\_of\_report observed for this filer. - **`period_min`** `object` — Optional. Earliest period\_of\_report observed for this filer. - **`tickers`** `object` — Optional. Filer ticker symbols sampled from one filing's \`filer\_tickers\`. * **`page_size` (required)** `integer` — Results per page * **`page`** `integer`, default: `1` — Current page number (1-indexed) * **`total`** `integer`, default: `0` — Total count of matching rows * **`total_pages`** `integer`, default: `1` — Total number of pages **Example:** ```json { "total": 0, "page": 1, "page_size": 1, "total_pages": 1, "data": [ { "cik": "1067983", "company_name": "BERKSHIRE HATHAWAY INC", "filing_count": 47, "period_max": "2024-03-31", "period_min": "2010-12-31", "tickers": [ "BRK-A", "BRK-B" ] } ] } ``` ### BeneficialOwnershipEntitySummary - **Type:**`object` Per-filer summary of Schedule 13D/G filing availability. SC 13 doesn't carry an `issuer_cik` column — the parent view's `cik` is the *filer's* (holder's) CIK, so this discovery view enumerates filing holders rather than target issuers. - **`cik` (required)** `string` — Required. Filer (holder) SEC Central Index Key (canonical short form). - **`filing_count` (required)** `integer` — Required. Total Schedule 13D/G filings on file for this filer. - **`company_name`** `object` — Optional. Modal filer name across the filer's Schedule 13 filings. - **`period_max`** `object` — Optional. Latest period\_of\_report observed for this filer. - **`period_min`** `object` — Optional. Earliest period\_of\_report observed for this filer. - **`tickers`** `object` — Optional. Filer ticker symbols sampled from one filing's \`filer\_tickers\`. **Example:** ```json { "cik": "1067983", "company_name": "BERKSHIRE HATHAWAY INC", "filing_count": 47, "period_max": "2024-03-31", "period_min": "2010-12-31", "tickers": [ "BRK-A", "BRK-B" ] } ``` ### BeneficialOwnershipFilingDetail - **Type:**`object` Per-filing detail — filing summary plus full reporting-person cover-page rows and exhibit list. - **`accession_num` (required)** `object` — EDGAR accession number derived from filing\_id (e.g., '0000320193-24-000123') - **`cik` (required)** `string` — Filer SEC Central Index Key - **`filing_id` (required)** `string` — Unique filing identifier - **`form_type` (required)** `string` — SEC form type (e.g., 'SC 13D', 'SC 13G/A') - **`source_url` (required)** `object` — Canonical SEC EDGAR Archives URL pointing at the filing's index page - **`accepted_time`** `object` — When the SEC accepted the filing - **`amendment_no`** `object` — Amendment number if this is an amendment ('/A' filing) - **`event_date`** `object` — Date of the event triggering the filing - **`exhibits`** `array` — All exhibits attached to this filing **Items:** - **`record_index` (required)** `integer` — Per-filing 0-based ordinal of this exhibit - **`letter`** `object` — Exhibit letter or designator (e.g., 'A', 'B', '99') - **`schedule_type`** `object` — Schedule variant the exhibit belongs to - **`title`** `object` — Exhibit title or description - **`filer_name`** `object` — Filer entity name - **`filer_tickers`** `object` — Ticker symbols associated with the filer - **`is_valid`** `object` — Whether the filing passed validation - **`issuer_class_title`** `object` — Title of the security class (e.g., 'Common Stock', 'Class A Common') - **`issuer_cusip`** `object` — 9-character CUSIP of the security covered by the filing - **`issuer_name`** `object` — Issuer (target company) legal name - **`period_of_report`** `object` — Reporting period end date - **`reporting_persons`** `array` — All reporting-person cover-page rows attached to this filing **Items:** - **`record_index` (required)** `integer` — Per-filing 0-based ordinal of this person row - **`aggregate_amount`** `object` — Item 11: aggregate beneficial ownership reported by this person - **`citizenship`** `object` — Citizenship or place of organization (Item 6 of the cover page) - **`cusip`** `object` — CUSIP repeated on the reporting-person cover page - **`excludes_certain_shares`** `object` — Item 12: row 11 excludes certain shares - **`group_member_a`** `object` — Item 2(a): person is part of a Section 13(d) group - **`group_member_b`** `object` — Item 2(b): person is excluded from the group - **`legal_proceedings_required`** `object` — Item 5: legal-proceedings disclosure required for this person - **`names`** `object` — Reporting person name (Item 1 of the cover page) - **`percent_of_class`** `object` — Item 13: percent of class represented by row 11 (whole number, e.g. 5.2) - **`reporting_person_type`** `object` — Cover-page Item 2 type code (e.g., IN individual, OO other, BD broker-dealer) - **`sec_use_only`** `object` — Item 3: SEC use only — typically blank in filings - **`shared_dispositive_power`** `object` — Item 10: shares with shared dispositive power - **`shared_voting_power`** `object` — Item 8: shares with shared voting power - **`sole_dispositive_power`** `object` — Item 9: shares with sole dispositive power - **`sole_voting_power`** `object` — Item 7: shares with sole voting power - **`source_of_funds`** `object` — Item 4 source-of-funds codes (e.g., 'WC' working capital, 'PF' personal funds, 'AF' affiliate funds) - **`rule_basis`** `object` — Filing-rule basis (e.g., '13d-1(a)', '13d-1(b)', '13d-1(c)', '13d-1(d)') - **`schedule_type`** `object` — Normalized schedule variant (see ScheduleType enum) - **`submission_type`** `object` — EDGAR submission type **Example:** ```json { "filing_id": "", "cik": "", "form_type": "", "schedule_type": "", "amendment_no": "", "accepted_time": "", "period_of_report": "", "is_valid": true, "filer_name": "", "filer_tickers": [ "" ], "submission_type": "", "issuer_cusip": "", "issuer_name": "", "issuer_class_title": "", "event_date": "", "rule_basis": "", "reporting_persons": [ { "record_index": 1, "cusip": "", "names": "", "citizenship": "", "reporting_person_type": "", "group_member_a": true, "group_member_b": true, "sec_use_only": "", "source_of_funds": "", "legal_proceedings_required": true, "sole_voting_power": "", "shared_voting_power": "", "sole_dispositive_power": "", "shared_dispositive_power": "", "aggregate_amount": "", "excludes_certain_shares": true, "percent_of_class": "" } ], "exhibits": [ { "record_index": 1, "schedule_type": "", "letter": "", "title": "" } ], "accession_num": "", "source_url": "" } ``` ### BeneficialOwnershipFilingSummary - **Type:**`object` Filing-level summary for one Schedule 13D/G submission. - **`accession_num` (required)** `object` — EDGAR accession number derived from filing\_id (e.g., '0000320193-24-000123') - **`cik` (required)** `string` — Filer SEC Central Index Key - **`filing_id` (required)** `string` — Unique filing identifier - **`form_type` (required)** `string` — SEC form type (e.g., 'SC 13D', 'SC 13G/A') - **`source_url` (required)** `object` — Canonical SEC EDGAR Archives URL pointing at the filing's index page - **`accepted_time`** `object` — When the SEC accepted the filing - **`amendment_no`** `object` — Amendment number if this is an amendment ('/A' filing) - **`event_date`** `object` — Date of the event triggering the filing - **`filer_name`** `object` — Filer entity name - **`filer_tickers`** `object` — Ticker symbols associated with the filer - **`is_valid`** `object` — Whether the filing passed validation - **`issuer_class_title`** `object` — Title of the security class (e.g., 'Common Stock', 'Class A Common') - **`issuer_cusip`** `object` — 9-character CUSIP of the security covered by the filing - **`issuer_name`** `object` — Issuer (target company) legal name - **`period_of_report`** `object` — Reporting period end date - **`rule_basis`** `object` — Filing-rule basis (e.g., '13d-1(a)', '13d-1(b)', '13d-1(c)', '13d-1(d)') - **`schedule_type`** `object` — Normalized schedule variant (see ScheduleType enum) - **`submission_type`** `object` — EDGAR submission type **Example:** ```json { "filing_id": "", "cik": "", "form_type": "", "schedule_type": "", "amendment_no": "", "accepted_time": "", "period_of_report": "", "is_valid": true, "filer_name": "", "filer_tickers": [ "" ], "submission_type": "", "issuer_cusip": "", "issuer_name": "", "issuer_class_title": "", "event_date": "", "rule_basis": "", "accession_num": "", "source_url": "" } ``` ### BeneficialOwnershipListResponse - **Type:**`object` * **`data` (required)** `array` — Page of Schedule 13D/G filing rows **Items:** - **`accession_num` (required)** `object` — EDGAR accession number derived from filing\_id (e.g., '0000320193-24-000123') - **`cik` (required)** `string` — Filer SEC Central Index Key - **`filing_id` (required)** `string` — Unique filing identifier - **`form_type` (required)** `string` — SEC form type (e.g., 'SC 13D', 'SC 13G/A') - **`source_url` (required)** `object` — Canonical SEC EDGAR Archives URL pointing at the filing's index page - **`accepted_time`** `object` — When the SEC accepted the filing - **`amendment_no`** `object` — Amendment number if this is an amendment ('/A' filing) - **`event_date`** `object` — Date of the event triggering the filing - **`filer_name`** `object` — Filer entity name - **`filer_tickers`** `object` — Ticker symbols associated with the filer - **`is_valid`** `object` — Whether the filing passed validation - **`issuer_class_title`** `object` — Title of the security class (e.g., 'Common Stock', 'Class A Common') - **`issuer_cusip`** `object` — 9-character CUSIP of the security covered by the filing - **`issuer_name`** `object` — Issuer (target company) legal name - **`period_of_report`** `object` — Reporting period end date - **`rule_basis`** `object` — Filing-rule basis (e.g., '13d-1(a)', '13d-1(b)', '13d-1(c)', '13d-1(d)') - **`schedule_type`** `object` — Normalized schedule variant (see ScheduleType enum) - **`submission_type`** `object` — EDGAR submission type * **`page_size` (required)** `integer` — Results per page * **`page`** `integer`, default: `1` — Current page number (1-indexed) * **`total`** `integer`, default: `0` — Total count of matching rows * **`total_pages`** `integer`, default: `1` — Total number of pages **Example:** ```json { "total": 0, "page": 1, "page_size": 1, "total_pages": 1, "data": [ { "filing_id": "", "cik": "", "form_type": "", "schedule_type": "", "amendment_no": "", "accepted_time": "", "period_of_report": "", "is_valid": true, "filer_name": "", "filer_tickers": [ "" ], "submission_type": "", "issuer_cusip": "", "issuer_name": "", "issuer_class_title": "", "event_date": "", "rule_basis": "", "accession_num": "", "source_url": "" } ] } ``` ### CapitalFormationBucket - **Type:**`object` One quarterly (and optionally per-industry) bucket of Form D capital-formation activity. - **`filing_count` (required)** `integer` — Form D filings in this bucket - **`is_40_act_count` (required)** `integer` — Filings flagged as Investment Company Act of 1940 funds - **`issuer_count` (required)** `integer` — Distinct issuers (issuer\_cik) in this bucket - **`period_end` (required)** `string`, format: `date` — Quarter end (e.g., '2025-09-30') - **`period_start` (required)** `string`, format: `date` — Quarter start (e.g., '2025-07-01') - **`total_amount_sold` (required)** `string` — Sum of total amount sold to date in this bucket (USD) - **`total_offering_amount` (required)** `string` — Sum of total offering amounts in this bucket (USD) - **`avg_offering_size`** `object` — Mean offering amount (total\_offering\_amount / filing\_count) - **`industry_group_type`** `object` — Industry bucket; null when include\_industry\_breakdown=false **Example:** ```json { "period_start": "", "period_end": "", "industry_group_type": "", "filing_count": 1, "issuer_count": 1, "total_offering_amount": "", "total_amount_sold": "", "avg_offering_size": "", "is_40_act_count": 1 } ``` ### ChangesResponse - **Type:**`object` * **`data` (required)** `array` — Change events sorted by accepted\_time ascending (oldest first). **Items:** - **`accepted_time` (required)** `string`, format: `date-time` — When the SEC accepted the filing (the changefeed cursor). - **`action` (required)** `string`, possible values: `"created", "amended"` — \`amended\` when the filing is an amendment of an earlier filing in the same family; \`created\` otherwise. - **`family` (required)** `object` — Family this change belongs to. - **`filing_id` (required)** `string` — Filing identifier. - **`cik`** `object` — Filer CIK on the filing (canonical short form). - **`form_type`** `object` — SEC form type. * **`family` (required)** `object` — Family the changefeed is scoped to. * **`page_size` (required)** `integer` — Results per page * **`page`** `integer`, default: `1` — Current page number (1-indexed) * **`total`** `integer`, default: `0` — Total count of matching rows * **`total_pages`** `integer`, default: `1` — Total number of pages **Example:** ```json { "total": 0, "page": 1, "page_size": 1, "total_pages": 1, "family": "insiders", "data": [ { "family": null, "filing_id": "", "cik": "", "form_type": "", "accepted_time": "", "action": "created" } ] } ``` ### ClassFlowsTimeseriesResponse - **Type:**`object` * **`data` (required)** `array` — Page of class subscriptions/redemptions time-series points **Items:** - **`class_index` (required)** `integer` — record\_index of the parent share class in the same filing's classes\[] list - **`filing_id` (required)** `string` — Filing this point came from - **`record_index` (required)** `integer` — Per-filing 0-based ordinal of this point - **`class_full_name`** `object` — Share class display name - **`classes_id`** `object` — SEC share-class identifier - **`date`** `object` — Date of this flow observation - **`granularity`** `object` — 'monthly' or 'daily' - **`gross_redemptions`** `object` — Gross redemptions on this date (USD) - **`gross_subscriptions`** `object` — Gross subscriptions on this date (USD) - **`series_id`** `object` — SEC fund series identifier - **`series_name`** `object` — Fund series display name * **`page_size` (required)** `integer` — Results per page * **`page`** `integer`, default: `1` — Current page number (1-indexed) * **`total`** `integer`, default: `0` — Total count of matching rows * **`total_pages`** `integer`, default: `1` — Total number of pages **Example:** ```json { "total": 0, "page": 1, "page_size": 1, "total_pages": 1, "data": [ { "filing_id": "", "class_index": 1, "record_index": 1, "series_id": "", "series_name": "", "classes_id": "", "class_full_name": "", "date": "", "gross_subscriptions": "", "gross_redemptions": "", "granularity": "" } ] } ``` ### ClassFlowsTimeseriesRow - **Type:**`object` One class-level flows time-series point — one date's gross subscriptions and redemptions for a single share class. - **`class_index` (required)** `integer` — record\_index of the parent share class in the same filing's classes\[] list - **`filing_id` (required)** `string` — Filing this point came from - **`record_index` (required)** `integer` — Per-filing 0-based ordinal of this point - **`class_full_name`** `object` — Share class display name - **`classes_id`** `object` — SEC share-class identifier - **`date`** `object` — Date of this flow observation - **`granularity`** `object` — 'monthly' or 'daily' - **`gross_redemptions`** `object` — Gross redemptions on this date (USD) - **`gross_subscriptions`** `object` — Gross subscriptions on this date (USD) - **`series_id`** `object` — SEC fund series identifier - **`series_name`** `object` — Fund series display name **Example:** ```json { "filing_id": "", "class_index": 1, "record_index": 1, "series_id": "", "series_name": "", "classes_id": "", "class_full_name": "", "date": "", "gross_subscriptions": "", "gross_redemptions": "", "granularity": "" } ``` ### ClassNavTimeseriesResponse - **Type:**`object` * **`data` (required)** `array` — Page of class-NAV time-series points **Items:** - **`class_index` (required)** `integer` — record\_index of the parent share class in the same filing's classes\[] list - **`filing_id` (required)** `string` — Filing this point came from - **`record_index` (required)** `integer` — Per-filing 0-based ordinal of this point - **`class_full_name`** `object` — Share class display name - **`classes_id`** `object` — SEC share-class identifier - **`date`** `object` — Date of this NAV observation - **`granularity`** `object` — 'monthly' or 'daily' - **`series_id`** `object` — SEC fund series identifier - **`series_name`** `object` — Fund series display name - **`value`** `object` — Class-level NAV value at this date (USD) * **`page_size` (required)** `integer` — Results per page * **`page`** `integer`, default: `1` — Current page number (1-indexed) * **`total`** `integer`, default: `0` — Total count of matching rows * **`total_pages`** `integer`, default: `1` — Total number of pages **Example:** ```json { "total": 0, "page": 1, "page_size": 1, "total_pages": 1, "data": [ { "filing_id": "", "class_index": 1, "record_index": 1, "series_id": "", "series_name": "", "classes_id": "", "class_full_name": "", "date": "", "value": "", "granularity": "" } ] } ``` ### ClassNavTimeseriesRow - **Type:**`object` One class-level NAV time-series point — one date's NAV value for a single share class of a fund series. - **`class_index` (required)** `integer` — record\_index of the parent share class in the same filing's classes\[] list - **`filing_id` (required)** `string` — Filing this point came from - **`record_index` (required)** `integer` — Per-filing 0-based ordinal of this point - **`class_full_name`** `object` — Share class display name - **`classes_id`** `object` — SEC share-class identifier - **`date`** `object` — Date of this NAV observation - **`granularity`** `object` — 'monthly' or 'daily' - **`series_id`** `object` — SEC fund series identifier - **`series_name`** `object` — Fund series display name - **`value`** `object` — Class-level NAV value at this date (USD) **Example:** ```json { "filing_id": "", "class_index": 1, "record_index": 1, "series_id": "", "series_name": "", "classes_id": "", "class_full_name": "", "date": "", "value": "", "granularity": "" } ``` ### ConvictionComponents - **Type:**`object` Three components that combine into the composite conviction score. - **`breadth` (required)** `number` — Distinct contributing insiders, sigmoid-normalized to \[0, 1] - **`dollar_imbalance` (required)** `number` — (acquired\_dollars − disposed\_dollars) / total\_dollars, range \[-1, 1] - **`seniority_weight` (required)** `number` — Mean seniority of contributing insiders (CEO/Director/etc.), range \[0, 1] **Example:** ```json { "dollar_imbalance": 1, "breadth": 1, "seniority_weight": 1 } ``` ### ConvictionXCrowdingResponse - **Type:**`object` * **`as_of` (required)** `string`, format: `date` — Anchor date used for the conviction window. * **`data` (required)** `array` — Issuers satisfying both \`direction='bullish'\` insider conviction AND \`pct\_of\_filers <= max\_pct\_of\_filers\`. Sorted by \`insider\_conviction\_score\` descending. **Items:** - **`distinct_insiders` (required)** `integer` — Distinct insiders contributing to the conviction signal. - **`insider_conviction_score` (required)** `number` — Insider conviction score (bullish-direction; higher = stronger). - **`crowding_aggregate_value`** `object` — Total reported 13F value across all holders (thousands of USD); null when no 13F match. - **`crowding_n_holders`** `object` — Distinct 13F managers holding this CUSIP at the comparison period; null when no 13F match. - **`crowding_pct_of_filers`** `object` — n\_holders / total\_filers\_in\_period, range \[0, 1]; null when no 13F match. - **`cusip`** `object` — Resolved CUSIP via name match; null when no 13F match was found. - **`issuer_cik`** `object` — Issuer CIK (canonical short form, no leading zeros). - **`issuer_name`** `object` — Modal issuer name across the matched 13F holdings rows. - **`issuer_trading_symbol`** `object` — Issuer ticker symbol from Form 4. * **`max_pct_of_filers` (required)** `number` — Maximum \`pct\_of\_filers\` to qualify as 'low crowding'. Default 0.10 — only issuers held by ≤10% of 13F filers qualify. * **`window_days` (required)** `integer` — Insider-conviction trailing window in days. * **`crowding_period`** `object` — 13F period\_of\_report used for the crowding lookup. **Example:** ```json { "as_of": "", "window_days": 1, "crowding_period": "", "max_pct_of_filers": 1, "data": [ { "issuer_cik": "", "issuer_trading_symbol": "", "issuer_name": "", "cusip": "", "insider_conviction_score": 1, "distinct_insiders": 1, "crowding_n_holders": 1, "crowding_pct_of_filers": 1, "crowding_aggregate_value": "" } ] } ``` ### ConvictionXCrowdingRow - **Type:**`object` One issuer that satisfies both conditions. - **`distinct_insiders` (required)** `integer` — Distinct insiders contributing to the conviction signal. - **`insider_conviction_score` (required)** `number` — Insider conviction score (bullish-direction; higher = stronger). - **`crowding_aggregate_value`** `object` — Total reported 13F value across all holders (thousands of USD); null when no 13F match. - **`crowding_n_holders`** `object` — Distinct 13F managers holding this CUSIP at the comparison period; null when no 13F match. - **`crowding_pct_of_filers`** `object` — n\_holders / total\_filers\_in\_period, range \[0, 1]; null when no 13F match. - **`cusip`** `object` — Resolved CUSIP via name match; null when no 13F match was found. - **`issuer_cik`** `object` — Issuer CIK (canonical short form, no leading zeros). - **`issuer_name`** `object` — Modal issuer name across the matched 13F holdings rows. - **`issuer_trading_symbol`** `object` — Issuer ticker symbol from Form 4. **Example:** ```json { "issuer_cik": "", "issuer_trading_symbol": "", "issuer_name": "", "cusip": "", "insider_conviction_score": 1, "distinct_insiders": 1, "crowding_n_holders": 1, "crowding_pct_of_filers": 1, "crowding_aggregate_value": "" } ``` ### CoordinatedFilerPair - **Type:**`object` Two reporting persons who appear together on multiple Schedule 13D/G filings. - **`co_filing_count` (required)** `integer` — Number of distinct Schedule 13D/G filings where both persons appear. - **`distinct_issuer_names` (required)** `array` — Up to 10 issuer names this pair has co-filed against. **Items:** `string` - **`distinct_issuers` (required)** `integer` — Number of distinct issuer CUSIPs the pair has co-filed against. - **`person_a_name` (required)** `string` — Reporting person A's name (lexicographically first member of the pair). - **`person_b_name` (required)** `string` — Reporting person B's name (lexicographically second member of the pair). - **`last_filing_accepted`** `object` — Most recent accepted\_time across the pair's co-filings. **Example:** ```json { "person_a_name": "", "person_b_name": "", "co_filing_count": 1, "distinct_issuers": 1, "distinct_issuer_names": [ "" ], "last_filing_accepted": "" } ``` ### CoordinatedFilersResponse - **Type:**`object` * **`min_co_filings` (required)** `integer` — Minimum co-filing threshold applied (default 2 — pairs with a single shared filing are excluded). * **`pairs` (required)** `array` — Recurring co-filer pairs ranked by co\_filing\_count descending. **Items:** - **`co_filing_count` (required)** `integer` — Number of distinct Schedule 13D/G filings where both persons appear. - **`distinct_issuer_names` (required)** `array` — Up to 10 issuer names this pair has co-filed against. **Items:** `string` - **`distinct_issuers` (required)** `integer` — Number of distinct issuer CUSIPs the pair has co-filed against. - **`person_a_name` (required)** `string` — Reporting person A's name (lexicographically first member of the pair). - **`person_b_name` (required)** `string` — Reporting person B's name (lexicographically second member of the pair). - **`last_filing_accepted`** `object` — Most recent accepted\_time across the pair's co-filings. * **`since`** `object` — Window start (inclusive) applied to filings.accepted\_time, when supplied. **Example:** ```json { "since": "", "min_co_filings": 1, "pairs": [ { "person_a_name": "", "person_b_name": "", "co_filing_count": 1, "distinct_issuers": 1, "distinct_issuer_names": [ "" ], "last_filing_accepted": "" } ] } ``` ### CoordinatedGroup - **Type:**`object` One coordinated-filing event — a Schedule 13D/G filing with two or more reporting persons flagged as members of a group. - **`filing_id` (required)** `string` — Source SC13 filing identifier - **`member_count` (required)** `integer` — Number of flagged group members on this filing - **`members` (required)** `array` — Flagged group-member rows **Items:** - **`record_index` (required)** `integer` — Per-filing 0-based ordinal of this person row - **`aggregate_amount`** `object` — Aggregate beneficial ownership reported (Item 11) - **`cik`** `object` — Reporting person CIK (where assigned) - **`citizenship`** `object` — Citizenship or place of organization (Item 6) - **`group_member_a`** `object` — Item 2(a): person is a member of a Section 13(d) group - **`group_member_b`** `object` — Item 2(b): person is excluded from the group - **`names`** `object` — Reporting person name (Item 1 on the cover page) - **`percent_of_class`** `object` — Percent of class reported (Item 13) - **`reporting_person_type`** `object` — Cover-page Item 2 type code (e.g., IN, OO, BD) - **`shared_voting_power`** `object` — Shared voting power (Item 8) - **`sole_voting_power`** `object` — Sole voting power (Item 7) - **`accepted_time`** `object` — When the SEC accepted the filing - **`aggregate_amount`** `object` — Sum of \`aggregate\_amount\` across all flagged group members - **`aggregate_percent_of_class`** `object` — Sum of \`percent\_of\_class\` across all flagged group members on this filing - **`amendment_no`** `object` — Amendment number for amendment filings - **`event_date`** `object` — Triggering event date for this filing - **`is_likely_double_counted`** `boolean`, default: `false` — True when \`aggregate\_percent\_of\_class > 100\` — a strong signal that the same shares are being reported by multiple members of the group (legitimate under SC 13 rules but should not be displayed as a literal ownership stake). - **`issuer_cusip`** `object` — Issuer CUSIP from the filing - **`issuer_name`** `object` — Issuer (target company) legal name - **`schedule_type`** `object` — Schedule variant (SC 13D / 13D/A / 13G / 13G/A) **Example:** ```json { "filing_id": "", "schedule_type": "", "issuer_cusip": "", "issuer_name": "", "event_date": "", "accepted_time": "", "amendment_no": "", "member_count": 1, "aggregate_percent_of_class": "", "aggregate_amount": "", "is_likely_double_counted": false, "members": [ { "record_index": 1, "cik": "", "names": "", "aggregate_amount": "", "percent_of_class": "", "sole_voting_power": "", "shared_voting_power": "", "citizenship": "", "reporting_person_type": "", "group_member_a": true, "group_member_b": true } ] } ``` ### CoordinatedGroupsListResponse - **Type:**`object` * **`data` (required)** `array` — Page of coordinated-filing groups **Items:** - **`filing_id` (required)** `string` — Source SC13 filing identifier - **`member_count` (required)** `integer` — Number of flagged group members on this filing - **`members` (required)** `array` — Flagged group-member rows **Items:** - **`record_index` (required)** `integer` — Per-filing 0-based ordinal of this person row - **`aggregate_amount`** `object` — Aggregate beneficial ownership reported (Item 11) - **`cik`** `object` — Reporting person CIK (where assigned) - **`citizenship`** `object` — Citizenship or place of organization (Item 6) - **`group_member_a`** `object` — Item 2(a): person is a member of a Section 13(d) group - **`group_member_b`** `object` — Item 2(b): person is excluded from the group - **`names`** `object` — Reporting person name (Item 1 on the cover page) - **`percent_of_class`** `object` — Percent of class reported (Item 13) - **`reporting_person_type`** `object` — Cover-page Item 2 type code (e.g., IN, OO, BD) - **`shared_voting_power`** `object` — Shared voting power (Item 8) - **`sole_voting_power`** `object` — Sole voting power (Item 7) - **`accepted_time`** `object` — When the SEC accepted the filing - **`aggregate_amount`** `object` — Sum of \`aggregate\_amount\` across all flagged group members - **`aggregate_percent_of_class`** `object` — Sum of \`percent\_of\_class\` across all flagged group members on this filing - **`amendment_no`** `object` — Amendment number for amendment filings - **`event_date`** `object` — Triggering event date for this filing - **`is_likely_double_counted`** `boolean`, default: `false` — True when \`aggregate\_percent\_of\_class > 100\` — a strong signal that the same shares are being reported by multiple members of the group (legitimate under SC 13 rules but should not be displayed as a literal ownership stake). - **`issuer_cusip`** `object` — Issuer CUSIP from the filing - **`issuer_name`** `object` — Issuer (target company) legal name - **`schedule_type`** `object` — Schedule variant (SC 13D / 13D/A / 13G / 13G/A) * **`page_size` (required)** `integer` — Results per page * **`page`** `integer`, default: `1` — Current page number (1-indexed) * **`total`** `integer`, default: `0` — Total count of matching rows * **`total_pages`** `integer`, default: `1` — Total number of pages **Example:** ```json { "total": 0, "page": 1, "page_size": 1, "total_pages": 1, "data": [ { "filing_id": "", "schedule_type": "", "issuer_cusip": "", "issuer_name": "", "event_date": "", "accepted_time": "", "amendment_no": "", "member_count": 1, "aggregate_percent_of_class": "", "aggregate_amount": "", "is_likely_double_counted": false, "members": [] } ] } ``` ### CrowdingMetrics - **Type:**`object` 13F crowding metrics for one security at one period. - **`aggregate_shares` (required)** `string` — Total reported shares across all holders - **`aggregate_value` (required)** `string` — Total reported value across all holders (in thousands of USD per Form 13F convention) - **`cusip` (required)** `string` — Security CUSIP - **`n_holders` (required)** `integer` — Distinct managers reporting this position at the period end - **`pct_of_filers` (required)** `number` — n\_holders / total\_filers\_in\_period, range \[0, 1] - **`period_of_report` (required)** `string`, format: `date` — 13F period analyzed - **`top_10_share_pct` (required)** `number` — Share of aggregate\_value held by the top-10 managers (concentration proxy) - **`total_filers_in_period` (required)** `integer` — Distinct managers with any 13F holding in this period (denominator) - **`hhi`** `object` — Herfindahl-Hirschman Index over manager value shares, scaled to the standard \[0, 10000] range (sum of squared percentage shares). Higher = more concentrated holder base. Null when aggregate\_value is zero. - **`name_of_issuer`** `object` — Issuer name resolved from holdings - **`qoq_holders_delta`** `object` — Change in n\_holders vs prior calendar quarter; null if no prior-period data available **Example:** ```json { "aggregate_shares": "3187420800", "aggregate_value": "548320500", "cusip": "037833100", "n_holders": 4218, "name_of_issuer": "APPLE INC", "pct_of_filers": 0.748, "period_of_report": "2024-03-31", "qoq_holders_delta": 47, "top_10_share_pct": 0.31, "total_filers_in_period": 5640 } ``` ### DataAsOf - **Type:**`object` Latest reporting period present in the database for each major filing family. Use this to detect ETL staleness — querying a period after the value listed here will return zero rows, not a 4xx. Per family we expose two values: `*_latest_accepted` (the most recent `accepted_time` the SEC accepted into the family's view) and `*_latest_period` (the most recent `period_of_report` / `event_date` covered). Both are ISO-8601 dates, or null when the family has no rows yet (DATA-1 from the round-3 audit). - **`form_13f_latest_accepted`** `object` — Latest accepted\_time in vw\_api\_data\_form13f\_filings (institutional holdings). - **`form_13f_latest_period`** `object` — Latest period\_of\_report in vw\_api\_data\_form13f\_filings. - **`form_144_latest_accepted`** `object` — Latest accepted\_time in vw\_api\_data\_form144\_filings (proposed sales). - **`form_144_latest_period`** `object` — Latest period\_of\_report in vw\_api\_data\_form144\_filings. - **`form_1a_latest_accepted`** `object` — Latest accepted\_time in vw\_api\_data\_form1a\_filings (Reg A+ offerings). - **`form_1a_latest_period`** `object` — Latest period\_of\_report in vw\_api\_data\_form1a\_filings. - **`form_4_latest_accepted`** `object` — Latest accepted\_time in vw\_api\_data\_form345\_filings (insider Forms 3/4/5). - **`form_4_latest_period`** `object` — Latest period\_of\_report in vw\_api\_data\_form345\_filings. - **`form_d_latest_accepted`** `object` — Latest accepted\_time in vw\_api\_data\_formd\_filings (private offerings). - **`form_d_latest_period`** `object` — Latest period\_of\_report in vw\_api\_data\_formd\_filings. - **`n_cen_latest_accepted`** `object` — Latest accepted\_time in vw\_api\_data\_ncen\_filings (fund census). - **`n_cen_latest_period`** `object` — Latest period\_of\_report in vw\_api\_data\_ncen\_filings. - **`n_mfp_latest_accepted`** `object` — Latest accepted\_time in vw\_api\_data\_nmfp\_filings (money-market funds). - **`n_mfp_latest_period`** `object` — Latest period\_of\_report in vw\_api\_data\_nmfp\_filings. - **`n_port_latest_accepted`** `object` — Latest accepted\_time in vw\_api\_data\_nport\_filings (fund portfolios). - **`n_port_latest_period`** `object` — Latest period\_of\_report in vw\_api\_data\_nport\_filings. - **`n_px_latest_accepted`** `object` — Latest accepted\_time in vw\_api\_data\_npx\_filings (proxy votes). - **`n_px_latest_period`** `object` — Latest period\_of\_report in vw\_api\_data\_npx\_filings. - **`sc13_latest_accepted`** `object` — Latest accepted\_time in vw\_api\_data\_sc13\_filings (beneficial ownership). - **`sc13_latest_event`** `object` — Latest event\_date in vw\_api\_data\_sc13\_filings. **Example:** ```json { "form_4_latest_accepted": "", "form_13f_latest_accepted": "", "form_d_latest_accepted": "", "form_144_latest_accepted": "", "form_1a_latest_accepted": "", "n_port_latest_accepted": "", "n_mfp_latest_accepted": "", "n_cen_latest_accepted": "", "n_px_latest_accepted": "", "sc13_latest_accepted": "", "form_4_latest_period": "", "form_13f_latest_period": "", "form_d_latest_period": "", "form_144_latest_period": "", "form_1a_latest_period": "", "n_port_latest_period": "", "n_mfp_latest_period": "", "n_cen_latest_period": "", "n_px_latest_period": "", "sc13_latest_event": "" } ``` ### DataAsOfResponse - **Type:**`object` * **`families` (required)** `object` — Freshness summary keyed by filing family. **Example:** ```json { "families": { "fund_portfolios": { "accepted_time_max": "2024-03-30T18:00:00", "filing_count": 12500, "period_of_report_max": "2024-02-29" }, "insiders": { "accepted_time_max": "2024-03-15T20:14:00", "filing_count": 71800, "period_of_report_max": "2024-03-15" } } } ``` ### DerivHoldingResponse - **Type:**`object` One derivative holding row — options, warrants, RSUs, convertible notes, or other instruments tied to the issuer's stock. - **`record_index` (required)** `integer` — Per-filing 0-based ordinal of this derivative-holding row - **`conversion_or_exercise_price`** `object` — Strike / conversion price per share - **`direct_or_indirect_ownership`** `object` — 'D' = direct ownership, 'I' = indirect - **`exercise_date`** `object` — Earliest date the derivative becomes exercisable - **`expiration_date`** `object` — Date the derivative expires - **`nature_of_ownership`** `object` — Free-text describing indirect ownership - **`security_title`** `object` — Derivative title (e.g., 'Stock Option (Right to Buy)', 'RSU') - **`shares_owned_following_transaction`** `object` — Derivative-instrument count owned after the most recent transaction - **`underlying_security_shares`** `object` — Number of underlying shares the derivative covers - **`underlying_security_title`** `object` — Underlying security title (typically 'Common Stock') - **`underlying_security_value`** `object` — USD value of the underlying shares - **`value_owned_following_transaction`** `object` — USD value of derivatives owned after the most recent transaction **Example:** ```json { "record_index": 1, "security_title": "", "conversion_or_exercise_price": "", "exercise_date": "", "expiration_date": "", "underlying_security_title": "", "underlying_security_shares": "", "underlying_security_value": "", "shares_owned_following_transaction": "", "value_owned_following_transaction": "", "direct_or_indirect_ownership": "", "nature_of_ownership": "" } ``` ### DerivTransactionResponse - **Type:**`object` One derivative transaction row — option exercise, RSU vesting, grant, or other transaction in a derivative security. - **`record_index` (required)** `integer` — Per-filing 0-based ordinal of this derivative-transaction row - **`conversion_or_exercise_price`** `object` — Strike / conversion price per share - **`direct_or_indirect_ownership`** `object` — 'D' = direct ownership, 'I' = indirect - **`exercise_date`** `object` — Earliest date the derivative becomes exercisable - **`expiration_date`** `object` — Date the derivative expires - **`security_title`** `object` — Derivative title - **`shares_owned_following_transaction`** `object` — Total derivative instruments owned after this transaction - **`transaction_acquired_disposed_code`** `object` — 'A' = acquired, 'D' = disposed - **`transaction_code`** `object` — Single-letter transaction code (see NonderivTransactionResponse) - **`transaction_date`** `object` — Date the transaction occurred - **`transaction_price_per_share`** `object` — Price per derivative instrument - **`transaction_shares`** `object` — Number of derivative instruments involved - **`transaction_total_value`** `object` — Total USD value of the transaction - **`underlying_security_shares`** `object` — Number of underlying shares the derivative covers - **`underlying_security_title`** `object` — Underlying security title (typically 'Common Stock') - **`underlying_security_value`** `object` — USD value of the underlying shares **Example:** ```json { "record_index": 1, "security_title": "", "conversion_or_exercise_price": "", "transaction_date": "", "transaction_code": "", "transaction_acquired_disposed_code": "", "transaction_shares": "", "transaction_total_value": "", "transaction_price_per_share": "", "exercise_date": "", "expiration_date": "", "underlying_security_title": "", "underlying_security_shares": "", "underlying_security_value": "", "shares_owned_following_transaction": "", "direct_or_indirect_ownership": "" } ``` ### DirectorInterlockBoard - **Type:**`object` One issuer the insider has filed Form 3/4/5 against. - **`cik` (required)** `string` — Issuer CIK (canonical short form, no leading zeros). - **`filing_count` (required)** `integer` — Form 3/4/5 filings this insider has made naming this issuer. - **`company_name`** `object` — Modal issuer name across the insider's filings. - **`is_director`** `object` — Whether the insider was flagged as a director on any of their filings for this issuer. - **`is_officer`** `object` — Whether the insider was flagged as an officer on any of their filings for this issuer. - **`is_ten_percent_owner`** `object` — Whether the insider was flagged as a 10%+ owner on any of their filings for this issuer. - **`period_max`** `object` — Latest period\_of\_report observed for this insider's filings on this issuer. - **`period_min`** `object` — Earliest period\_of\_report observed for this insider's filings on this issuer. - **`ticker`** `object` — Issuer ticker symbol when known (modal across the insider's filings). **Example:** ```json { "cik": "", "company_name": "", "ticker": "", "filing_count": 1, "is_director": true, "is_officer": true, "is_ten_percent_owner": true, "period_min": "", "period_max": "" } ``` ### DirectorInterlocksResponse - **Type:**`object` * **`boards` (required)** `array` — Distinct issuers this insider has filed Form 3/4/5 against, sorted by filing\_count descending. **Items:** - **`cik` (required)** `string` — Issuer CIK (canonical short form, no leading zeros). - **`filing_count` (required)** `integer` — Form 3/4/5 filings this insider has made naming this issuer. - **`company_name`** `object` — Modal issuer name across the insider's filings. - **`is_director`** `object` — Whether the insider was flagged as a director on any of their filings for this issuer. - **`is_officer`** `object` — Whether the insider was flagged as an officer on any of their filings for this issuer. - **`is_ten_percent_owner`** `object` — Whether the insider was flagged as a 10%+ owner on any of their filings for this issuer. - **`period_max`** `object` — Latest period\_of\_report observed for this insider's filings on this issuer. - **`period_min`** `object` — Earliest period\_of\_report observed for this insider's filings on this issuer. - **`ticker`** `object` — Issuer ticker symbol when known (modal across the insider's filings). * **`rpt_owner_cik` (required)** `string` — Reporting-owner CIK queried (canonical short form). * **`insider_name`** `object` — Modal insider name across their filings. **Example:** ```json { "rpt_owner_cik": "", "insider_name": "", "boards": [ { "cik": "", "company_name": "", "ticker": "", "filing_count": 1, "is_director": true, "is_officer": true, "is_ten_percent_owner": true, "period_min": "", "period_max": "" } ] } ``` ### EntitiesListResponse - **Type:**`object` Paginated list of registry entities. Used by both `/api/v1/people` and `/api/v1/companies`. The profile rows omit the `links` block (kept lean for list shapes; callers hit the per-CIK endpoint for the deep profile). - **`data` (required)** `array` — Registry entries matching the search / filters. **Items:** - **`cik` (required)** `string` — SEC Central Index Key, canonical short form (no leading zeros). - **`category`** `object` — Categorization tags (filer category, fund type, etc.). - **`description`** `object` — Free-text entity description. - **`ein`** `object` — IRS Employer Identification Number. - **`entity_type`** `object` — Entity type: \`operating\`, \`investment\`, or \`other\`. - **`exchanges`** `object` — Exchanges the entity trades on (e.g., \`NYSE\`, \`Nasdaq\`). - **`filer_status_flags`** `object` — Filer status flags (e.g., \`Large Accelerated\`, \`Well Known Seasoned Issuer\`, \`Emerging Growth Company\`). - **`fiscal_year_end`** `object` — Fiscal year end as \`MMDD\` (e.g., \`0930\` for Sep 30). - **`is_human`** `object` — Tri-state classification: \`true\` = confirmed human, \`false\` = confirmed company, \`null\` = not yet classified by the metadata pass. - **`lei`** `object` — Legal Entity Identifier (20-char ISO 17442). - **`name`** `object` — Entity legal name. - **`owner_org`** `object` — Owning organization name (when the entity is a subsidiary). - **`sic`** `object` — 4-digit Standard Industrial Classification code. - **`sic_description`** `object` — Plain-text SIC name. - **`state_of_incorp`** `object` — 2-letter state code or country code of incorporation. - **`tickers`** `object` — Ticker symbols associated with the entity. - **`page_size` (required)** `integer` — Results per page - **`page`** `integer`, default: `1` — Current page number (1-indexed) - **`total`** `integer`, default: `0` — Total count of matching rows - **`total_pages`** `integer`, default: `1` — Total number of pages **Example:** ```json { "total": 0, "page": 1, "page_size": 1, "total_pages": 1, "data": [ { "cik": "", "name": "", "is_human": true, "entity_type": "", "sic": "", "sic_description": "", "tickers": [ "" ], "exchanges": [ "" ], "ein": "", "lei": "", "description": "", "category": null, "fiscal_year_end": "", "state_of_incorp": "", "owner_org": "", "filer_status_flags": [ "" ] } ] } ``` ### EntityProfile - **Type:**`object` Registry metadata for one entity (human or company). Coverage note: every metadata field below is Optional. The bulk of the registry rows currently have only `cik` and `name` populated — the rich metadata (SIC, exchanges, EIN, LEI, etc.) fills in as the upstream metadata pass backfills the rows. Use `is_human IS NOT NULL` as a proxy for "this row has been classified by the metadata pass" today. - **`cik` (required)** `string` — SEC Central Index Key, canonical short form (no leading zeros). - **`category`** `object` — Categorization tags (filer category, fund type, etc.). - **`description`** `object` — Free-text entity description. - **`ein`** `object` — IRS Employer Identification Number. - **`entity_type`** `object` — Entity type: \`operating\`, \`investment\`, or \`other\`. - **`exchanges`** `object` — Exchanges the entity trades on (e.g., \`NYSE\`, \`Nasdaq\`). - **`filer_status_flags`** `object` — Filer status flags (e.g., \`Large Accelerated\`, \`Well Known Seasoned Issuer\`, \`Emerging Growth Company\`). - **`fiscal_year_end`** `object` — Fiscal year end as \`MMDD\` (e.g., \`0930\` for Sep 30). - **`is_human`** `object` — Tri-state classification: \`true\` = confirmed human, \`false\` = confirmed company, \`null\` = not yet classified by the metadata pass. - **`lei`** `object` — Legal Entity Identifier (20-char ISO 17442). - **`name`** `object` — Entity legal name. - **`owner_org`** `object` — Owning organization name (when the entity is a subsidiary). - **`sic`** `object` — 4-digit Standard Industrial Classification code. - **`sic_description`** `object` — Plain-text SIC name. - **`state_of_incorp`** `object` — 2-letter state code or country code of incorporation. - **`tickers`** `object` — Ticker symbols associated with the entity. **Example:** ```json { "cik": "", "name": "", "is_human": true, "entity_type": "", "sic": "", "sic_description": "", "tickers": [ "" ], "exchanges": [ "" ], "ein": "", "lei": "", "description": "", "category": null, "fiscal_year_end": "", "state_of_incorp": "", "owner_org": "", "filer_status_flags": [ "" ] } ``` ### EntityProfileWithLinks - **Type:**`object` Single-CIK profile with outbound link map. Returned by `/api/v1/entities/{cik}` so callers can pivot from the registry profile straight into the family-specific endpoints without rebuilding query strings. - **`cik` (required)** `string` — SEC Central Index Key, canonical short form (no leading zeros). - **`links` (required)** `object` — Outbound links into family-specific endpoints, keyed by the kind of follow-up query they support. Always present (every CIK in the registry can in principle file in any family). The \`form4\_as\_filer\` link is the high-value hop for confirmed humans — both companies and humans can appear as Form 4 reporting owners. - **`category`** `object` — Categorization tags (filer category, fund type, etc.). - **`description`** `object` — Free-text entity description. - **`ein`** `object` — IRS Employer Identification Number. - **`entity_type`** `object` — Entity type: \`operating\`, \`investment\`, or \`other\`. - **`exchanges`** `object` — Exchanges the entity trades on (e.g., \`NYSE\`, \`Nasdaq\`). - **`filer_status_flags`** `object` — Filer status flags (e.g., \`Large Accelerated\`, \`Well Known Seasoned Issuer\`, \`Emerging Growth Company\`). - **`fiscal_year_end`** `object` — Fiscal year end as \`MMDD\` (e.g., \`0930\` for Sep 30). - **`is_human`** `object` — Tri-state classification: \`true\` = confirmed human, \`false\` = confirmed company, \`null\` = not yet classified by the metadata pass. - **`lei`** `object` — Legal Entity Identifier (20-char ISO 17442). - **`name`** `object` — Entity legal name. - **`owner_org`** `object` — Owning organization name (when the entity is a subsidiary). - **`sic`** `object` — 4-digit Standard Industrial Classification code. - **`sic_description`** `object` — Plain-text SIC name. - **`state_of_incorp`** `object` — 2-letter state code or country code of incorporation. - **`tickers`** `object` — Ticker symbols associated with the entity. **Example:** ```json { "cik": "", "name": "", "is_human": true, "entity_type": "", "sic": "", "sic_description": "", "tickers": [ "" ], "exchanges": [ "" ], "ein": "", "lei": "", "description": "", "category": null, "fiscal_year_end": "", "state_of_incorp": "", "owner_org": "", "filer_status_flags": [ "" ], "links": { "additionalProperty": "" } } ``` ### FamilyAsOf - **Type:**`object` Per-family freshness summary. - **`accepted_time_max`** `object` — Latest accepted\_time observed for this family (UTC). - **`filing_count`** `integer`, default: `0` — Total filings on file for this family. - **`period_of_report_max`** `object` — Latest period\_of\_report observed for this family. **Example:** ```json { "accepted_time_max": "", "period_of_report_max": "", "filing_count": 0 } ``` ### FamilyChangeRow - **Type:**`object` One change event for the family changefeed. - **`accepted_time` (required)** `string`, format: `date-time` — When the SEC accepted the filing (the changefeed cursor). - **`action` (required)** `string`, possible values: `"created", "amended"` — \`amended\` when the filing is an amendment of an earlier filing in the same family; \`created\` otherwise. - **`family` (required)** `object` — Family this change belongs to. - **`filing_id` (required)** `string` — Filing identifier. - **`cik`** `object` — Filer CIK on the filing (canonical short form). - **`form_type`** `object` — SEC form type. **Example:** ```json { "family": "insiders", "filing_id": "", "cik": "", "form_type": "", "accepted_time": "", "action": "created" } ``` ### FamilyCoverageResponse - **Type:**`object` * **`families` (required)** `object` — Coverage summary keyed by filing family. **Example:** ```json { "families": { "additionalProperty": { "distinct_cik_count": 0, "filing_count": 0, "period_min": "", "period_max": "", "accepted_time_min": "", "accepted_time_max": "" } } } ``` ### FamilyCoverageStats - **Type:**`object` Per-family aggregate used in /coverage/by-family responses. - **`accepted_time_max`** `object` — Latest accepted\_time observed for this family (UTC). - **`accepted_time_min`** `object` — Earliest accepted\_time observed for this family (UTC). - **`distinct_cik_count`** `integer`, default: `0` — Number of distinct filer CIKs with at least one filing in this family. - **`filing_count`** `integer`, default: `0` — Total filings on file for this family. - **`period_max`** `object` — Latest period\_of\_report observed for this family. - **`period_min`** `object` — Earliest period\_of\_report observed for this family. **Example:** ```json { "distinct_cik_count": 0, "filing_count": 0, "period_min": "", "period_max": "", "accepted_time_min": "", "accepted_time_max": "" } ``` ### FilingFamily - **Type:**`string` Filing families surfaced by /api/v1/{family} resources. The eleven values below correspond 1:1 with the per-family routers registered in `app/api/v1/router.py`. Coverage / intake / data-as-of aggregate across exactly this set, so adding a new family means registering its view in `app/services/api_coverage_service.py:FAMILY_VIEWS` and extending this enum in lockstep. **Example:** ### FilingManagerResponse - **Type:**`object` One row from the distinct-filing-managers index. - **`filing_count` (required)** `integer` — Total 13F filings this manager has submitted - **`filing_manager_cik`** `object` — Filing manager SEC CIK - **`filing_manager_name`** `object` — Filing manager legal name **Example:** ```json { "filing_manager_cik": "", "filing_manager_name": "", "filing_count": 1 } ``` ### FilingManagersListResponse - **Type:**`object` * **`data` (required)** `array` — Page of distinct filing managers **Items:** - **`filing_count` (required)** `integer` — Total 13F filings this manager has submitted - **`filing_manager_cik`** `object` — Filing manager SEC CIK - **`filing_manager_name`** `object` — Filing manager legal name * **`page_size` (required)** `integer` — Results per page * **`page`** `integer`, default: `1` — Current page number (1-indexed) * **`total`** `integer`, default: `0` — Total count of matching rows * **`total_pages`** `integer`, default: `1` — Total number of pages **Example:** ```json { "total": 0, "page": 1, "page_size": 1, "total_pages": 1, "data": [ { "filing_manager_cik": "", "filing_manager_name": "", "filing_count": 1 } ] } ``` ### FilingResponse - **Type:**`object` One row from the cross-cutting filings index. `accession_num` and `source_url` are derived from `filing_id` by FilingSourceMixin. - **`accession_num` (required)** `object` — EDGAR accession number derived from filing\_id (e.g., '0000320193-24-000123') - **`cik` (required)** `string` — Filer SEC Central Index Key - **`filing_id` (required)** `string` — Unique filing identifier - **`form_type` (required)** `string` — SEC form type (e.g., '4', '13F-HR', 'D') - **`source_url` (required)** `object` — Canonical SEC EDGAR Archives URL pointing at the filing's index page - **`accepted_time`** `object` — When the SEC accepted the filing - **`filer_name`** `object` — Filer entity name - **`filer_sic`** `object` — Filer Standard Industrial Classification code (e.g., '7372' Prepackaged Software) - **`filer_tickers`** `object` — Ticker symbols associated with the filer - **`is_valid`** `object` — Whether the filing passed validation - **`period_of_report`** `object` — Reporting period end date (null on the cross-cutting index) **Example:** ```json { "accepted_time": "2024-03-17T16:30:00", "accession_num": "0001209191-24-031337", "cik": "1209191", "filer_name": "DOE JOHN", "filer_sic": "3571", "filer_tickers": [ "AAPL" ], "filing_id": "0001209191_0001209191-24-031337", "form_type": "4", "is_valid": true, "period_of_report": "2024-03-15", "source_url": "https://www.sec.gov/Archives/edgar/data/1209191/000120919124031337/0001209191-24-031337-index.htm" } ``` ### FilingsListResponse - **Type:**`object` Paginated list of filings. - **`data` (required)** `array` — Array of filings **Items:** - **`accession_num` (required)** `object` — EDGAR accession number derived from filing\_id (e.g., '0000320193-24-000123') - **`cik` (required)** `string` — Filer SEC Central Index Key - **`filing_id` (required)** `string` — Unique filing identifier - **`form_type` (required)** `string` — SEC form type (e.g., '4', '13F-HR', 'D') - **`source_url` (required)** `object` — Canonical SEC EDGAR Archives URL pointing at the filing's index page - **`accepted_time`** `object` — When the SEC accepted the filing - **`filer_name`** `object` — Filer entity name - **`filer_sic`** `object` — Filer Standard Industrial Classification code (e.g., '7372' Prepackaged Software) - **`filer_tickers`** `object` — Ticker symbols associated with the filer - **`is_valid`** `object` — Whether the filing passed validation - **`period_of_report`** `object` — Reporting period end date (null on the cross-cutting index) - **`page_size` (required)** `integer` — Results per page - **`page`** `integer`, default: `1` — Current page number (1-indexed) - **`total`** `integer`, default: `0` — Total count of matching rows - **`total_pages`** `integer`, default: `1` — Total number of pages **Example:** ```json { "total": 0, "page": 1, "page_size": 1, "total_pages": 1, "data": [ { "accepted_time": "2024-03-17T16:30:00", "accession_num": "0001209191-24-031337", "cik": "1209191", "filer_name": "DOE JOHN", "filer_sic": "3571", "filer_tickers": [ "AAPL" ], "filing_id": "0001209191_0001209191-24-031337", "form_type": "4", "is_valid": true, "period_of_report": "2024-03-15", "source_url": "https://www.sec.gov/Archives/edgar/data/1209191/000120919124031337/0001209191-24-031337-index.htm" } ] } ``` ### FlowClassification - **Type:**`string` 13F position-flow classification. - `new` — position appeared this period (not in prior period) - `exit` — position dropped this period (was in prior period) - `upsize` — position grew vs. prior period - `downsize` — position shrank vs. prior period - `hold` — unchanged position (omitted unless include\_holds=true) **Example:** ### FlowEntry - **Type:**`object` One flow row. The 'subject' fields populated depend on which filter the request used: a by-manager request fills cusip/issuer fields; a by-cusip request fills filing\_manager\_cik/name. - **`classification` (required)** `object` — Flow classification (see FlowClassification enum) - **`current_value` (required)** `string` — Current-period position value (in thousands of USD) - **`delta_value` (required)** `string` — current\_value − prior\_value (in thousands of USD) - **`prior_value` (required)** `string` — Prior-period position value (in thousands of USD) - **`cusip`** `object` — Security CUSIP - **`filing_manager_cik`** `object` — Filing manager CIK - **`filing_manager_name`** `object` — Filing manager legal name - **`name_of_issuer`** `object` — Issuer name - **`pct_change`** `object` — (current − prior) / prior. Null for new positions where prior is zero (avoids +inf). **Example:** ```json { "cusip": "", "name_of_issuer": "", "filing_manager_cik": "", "filing_manager_name": "", "classification": "new", "current_value": "", "prior_value": "", "delta_value": "", "pct_change": 1 } ``` ### Form13fCrowdingLeadersResponse - **Type:**`object` Top-N securities by 13F crowding for one period. - **`direction` (required)** `string` — Ranking direction applied (see query-param doc) - **`period_of_report` (required)** `string`, format: `date` — 13F period ranked - **`results` (required)** `array` — Top-N results **Items:** - **`aggregate_shares` (required)** `string` — Total reported shares across all holders - **`aggregate_value` (required)** `string` — Total reported value across all holders (in thousands of USD per Form 13F convention) - **`cusip` (required)** `string` — Security CUSIP - **`n_holders` (required)** `integer` — Distinct managers reporting this position at the period end - **`pct_of_filers` (required)** `number` — n\_holders / total\_filers\_in\_period, range \[0, 1] - **`period_of_report` (required)** `string`, format: `date` — 13F period analyzed - **`top_10_share_pct` (required)** `number` — Share of aggregate\_value held by the top-10 managers (concentration proxy) - **`total_filers_in_period` (required)** `integer` — Distinct managers with any 13F holding in this period (denominator) - **`hhi`** `object` — Herfindahl-Hirschman Index over manager value shares, scaled to the standard \[0, 10000] range (sum of squared percentage shares). Higher = more concentrated holder base. Null when aggregate\_value is zero. - **`name_of_issuer`** `object` — Issuer name resolved from holdings - **`qoq_holders_delta`** `object` — Change in n\_holders vs prior calendar quarter; null if no prior-period data available **Example:** ```json { "period_of_report": "", "direction": "", "results": [ { "aggregate_shares": "3187420800", "aggregate_value": "548320500", "cusip": "037833100", "n_holders": 4218, "name_of_issuer": "APPLE INC", "pct_of_filers": 0.748, "period_of_report": "2024-03-31", "qoq_holders_delta": 47, "top_10_share_pct": 0.31, "total_filers_in_period": 5640 } ] } ``` ### Form13fCrowdingResponse - **Type:**`object` Per-security crowding metrics response (alias of CrowdingMetrics). - **`aggregate_shares` (required)** `string` — Total reported shares across all holders - **`aggregate_value` (required)** `string` — Total reported value across all holders (in thousands of USD per Form 13F convention) - **`cusip` (required)** `string` — Security CUSIP - **`n_holders` (required)** `integer` — Distinct managers reporting this position at the period end - **`pct_of_filers` (required)** `number` — n\_holders / total\_filers\_in\_period, range \[0, 1] - **`period_of_report` (required)** `string`, format: `date` — 13F period analyzed - **`top_10_share_pct` (required)** `number` — Share of aggregate\_value held by the top-10 managers (concentration proxy) - **`total_filers_in_period` (required)** `integer` — Distinct managers with any 13F holding in this period (denominator) - **`hhi`** `object` — Herfindahl-Hirschman Index over manager value shares, scaled to the standard \[0, 10000] range (sum of squared percentage shares). Higher = more concentrated holder base. Null when aggregate\_value is zero. - **`name_of_issuer`** `object` — Issuer name resolved from holdings - **`qoq_holders_delta`** `object` — Change in n\_holders vs prior calendar quarter; null if no prior-period data available **Example:** ```json { "aggregate_shares": "3187420800", "aggregate_value": "548320500", "cusip": "037833100", "n_holders": 4218, "name_of_issuer": "APPLE INC", "pct_of_filers": 0.748, "period_of_report": "2024-03-31", "qoq_holders_delta": 47, "top_10_share_pct": 0.31, "total_filers_in_period": 5640 } ``` ### Form13fFlowsResponse - **Type:**`object` 13F flows for one (manager, period) or (cusip, period) — new, exit, upsize, downsize positions vs. the prior calendar quarter. - **`flows` (required)** `array` — Per-position flow rows **Items:** - **`classification` (required)** `object` — Flow classification (see FlowClassification enum) - **`current_value` (required)** `string` — Current-period position value (in thousands of USD) - **`delta_value` (required)** `string` — current\_value − prior\_value (in thousands of USD) - **`prior_value` (required)** `string` — Prior-period position value (in thousands of USD) - **`cusip`** `object` — Security CUSIP - **`filing_manager_cik`** `object` — Filing manager CIK - **`filing_manager_name`** `object` — Filing manager legal name - **`name_of_issuer`** `object` — Issuer name - **`pct_change`** `object` — (current − prior) / prior. Null for new positions where prior is zero (avoids +inf). - **`period_of_report` (required)** `string`, format: `date` — Current 13F period analyzed - **`summary` (required)** `object` — Counts per classification — keys: new, exit, upsize, downsize, hold - **`cusip`** `object` — Security CUSIP if request was filtered by security - **`filing_manager_cik`** `object` — Filing manager CIK if request was filtered by manager - **`prior_period`** `object` — Calendar-quarter end before \`period\_of\_report\`. Null if no prior holdings could be resolved. **Example:** ```json { "filing_manager_cik": "", "cusip": "", "period_of_report": "", "prior_period": "", "flows": [ { "cusip": "", "name_of_issuer": "", "filing_manager_cik": "", "filing_manager_name": "", "classification": null, "current_value": "", "prior_value": "", "delta_value": "", "pct_change": 1 } ], "summary": { "additionalProperty": 1 } } ``` ### Form13fPositionsResponse - **Type:**`object` Amendment-resolved 13F holdings for one (manager, period). Walks 13F-NT / 13F-HR / 13F-HR/A reliance chains and confidential-treatment lift events to surface canonical post-amendment positions. The response carries both the canonical envelope keys (`data` for rows, `summary` for endpoint-specific aggregates) and the legacy keys (`positions`, `aggregate_value`, `position_count`, `amendment_chain`, `period_of_report`, `filing_manager_*`). The legacy keys will be removed in a future release; new clients should consume `data` and `summary`. - **`aggregate_value` (required)** `string` — Total portfolio value across all positions (thousands of USD) - **`amendment_chain` (required)** `array` — filing\_ids walked in chronological order (original first, amendments after). Empty list means no filings found for the (manager, period). **Items:** `string` - **`data` (required)** `array` — Canonical envelope alias of \`positions\`. Prefer this key for new code — \`positions\` is retained for backward compatibility and slated for removal in a future release. **Items:** - **`cusip`** `object` — Security CUSIP - **`figi`** `object` — OpenFIGI identifier (12 chars) - **`investment_discretion`** `object` — 'SOLE', 'DFND' (defined), or 'OTR' (other shared) - **`name_of_issuer`** `object` — Issuer name - **`ssh_prnamt`** `object` — Number of shares or principal amount - **`ssh_prnamt_type`** `object` — Type of ssh\_prnamt: 'SH' = shares, 'PRN' = principal - **`title_of_class`** `object` — Title of class (e.g., 'COM', 'CL A') - **`value`** `object` — Position value (in thousands of USD per Form 13F) - **`voting_none`** `object` — Shares with no voting authority - **`voting_shared`** `object` — Shares with shared voting authority - **`voting_sole`** `object` — Shares with sole voting authority - **`filing_manager_cik` (required)** `string` — Filing manager CIK - **`period_of_report` (required)** `string`, format: `date` — 13F period - **`position_count` (required)** `integer` — Total positions after amendment resolution - **`positions` (required)** `array` — Amendment-resolved position rows **Items:** - **`cusip`** `object` — Security CUSIP - **`figi`** `object` — OpenFIGI identifier (12 chars) - **`investment_discretion`** `object` — 'SOLE', 'DFND' (defined), or 'OTR' (other shared) - **`name_of_issuer`** `object` — Issuer name - **`ssh_prnamt`** `object` — Number of shares or principal amount - **`ssh_prnamt_type`** `object` — Type of ssh\_prnamt: 'SH' = shares, 'PRN' = principal - **`title_of_class`** `object` — Title of class (e.g., 'COM', 'CL A') - **`value`** `object` — Position value (in thousands of USD per Form 13F) - **`voting_none`** `object` — Shares with no voting authority - **`voting_shared`** `object` — Shares with shared voting authority - **`voting_sole`** `object` — Shares with sole voting authority - **`summary` (required)** `object` — Endpoint-specific aggregates. Mirrors the top-level \`filing\_manager\_\*\`, \`period\_of\_report\`, \`position\_count\`, \`aggregate\_value\`, and \`amendment\_chain\` fields. - **`filing_manager_name`** `object` — Filing manager legal name **Example:** ```json { "filing_manager_cik": "", "filing_manager_name": "", "period_of_report": "", "amendment_chain": [ "" ], "position_count": 1, "aggregate_value": "", "positions": [ { "cusip": "", "figi": "", "name_of_issuer": "", "title_of_class": "", "value": "", "ssh_prnamt": "", "ssh_prnamt_type": "", "voting_sole": "", "voting_shared": "", "voting_none": "", "investment_discretion": "" } ], "data": [ { "cusip": "", "figi": "", "name_of_issuer": "", "title_of_class": "", "value": "", "ssh_prnamt": "", "ssh_prnamt_type": "", "voting_sole": "", "voting_shared": "", "voting_none": "", "investment_discretion": "" } ], "summary": {} } ``` ### Form144AcquisitionResponse - **Type:**`object` One acquisition row from a Form 144 — the original acquisition of the restricted/control securities now being proposed for sale. - **`record_index` (required)** `integer` — Per-filing 0-based ordinal of this acquisition row - **`acquired_date`** `object` — Date the securities were originally acquired - **`amount_of_securities_acquired`** `object` — Number of units acquired in the original transaction - **`is_gift_transaction`** `object` — True if the original acquisition was a gift - **`name_of_person_from_whom_acquired`** `object` — Name of the prior owner (where applicable, e.g., for gifts or inheritances) - **`nature_of_acquisition_transaction`** `object` — Free-text description of how the securities were acquired (e.g., 'Stock Option Exercise', 'Gift', 'Inheritance') - **`nature_of_payment`** `object` — Free-text description of how payment was made - **`payment_date`** `object` — Date payment was made for the securities - **`securities_class_title`** `object` — Class of securities acquired **Example:** ```json { "record_index": 1, "securities_class_title": "", "acquired_date": "", "nature_of_acquisition_transaction": "", "name_of_person_from_whom_acquired": "", "is_gift_transaction": true, "amount_of_securities_acquired": "", "payment_date": "", "nature_of_payment": "" } ``` ### Form144PriorSaleResponse - **Type:**`object` One prior-sale row from a Form 144 — a Rule 144 sale of the same class of securities by the same seller in the past 3 months (used to verify Rule 144 volume limits). - **`record_index` (required)** `integer` — Per-filing 0-based ordinal of this prior-sale row - **`amount_of_securities_sold`** `object` — Number of units sold in the prior sale - **`gross_proceeds`** `object` — Gross proceeds from the prior sale (USD) - **`sale_date`** `object` — Date of the prior sale - **`securities_class_title`** `object` — Class of securities previously sold - **`seller_name`** `object` — Name of the seller for this prior sale **Example:** ```json { "record_index": 1, "seller_name": "", "securities_class_title": "", "sale_date": "", "amount_of_securities_sold": "", "gross_proceeds": "" } ``` ### Form1aEquityClassResponse - **Type:**`object` One equity-class row from a Reg A+ filing — a class of securities being offered or held outstanding by the issuer. - **`record_index` (required)** `integer` — Per-filing 0-based ordinal of this class row - **`class_name`** `object` — Class name (e.g., 'Class A Common Stock') - **`cusip`** `object` — CUSIP of the class (where assigned) - **`equity_type`** `object` — Equity type (e.g., 'Common Equity', 'Preferred Equity') - **`outstanding`** `object` — Shares outstanding for this class - **`publicly_traded`** `object` — Public-trading designation (e.g., 'Yes' / 'No' / exchange name) **Example:** ```json { "record_index": 1, "equity_type": "", "class_name": "", "outstanding": "", "cusip": "", "publicly_traded": "" } ``` ### Form1aUnregisteredSecurityResponse - **Type:**`object` One unregistered-security row from a Reg A+ filing — a recent sale of unregistered securities (Item 6 of Form 1-A). - **`record_index` (required)** `integer` — Per-filing 0-based ordinal of this row - **`aggregate_amount`** `object` — Aggregate amount as reported (free-text; may include narrative) - **`issuer_name`** `object` — Name of the issuer of the unregistered securities - **`principal_holder_amount`** `object` — Amount sold to principal holders - **`title`** `object` — Security title (e.g., 'Series A Preferred Stock') - **`total_amount`** `object` — Total amount of unregistered securities sold **Example:** ```json { "record_index": 1, "issuer_name": "", "title": "", "total_amount": "", "principal_holder_amount": "", "aggregate_amount": "" } ``` ### FormDExemptionBreakdownResponse - **Type:**`object` * **`data` (required)** `array` — Buckets ranked by \`total\_offering\_amount\_sum\` descending. **Items:** - **`distinct_filer_count` (required)** `integer` — Distinct filer CIKs in this bucket. - **`exemption_label` (required)** `string` — Bucket label: '506b' (Rule 506(b)), '506c' (Rule 506(c)), '504' (Rule 504), 'other', or 'unspecified' (no Reg D exemption claimed in \`federal\_exemptions\_exclusions\`). - **`filing_count` (required)** `integer` — Form D filings in this bucket. - **`total_amount_sold_sum`** `object` — Sum of \`total\_amount\_sold\` (USD) for the bucket. - **`total_offering_amount_sum`** `object` — Sum of \`total\_offering\_amount\` (USD) for the bucket. * **`since`** `object` — Window start applied to filings.accepted\_time, when supplied. * **`until`** `object` — Window end applied to filings.accepted\_time, when supplied. **Example:** ```json { "since": "", "until": "", "data": [ { "exemption_label": "", "filing_count": 1, "distinct_filer_count": 1, "total_offering_amount_sum": "", "total_amount_sold_sum": "" } ] } ``` ### FormDExemptionRow - **Type:**`object` One exemption-bucket aggregate. - **`distinct_filer_count` (required)** `integer` — Distinct filer CIKs in this bucket. - **`exemption_label` (required)** `string` — Bucket label: '506b' (Rule 506(b)), '506c' (Rule 506(c)), '504' (Rule 504), 'other', or 'unspecified' (no Reg D exemption claimed in \`federal\_exemptions\_exclusions\`). - **`filing_count` (required)** `integer` — Form D filings in this bucket. - **`total_amount_sold_sum`** `object` — Sum of \`total\_amount\_sold\` (USD) for the bucket. - **`total_offering_amount_sum`** `object` — Sum of \`total\_offering\_amount\` (USD) for the bucket. **Example:** ```json { "exemption_label": "", "filing_count": 1, "distinct_filer_count": 1, "total_offering_amount_sum": "", "total_amount_sold_sum": "" } ``` ### FormdIssuerResponse - **Type:**`object` One issuer row from a Form D — the entity raising capital. A single Form D may list multiple co-issuers. - **`record_index` (required)** `integer` — Per-filing 0-based ordinal of this issuer row - **`entity_name`** `object` — Issuer legal name - **`entity_type`** `object` — Entity type (e.g., 'Corporation', 'Limited Partnership', 'Limited Liability Company') - **`issuer_cik`** `object` — Issuer SEC CIK (where the issuer has one) - **`issuer_city`** `object` — Issuer city - **`issuer_phone`** `object` — Issuer contact phone number - **`issuer_state_or_country`** `object` — Issuer state code or country code - **`issuer_state_or_country_description`** `object` — Human-readable state / country name - **`issuer_street1`** `object` — Issuer street address line 1 - **`issuer_street2`** `object` — Issuer street address line 2 - **`issuer_zip_code`** `object` — Issuer postal code - **`jurisdiction_of_inc`** `object` — State or country of incorporation/organization (e.g., 'DELAWARE') - **`year_of_inc`** `object` — Year of incorporation/organization **Example:** ```json { "record_index": 1, "issuer_cik": "", "entity_name": "", "jurisdiction_of_inc": "", "entity_type": "", "year_of_inc": "", "issuer_phone": "", "issuer_street1": "", "issuer_street2": "", "issuer_city": "", "issuer_state_or_country": "", "issuer_state_or_country_description": "", "issuer_zip_code": "" } ``` ### FormdRelatedPersonResponse - **Type:**`object` One related-person row from a Form D — an executive officer, director, or promoter of the issuer. - **`record_index` (required)** `integer` — Per-filing 0-based ordinal of this person row - **`address_city`** `object` — Person's city - **`address_state_or_country`** `object` — Person's state code or country code - **`address_state_or_country_description`** `object` — Human-readable state / country name - **`address_street1`** `object` — Person's street address line 1 - **`address_street2`** `object` — Person's street address line 2 - **`address_zip_code`** `object` — Person's postal code - **`first_name`** `object` — Given name - **`last_name`** `object` — Family name - **`middle_name`** `object` — Middle name - **`relationship_clarification`** `object` — Free-text clarification of the relationship (where 'Other' is selected) - **`relationships`** `object` — Relationship tags (e.g., \['Executive Officer', 'Director', 'Promoter']) **Example:** ```json { "record_index": 1, "first_name": "", "middle_name": "", "last_name": "", "address_street1": "", "address_street2": "", "address_city": "", "address_state_or_country": "", "address_state_or_country_description": "", "address_zip_code": "", "relationships": null, "relationship_clarification": "" } ``` ### FundCensusEntitiesListResponse - **Type:**`object` * **`data` (required)** `array` — Page of registrants with N-CEN data on file. **Items:** - **`cik` (required)** `string` — Required. Registrant SEC Central Index Key (canonical short form, no leading zeros). - **`filing_count` (required)** `integer` — Required. Total Form N-CEN filings on file for this registrant. - **`company_name`** `object` — Optional. Modal registrant name across the registrant's N-CEN filings. - **`period_max`** `object` — Optional. Latest period\_of\_report observed for this registrant. - **`period_min`** `object` — Optional. Earliest period\_of\_report observed for this registrant. - **`tickers`** `object` — Optional. Registrant ticker symbols sampled from one filing's \`filer\_tickers\`. * **`page_size` (required)** `integer` — Results per page * **`page`** `integer`, default: `1` — Current page number (1-indexed) * **`total`** `integer`, default: `0` — Total count of matching rows * **`total_pages`** `integer`, default: `1` — Total number of pages **Example:** ```json { "total": 0, "page": 1, "page_size": 1, "total_pages": 1, "data": [ { "cik": "", "company_name": "", "tickers": [ "" ], "filing_count": 1, "period_min": "", "period_max": "" } ] } ``` ### FundCensusEntitySummary - **Type:**`object` Per-registrant summary of N-CEN filing availability. One row per distinct `registrant_cik` with modal `registrant_name`, total filing count, and observed period-of-report range. - **`cik` (required)** `string` — Required. Registrant SEC Central Index Key (canonical short form, no leading zeros). - **`filing_count` (required)** `integer` — Required. Total Form N-CEN filings on file for this registrant. - **`company_name`** `object` — Optional. Modal registrant name across the registrant's N-CEN filings. - **`period_max`** `object` — Optional. Latest period\_of\_report observed for this registrant. - **`period_min`** `object` — Optional. Earliest period\_of\_report observed for this registrant. - **`tickers`** `object` — Optional. Registrant ticker symbols sampled from one filing's \`filer\_tickers\`. **Example:** ```json { "cik": "", "company_name": "", "tickers": [ "" ], "filing_count": 1, "period_min": "", "period_max": "" } ``` ### FundCensusFilingDetail - **Type:**`object` Per-filing detail — filing summary plus all series and class rows. - **`accession_num` (required)** `object` — EDGAR accession number derived from filing\_id (e.g., '0000320193-24-000123') - **`cik` (required)** `string` — Filer SEC Central Index Key - **`filing_id` (required)** `string` — Unique filing identifier - **`form_type` (required)** `string` — SEC form type (e.g., '4', '13F-HR', 'D') - **`source_url` (required)** `object` — Canonical SEC EDGAR Archives URL pointing at the filing's index page - **`accepted_time`** `object` — When SEC accepted the filing - **`classes`** `array` — Flat list of share-class rows; group by \`series\[].record\_index == class.series\_index\` **Items:** - **`record_index` (required)** `integer` — Per-filing 0-based ordinal of this class row - **`series_index` (required)** `integer` — record\_index of the parent series row in the same filing's series\[] list - **`class_id`** `object` — SEC share class identifier (e.g., C000001234) - **`extra_data`** `object` — Additional class-level fields (varies by investment-company type) - **`series_id`** `object` — SEC fund series identifier the class belongs to - **`filer_name`** `object` — Filer entity name - **`filer_tickers`** `object` — Ticker symbols associated with the filer - **`form_data`** `object` — Full N-CEN form\_data JSON (omit by passing include\_form\_data=false on the request) - **`investment_comp_file_no`** `object` — Investment Company Act file number (e.g., 811-12345) - **`investment_company_type`** `object` — Investment company type code (see query-param doc) - **`is_report_period_lt_12`** `object` — True if the report covers less than 12 months - **`is_valid`** `object` — Whether the filing passed validation - **`period_of_report`** `object` — Reporting period end date - **`previous_accession_number`** `object` — Accession number of the prior year's N-CEN filing for this registrant - **`registrant_cik`** `object` — Fund registrant (registered investment company) CIK - **`registrant_lei`** `object` — Fund registrant Legal Entity Identifier (20 chars) - **`registrant_name`** `object` — Fund registrant legal name - **`series`** `array` — All fund series rows reported on this filing **Items:** - **`record_index` (required)** `integer` — Per-filing 0-based ordinal of this series row - **`include_all_classes_flag`** `object` — True if the filing reports for all share classes of this series - **`registrant_cik`** `object` — Fund registrant CIK - **`registrant_name`** `object` — Fund registrant legal name - **`series_id`** `object` — SEC fund series identifier (e.g., S000001234) - **`submission_type`** `object` — EDGAR submission type **Example:** ```json { "filing_id": "", "cik": "", "form_type": "", "period_of_report": "", "accepted_time": "", "is_valid": true, "filer_name": "", "filer_tickers": [ "" ], "submission_type": "", "investment_company_type": "", "is_report_period_lt_12": true, "registrant_cik": "", "registrant_name": "", "registrant_lei": "", "previous_accession_number": "", "investment_comp_file_no": "", "form_data": null, "series": [ { "record_index": 1, "series_id": "", "include_all_classes_flag": true, "registrant_cik": "", "registrant_name": "" } ], "classes": [ { "series_index": 1, "record_index": 1, "series_id": "", "class_id": "", "extra_data": null } ], "accession_num": "", "source_url": "" } ``` ### FundCensusFilingSummary - **Type:**`object` Filing-level summary for one Form N-CEN submission. - **`accession_num` (required)** `object` — EDGAR accession number derived from filing\_id (e.g., '0000320193-24-000123') - **`cik` (required)** `string` — Filer SEC Central Index Key - **`filing_id` (required)** `string` — Unique filing identifier - **`form_type` (required)** `string` — SEC form type (e.g., '4', '13F-HR', 'D') - **`source_url` (required)** `object` — Canonical SEC EDGAR Archives URL pointing at the filing's index page - **`accepted_time`** `object` — When SEC accepted the filing - **`filer_name`** `object` — Filer entity name - **`filer_tickers`** `object` — Ticker symbols associated with the filer - **`investment_company_type`** `object` — Investment company type code (see query-param doc) - **`is_report_period_lt_12`** `object` — True if the report covers less than 12 months - **`is_valid`** `object` — Whether the filing passed validation - **`period_of_report`** `object` — Reporting period end date - **`registrant_cik`** `object` — Fund registrant (registered investment company) CIK - **`registrant_lei`** `object` — Fund registrant Legal Entity Identifier (20 chars) - **`registrant_name`** `object` — Fund registrant legal name - **`submission_type`** `object` — EDGAR submission type **Example:** ```json { "filing_id": "", "cik": "", "form_type": "", "period_of_report": "", "accepted_time": "", "is_valid": true, "filer_name": "", "filer_tickers": [ "" ], "submission_type": "", "investment_company_type": "", "is_report_period_lt_12": true, "registrant_cik": "", "registrant_name": "", "registrant_lei": "", "accession_num": "", "source_url": "" } ``` ### FundCensusListResponse - **Type:**`object` * **`data` (required)** `array` — Page of N-CEN filing rows **Items:** - **`accession_num` (required)** `object` — EDGAR accession number derived from filing\_id (e.g., '0000320193-24-000123') - **`cik` (required)** `string` — Filer SEC Central Index Key - **`filing_id` (required)** `string` — Unique filing identifier - **`form_type` (required)** `string` — SEC form type (e.g., '4', '13F-HR', 'D') - **`source_url` (required)** `object` — Canonical SEC EDGAR Archives URL pointing at the filing's index page - **`accepted_time`** `object` — When SEC accepted the filing - **`filer_name`** `object` — Filer entity name - **`filer_tickers`** `object` — Ticker symbols associated with the filer - **`investment_company_type`** `object` — Investment company type code (see query-param doc) - **`is_report_period_lt_12`** `object` — True if the report covers less than 12 months - **`is_valid`** `object` — Whether the filing passed validation - **`period_of_report`** `object` — Reporting period end date - **`registrant_cik`** `object` — Fund registrant (registered investment company) CIK - **`registrant_lei`** `object` — Fund registrant Legal Entity Identifier (20 chars) - **`registrant_name`** `object` — Fund registrant legal name - **`submission_type`** `object` — EDGAR submission type * **`page_size` (required)** `integer` — Results per page * **`page`** `integer`, default: `1` — Current page number (1-indexed) * **`total`** `integer`, default: `0` — Total count of matching rows * **`total_pages`** `integer`, default: `1` — Total number of pages **Example:** ```json { "total": 0, "page": 1, "page_size": 1, "total_pages": 1, "data": [ { "filing_id": "", "cik": "", "form_type": "", "period_of_report": "", "accepted_time": "", "is_valid": true, "filer_name": "", "filer_tickers": [ "" ], "submission_type": "", "investment_company_type": "", "is_report_period_lt_12": true, "registrant_cik": "", "registrant_name": "", "registrant_lei": "", "accession_num": "", "source_url": "" } ] } ``` ### FundHolding - **Type:**`object` One fund holding of the queried security — a single fund-series position from N-PORT, sized in `balance` (units) and `val_usd`. - **`filing_id` (required)** `string` — N-PORT filing this position came from - **`period_of_report` (required)** `string`, format: `date` — N-PORT reporting period end date - **`accepted_time`** `object` — When the SEC accepted the parent N-PORT filing - **`asset_cat`** `object` — N-PORT asset category code (e.g., 'EC', 'DBT') - **`balance`** `object` — Position size in N-PORT units (shares, principal, contracts) - **`fair_val_level`** `object` — FAS 157 fair-value hierarchy level (1 quoted / 2 observable / 3 unobservable). NOT the Rule 22e-4 liquidity buckets. - **`is_restricted_sec`** `object` — True if this is a restricted security - **`issuer_cat`** `object` — N-PORT issuer category code (e.g., 'CORP', 'TREA') - **`payoff_profile`** `object` — Payoff direction: 'Long', 'Short', or 'N/A' - **`pct_val`** `object` — Position as a percent of fund portfolio (0-100) - **`registrant_cik`** `object` — Fund registrant CIK - **`registrant_name`** `object` — Fund registrant legal name - **`series_id`** `object` — SEC fund series identifier - **`series_name`** `object` — Fund series display name - **`val_usd`** `object` — Position value in USD at period end **Example:** ```json { "filing_id": "", "period_of_report": "", "accepted_time": "", "registrant_cik": "", "registrant_name": "", "series_id": "", "series_name": "", "balance": "", "val_usd": "", "pct_val": "", "payoff_profile": "", "asset_cat": "", "issuer_cat": "", "fair_val_level": 1, "is_restricted_sec": true } ``` ### FundOverlapPosition - **Type:**`object` One overlapping position between two managers. - **`manager_a_share_of_portfolio` (required)** `number` — manager\_a\_value / manager\_a\_aggregate\_value, in \[0, 1]. - **`manager_a_value` (required)** `string` — Position value held by manager A (thousands of USD). - **`manager_b_share_of_portfolio` (required)** `number` — manager\_b\_value / manager\_b\_aggregate\_value, in \[0, 1]. - **`manager_b_value` (required)** `string` — Position value held by manager B (thousands of USD). - **`min_share_of_portfolio` (required)** `number` — min(manager\_a\_share\_of\_portfolio, manager\_b\_share\_of\_portfolio) — the natural overlap weight (Czekanowski / Bray-Curtis denominator). - **`cusip`** `object` — Security CUSIP. - **`name_of_issuer`** `object` — Modal issuer name across the two managers' rows. - **`title_of_class`** `object` — Title of class (modal across the two managers' rows). **Example:** ```json { "cusip": "", "name_of_issuer": "", "title_of_class": "", "manager_a_value": "", "manager_b_value": "", "manager_a_share_of_portfolio": 1, "manager_b_share_of_portfolio": 1, "min_share_of_portfolio": 1 } ``` ### FundOverlapResponse - **Type:**`object` Two-manager 13F portfolio overlap at one period. - **`manager_a_aggregate_value` (required)** `string` — Manager A's total portfolio value at the period (thousands of USD). - **`manager_a_cik` (required)** `string` — Manager A CIK (canonical short form). - **`manager_a_position_count` (required)** `integer` — Manager A's total position count at the period. - **`manager_b_aggregate_value` (required)** `string` — Manager B's total portfolio value at the period (thousands of USD). - **`manager_b_cik` (required)** `string` — Manager B CIK (canonical short form). - **`manager_b_position_count` (required)** `integer` — Manager B's total position count at the period. - **`overlap_position_count` (required)** `integer` — Number of CUSIPs both managers hold at the period. - **`overlap_score` (required)** `number` — Czekanowski / Bray-Curtis-style overlap: sum(min(share\_a, share\_b)) across overlapping positions, in \[0, 1]. 1.0 = identical portfolios; 0 = no overlap. - **`overlap_share_a` (required)** `number` — overlap\_value\_a / manager\_a\_aggregate\_value, in \[0, 1]. - **`overlap_share_b` (required)** `number` — overlap\_value\_b / manager\_b\_aggregate\_value, in \[0, 1]. - **`overlap_value_a` (required)** `string` — Value held by manager A in overlapping positions (thousands of USD). - **`overlap_value_b` (required)** `string` — Value held by manager B in overlapping positions (thousands of USD). - **`period_of_report` (required)** `string`, format: `date` — 13F period analyzed. - **`positions` (required)** `array` — Per-CUSIP overlap rows, sorted by min\_share\_of\_portfolio descending. **Items:** - **`manager_a_share_of_portfolio` (required)** `number` — manager\_a\_value / manager\_a\_aggregate\_value, in \[0, 1]. - **`manager_a_value` (required)** `string` — Position value held by manager A (thousands of USD). - **`manager_b_share_of_portfolio` (required)** `number` — manager\_b\_value / manager\_b\_aggregate\_value, in \[0, 1]. - **`manager_b_value` (required)** `string` — Position value held by manager B (thousands of USD). - **`min_share_of_portfolio` (required)** `number` — min(manager\_a\_share\_of\_portfolio, manager\_b\_share\_of\_portfolio) — the natural overlap weight (Czekanowski / Bray-Curtis denominator). - **`cusip`** `object` — Security CUSIP. - **`name_of_issuer`** `object` — Modal issuer name across the two managers' rows. - **`title_of_class`** `object` — Title of class (modal across the two managers' rows). - **`manager_a_name`** `object` — Manager A name (modal across their rows). - **`manager_b_name`** `object` — Manager B name (modal across their rows). **Example:** ```json { "period_of_report": "", "manager_a_cik": "", "manager_a_name": "", "manager_a_aggregate_value": "", "manager_a_position_count": 1, "manager_b_cik": "", "manager_b_name": "", "manager_b_aggregate_value": "", "manager_b_position_count": 1, "overlap_position_count": 1, "overlap_value_a": "", "overlap_value_b": "", "overlap_share_a": 1, "overlap_share_b": 1, "overlap_score": 1, "positions": [ { "cusip": "", "name_of_issuer": "", "title_of_class": "", "manager_a_value": "", "manager_b_value": "", "manager_a_share_of_portfolio": 1, "manager_b_share_of_portfolio": 1, "min_share_of_portfolio": 1 } ] } ``` ### FundPortfolioFilingDetail - **Type:**`object` Per-filing detail for one N-PORT. Holdings are NOT bundled — fetch them via /fund-portfolios/holdings. - **`accession_num` (required)** `object` — EDGAR accession number derived from filing\_id (e.g., '0000320193-24-000123') - **`cik` (required)** `string` — Filer SEC Central Index Key - **`filing_id` (required)** `string` — Unique filing identifier - **`form_type` (required)** `string` — SEC form type (e.g., 'N-PORT', 'N-PORT/A') - **`source_url` (required)** `object` — Canonical SEC EDGAR Archives URL pointing at the filing's index page - **`accepted_time`** `object` — When the SEC accepted the filing - **`class_id`** `object` — SEC share class identifier (e.g., C000001234) - **`filer_name`** `object` — Filer entity name - **`filer_tickers`** `object` — Ticker symbols associated with the filer - **`form_data`** `object` — Full N-PORT form\_data JSON (omit with include\_form\_data=false) - **`holdings_count`** `object` — Count of holdings rows for this filing. - **`holdings_url`** `object` — Convenience link to fetch this filing's holdings via /fund-portfolios/holdings - **`is_confidential`** `object` — True if filing is confidential treatment - **`is_final_filing`** `object` — True if this is a final (de-registration) filing - **`is_valid`** `object` — Whether the filing passed validation - **`period_of_report`** `object` — Reporting period end date - **`previous_accession_number`** `object` — Accession number of the prior period's filing for this series - **`registrant_cik`** `object` — Fund registrant CIK (the registered investment company) - **`registrant_file_number`** `object` — Investment Company Act file number (e.g., 811-12345) - **`registrant_lei`** `object` — Fund registrant Legal Entity Identifier (20-char LEI) - **`registrant_name`** `object` — Fund registrant legal name - **`report_period_end`** `object` — End date of the reported portfolio period - **`series_id`** `object` — SEC fund series identifier (e.g., S000001234) - **`series_lei`** `object` — Fund series Legal Entity Identifier - **`series_name`** `object` — Fund series display name - **`submission_type`** `object` — N-PORT submission type (e.g., NPORT-P, NPORT-EX) **Example:** ```json { "filing_id": "", "cik": "", "form_type": "", "period_of_report": "", "accepted_time": "", "is_valid": true, "filer_name": "", "filer_tickers": [ "" ], "submission_type": "", "report_period_end": "", "is_confidential": true, "is_final_filing": true, "series_id": "", "class_id": "", "registrant_cik": "", "registrant_name": "", "registrant_lei": "", "series_name": "", "previous_accession_number": "", "series_lei": "", "registrant_file_number": "", "form_data": null, "holdings_count": 1, "holdings_url": "", "accession_num": "", "source_url": "" } ``` ### FundPortfolioFilingSummary - **Type:**`object` Filing-level summary for one Form N-PORT submission. - **`accession_num` (required)** `object` — EDGAR accession number derived from filing\_id (e.g., '0000320193-24-000123') - **`cik` (required)** `string` — Filer SEC Central Index Key - **`filing_id` (required)** `string` — Unique filing identifier - **`form_type` (required)** `string` — SEC form type (e.g., 'N-PORT', 'N-PORT/A') - **`source_url` (required)** `object` — Canonical SEC EDGAR Archives URL pointing at the filing's index page - **`accepted_time`** `object` — When the SEC accepted the filing - **`class_id`** `object` — SEC share class identifier (e.g., C000001234) - **`filer_name`** `object` — Filer entity name - **`filer_tickers`** `object` — Ticker symbols associated with the filer - **`is_confidential`** `object` — True if filing is confidential treatment - **`is_final_filing`** `object` — True if this is a final (de-registration) filing - **`is_valid`** `object` — Whether the filing passed validation - **`period_of_report`** `object` — Reporting period end date - **`registrant_cik`** `object` — Fund registrant CIK (the registered investment company) - **`registrant_lei`** `object` — Fund registrant Legal Entity Identifier (20-char LEI) - **`registrant_name`** `object` — Fund registrant legal name - **`report_period_end`** `object` — End date of the reported portfolio period - **`series_id`** `object` — SEC fund series identifier (e.g., S000001234) - **`series_name`** `object` — Fund series display name - **`submission_type`** `object` — N-PORT submission type (e.g., NPORT-P, NPORT-EX) **Example:** ```json { "filing_id": "", "cik": "", "form_type": "", "period_of_report": "", "accepted_time": "", "is_valid": true, "filer_name": "", "filer_tickers": [ "" ], "submission_type": "", "report_period_end": "", "is_confidential": true, "is_final_filing": true, "series_id": "", "class_id": "", "registrant_cik": "", "registrant_name": "", "registrant_lei": "", "series_name": "", "accession_num": "", "source_url": "" } ``` ### FundPortfoliosCrossHoldingsResponse - **Type:**`object` * **`data` (required)** `array` — Page of N-PORT holding rows **Items:** - **`filing_id` (required)** `string` — Filing this holding belongs to - **`record_index` (required)** `integer` — Per-filing 0-based ordinal of this holding row - **`asset_cat`** `object` — N-PORT asset category code (e.g., 'EC' equity, 'DBT' debt, 'DCO' commodity) - **`balance`** `object` — Position size in \`units\` (shares, principal amount, contracts) - **`cur_cd`** `object` — ISO 4217 currency code of the underlying security - **`cusip`** `object` — CUSIP (8-9 chars); '000000000' / 'N/A' indicate not assigned - **`fair_val_level`** `object` — Fair-value hierarchy level: 1 (quoted), 2 (observable), 3 (unobservable) - **`inv_country`** `object` — Issuer country (ISO 3166-1 alpha-2 code) - **`is_restricted_sec`** `object` — True if this is a restricted security (Rule 144A etc.) - **`isin`** `object` — International Securities Identification Number (12 chars) - **`issuer_cat`** `object` — N-PORT issuer category code (e.g., 'CORP' corporate, 'TREA' treasury) - **`lei`** `object` — Issuer LEI (20-char Legal Entity Identifier) - **`name`** `object` — Issuer name of the held security - **`other_id`** `object` — Alternate security identifier (when CUSIP/ISIN unavailable) - **`other_id_desc`** `object` — Description of the identifier in \`other\_id\` (e.g., 'INTERNAL', 'TICKER') - **`payoff_profile`** `object` — Payoff direction: 'Long' or 'Short' (derivatives may be either) - **`pct_val`** `object` — Position as a percent of the fund series' net assets - **`period_of_report`** `object` — Reporting period end date - **`registrant_cik`** `object` — Fund registrant CIK - **`registrant_name`** `object` — Fund registrant legal name - **`series_id`** `object` — SEC fund series identifier - **`series_name`** `object` — Fund series display name - **`title`** `object` — Security title / description (e.g., '5.50% Senior Notes due 2030') - **`units`** `object` — Unit type for \`balance\` (NS=number of shares, PA=principal amount, NC=number of contracts) - **`val_usd`** `object` — Position value in USD at period-end mark * **`page_size` (required)** `integer` — Results per page * **`page`** `integer`, default: `1` — Current page number (1-indexed) * **`total`** `integer`, default: `0` — Total count of matching rows * **`total_pages`** `integer`, default: `1` — Total number of pages **Example:** ```json { "total": 0, "page": 1, "page_size": 1, "total_pages": 1, "data": [ { "asset_cat": "EC", "balance": "129084215", "cur_cd": "USD", "cusip": "037833100", "fair_val_level": 1, "filing_id": "0000884394_0001752724-24-049321", "inv_country": "US", "is_restricted_sec": false, "isin": "US0378331005", "issuer_cat": "CORP", "lei": "HWUPKR0MPOU8FGXBT394", "name": "APPLE INC", "payoff_profile": "Long", "pct_val": "6.84", "period_of_report": "2024-03-31", "record_index": 12, "registrant_cik": "0000884394", "registrant_name": "VANGUARD INDEX FUNDS", "series_id": "S000001234", "series_name": "Vanguard 500 Index Fund", "title": "Common Stock", "units": "NS", "val_usd": "22117483560.50" } ] } ``` ### FundPortfoliosEntitiesListResponse - **Type:**`object` * **`data` (required)** `array` — Page of fund registrants with N-PORT data on file. **Items:** - **`cik` (required)** `string` — Required. Fund registrant CIK (canonical short form). - **`filing_count` (required)** `integer` — Required. Total N-PORT filings on file for this registrant. - **`company_name`** `object` — Optional. Modal registrant name across the registrant's N-PORT filings. - **`period_max`** `object` — Optional. Latest period\_of\_report observed for this registrant. - **`period_min`** `object` — Optional. Earliest period\_of\_report observed for this registrant. - **`tickers`** `object` — Optional. Registrant ticker symbols sampled from one filing's \`filer\_tickers\`. * **`page_size` (required)** `integer` — Results per page * **`page`** `integer`, default: `1` — Current page number (1-indexed) * **`total`** `integer`, default: `0` — Total count of matching rows * **`total_pages`** `integer`, default: `1` — Total number of pages **Example:** ```json { "total": 0, "page": 1, "page_size": 1, "total_pages": 1, "data": [ { "cik": "", "company_name": "", "tickers": [ "" ], "filing_count": 1, "period_min": "", "period_max": "" } ] } ``` ### FundPortfoliosEntitySummary - **Type:**`object` Per-registrant summary of Form N-PORT filing availability. Grouped by `registrant_cik`. Modal `registrant_name` dodges the issuer-name spelling drift caught in the round-4 audit. N-PORT holdings count is not joined here (max 394k rows per filing) — use `filing_count` as the proxy for activity volume. - **`cik` (required)** `string` — Required. Fund registrant CIK (canonical short form). - **`filing_count` (required)** `integer` — Required. Total N-PORT filings on file for this registrant. - **`company_name`** `object` — Optional. Modal registrant name across the registrant's N-PORT filings. - **`period_max`** `object` — Optional. Latest period\_of\_report observed for this registrant. - **`period_min`** `object` — Optional. Earliest period\_of\_report observed for this registrant. - **`tickers`** `object` — Optional. Registrant ticker symbols sampled from one filing's \`filer\_tickers\`. **Example:** ```json { "cik": "", "company_name": "", "tickers": [ "" ], "filing_count": 1, "period_min": "", "period_max": "" } ``` ### FundPortfoliosListResponse - **Type:**`object` * **`data` (required)** `array` — Page of N-PORT filing rows **Items:** - **`accession_num` (required)** `object` — EDGAR accession number derived from filing\_id (e.g., '0000320193-24-000123') - **`cik` (required)** `string` — Filer SEC Central Index Key - **`filing_id` (required)** `string` — Unique filing identifier - **`form_type` (required)** `string` — SEC form type (e.g., 'N-PORT', 'N-PORT/A') - **`source_url` (required)** `object` — Canonical SEC EDGAR Archives URL pointing at the filing's index page - **`accepted_time`** `object` — When the SEC accepted the filing - **`class_id`** `object` — SEC share class identifier (e.g., C000001234) - **`filer_name`** `object` — Filer entity name - **`filer_tickers`** `object` — Ticker symbols associated with the filer - **`is_confidential`** `object` — True if filing is confidential treatment - **`is_final_filing`** `object` — True if this is a final (de-registration) filing - **`is_valid`** `object` — Whether the filing passed validation - **`period_of_report`** `object` — Reporting period end date - **`registrant_cik`** `object` — Fund registrant CIK (the registered investment company) - **`registrant_lei`** `object` — Fund registrant Legal Entity Identifier (20-char LEI) - **`registrant_name`** `object` — Fund registrant legal name - **`report_period_end`** `object` — End date of the reported portfolio period - **`series_id`** `object` — SEC fund series identifier (e.g., S000001234) - **`series_name`** `object` — Fund series display name - **`submission_type`** `object` — N-PORT submission type (e.g., NPORT-P, NPORT-EX) * **`page_size` (required)** `integer` — Results per page * **`page`** `integer`, default: `1` — Current page number (1-indexed) * **`total`** `integer`, default: `0` — Total count of matching rows * **`total_pages`** `integer`, default: `1` — Total number of pages **Example:** ```json { "total": 0, "page": 1, "page_size": 1, "total_pages": 1, "data": [ { "filing_id": "", "cik": "", "form_type": "", "period_of_report": "", "accepted_time": "", "is_valid": true, "filer_name": "", "filer_tickers": [ "" ], "submission_type": "", "report_period_end": "", "is_confidential": true, "is_final_filing": true, "series_id": "", "class_id": "", "registrant_cik": "", "registrant_name": "", "registrant_lei": "", "series_name": "", "accession_num": "", "source_url": "" } ] } ``` ### FundXRayResponse - **Type:**`object` Inverse N-PORT lookup — every fund holding the queried security at the given period. Carries the canonical envelope keys (`data` for rows, `meta` for pagination, `summary` for endpoint-specific aggregates) alongside the legacy flat fields. The legacy flat fields are slated for removal in a future release; new clients should consume `data`, `meta`, and `summary`. - **`aggregate_value_usd` (required)** `string` — Total USD value held across all fund series - **`data` (required)** `array` — Per-fund holding rows (paginated) **Items:** - **`filing_id` (required)** `string` — N-PORT filing this position came from - **`period_of_report` (required)** `string`, format: `date` — N-PORT reporting period end date - **`accepted_time`** `object` — When the SEC accepted the parent N-PORT filing - **`asset_cat`** `object` — N-PORT asset category code (e.g., 'EC', 'DBT') - **`balance`** `object` — Position size in N-PORT units (shares, principal, contracts) - **`fair_val_level`** `object` — FAS 157 fair-value hierarchy level (1 quoted / 2 observable / 3 unobservable). NOT the Rule 22e-4 liquidity buckets. - **`is_restricted_sec`** `object` — True if this is a restricted security - **`issuer_cat`** `object` — N-PORT issuer category code (e.g., 'CORP', 'TREA') - **`payoff_profile`** `object` — Payoff direction: 'Long', 'Short', or 'N/A' - **`pct_val`** `object` — Position as a percent of fund portfolio (0-100) - **`registrant_cik`** `object` — Fund registrant CIK - **`registrant_name`** `object` — Fund registrant legal name - **`series_id`** `object` — SEC fund series identifier - **`series_name`** `object` — Fund series display name - **`val_usd`** `object` — Position value in USD at period end - **`fund_count` (required)** `integer` — Distinct fund registrants (registrant\_cik) holding the security - **`meta` (required)** `object` — Canonical pagination block. Mirrors top-level \`total\`, \`page\`, \`page\_size\`, \`total\_pages\` for clients that consume the {data, meta, summary} envelope. - **`page_size` (required)** `integer` — Results per page - **`period_of_report` (required)** `string`, format: `date` — N-PORT period analyzed - **`series_count` (required)** `integer` — Distinct fund series (series\_id) holding the security - **`summary` (required)** `object` — Endpoint-specific aggregates. Mirrors \`cusip\`, \`isin\`, \`security\_name\`, \`period\_of\_report\`, \`fund\_count\`, \`series\_count\`, and \`aggregate\_value\_usd\`. - **`cusip`** `object` — CUSIP queried - **`isin`** `object` — ISIN queried - **`page`** `integer`, default: `1` — Current page number (1-indexed) - **`security_name`** `object` — Security name from the first holding row - **`total`** `integer`, default: `0` — Total count of matching rows - **`total_pages`** `integer`, default: `1` — Total number of pages **Example:** ```json { "total": 0, "page": 1, "page_size": 1, "total_pages": 1, "cusip": "", "isin": "", "security_name": "", "period_of_report": "", "fund_count": 1, "series_count": 1, "aggregate_value_usd": "", "data": [ { "filing_id": "", "period_of_report": "", "accepted_time": "", "registrant_cik": "", "registrant_name": "", "series_id": "", "series_name": "", "balance": "", "val_usd": "", "pct_val": "", "payoff_profile": "", "asset_cat": "", "issuer_cat": "", "fair_val_level": 1, "is_restricted_sec": true } ], "meta": {}, "summary": {} } ``` ### FundingMapResponse - **Type:**`object` Per-issuer funding map — short-term (N-MFP money-market funding) plus long-term (N-PORT registered-fund funding) at one period. - **`long_term_funding` (required)** `object` — N-PORT-derived long-term funding (bonds, equity) - **`period_of_report` (required)** `string`, format: `date` — Reference period end - **`short_term_funding` (required)** `object` — N-MFP-derived short-term funding (commercial paper, repo, CDs) - **`short_term_share_pct` (required)** `number` — Short-term share of total visible funding in \[0, 1]. High values flag rollover-risk concentration. - **`total_aggregate_value` (required)** `string` — Sum of short\_term + long\_term aggregate values (USD) - **`cusip`** `object` — Security CUSIP queried - **`name_of_issuer`** `object` — Issuer name resolved from the holdings - **`security_cik`** `object` — Issuer CIK queried **Example:** ```json { "cusip": "", "security_cik": "", "name_of_issuer": "", "period_of_report": "", "short_term_funding": { "source_type": "", "holder_count": 1, "aggregate_value": "", "avg_maturity_days": 1, "illiquid_share_pct": 1 }, "long_term_funding": { "source_type": "", "holder_count": 1, "aggregate_value": "", "avg_maturity_days": 1, "illiquid_share_pct": 1 }, "total_aggregate_value": "", "short_term_share_pct": 1 } ``` ### FundingSourceBucket - **Type:**`object` One side (short-term or long-term) of the funding-source split. - **`aggregate_value` (required)** `string` — Total holdings value in this bucket (USD) - **`holder_count` (required)** `integer` — Distinct fund series holding debt of this issuer in this bucket - **`source_type` (required)** `string` — 'short\_term\_money\_market' (from N-MFP) or 'long\_term\_fund' (from N-PORT) - **`avg_maturity_days`** `object` — WAL-weighted average days to maturity (short-term bucket only) - **`illiquid_share_pct`** `object` — Share of N-MFP holdings flagged as illiquid in \[0,1] (short-term bucket only) **Example:** ```json { "source_type": "", "holder_count": 1, "aggregate_value": "", "avg_maturity_days": 1, "illiquid_share_pct": 1 } ``` ### GovernanceFeaturesResponse - **Type:**`object` Composite governance feature vector for one issuer over a window — combines insider trading patterns and 13D/G activity. - **`governance_pressure_score` (required)** `number` — Coarse composite combining net insider distribution rate, distinct SC13 filer count, and 13D-vs-13G mix. Range \[0, 1]; ≥0.6 means significant governance-pressure signals are stacking - **`insider` (required)** `object` — Insider (Form 4) features - **`issuer_cik` (required)** `string` — Issuer CIK queried - **`matched_issuer_names` (required)** `integer` — Distinct issuer\_name spellings used to match SC13 filings to this issuer — confidence proxy (1 = clean unique match; >1 = potential disambiguation noise) - **`period_end` (required)** `string`, format: `date` — Window end (inclusive) - **`period_start` (required)** `string`, format: `date` — Window start (inclusive) - **`sc13` (required)** `object` — Schedule 13D/G features - **`issuer_name`** `object` — Issuer name resolved from Form 4 / SC13 records **Example:** ```json { "issuer_cik": "", "issuer_name": "", "matched_issuer_names": 1, "period_start": "", "period_end": "", "insider": { "distinct_insiders_selling": 1, "distinct_insiders_buying": 1, "insider_dispositions_dollars": "", "insider_acquisitions_dollars": "", "discretionary_sale_dollars": "" }, "sc13": { "sc13_filings_count": 1, "sc13d_filings_count": 1, "sc13g_filings_count": 1, "distinct_filers": 1, "most_recent_event_date": "", "max_percent_of_class": "", "has_group_member_flag": true }, "governance_pressure_score": 1 } ``` ### GovernanceInsiderFeatures - **Type:**`object` Insider (Form 4) component of the governance feature vector. - **`discretionary_sale_dollars` (required)** `string` — USD value of open-market 'S' sales without Rule 10b5-1 plan affiliation - **`distinct_insiders_buying` (required)** `integer` — Distinct insiders with at least one acquisition in the window - **`distinct_insiders_selling` (required)** `integer` — Distinct insiders with at least one disposition in the window - **`insider_acquisitions_dollars` (required)** `string` — Total USD value of insider acquisitions in the window - **`insider_dispositions_dollars` (required)** `string` — Total USD value of insider dispositions in the window **Example:** ```json { "distinct_insiders_selling": 1, "distinct_insiders_buying": 1, "insider_dispositions_dollars": "", "insider_acquisitions_dollars": "", "discretionary_sale_dollars": "" } ``` ### GovernancePressureLeaderboardResponse - **Type:**`object` * **`data` (required)** `array` — Issuers ranked by \`governance\_pressure\_score\` descending. **Items:** - **`cik` (required)** `string` — Issuer SEC Central Index Key (short form). - **`dispositions_dollars` (required)** `string` — Sum of disposed-share value (USD) in the window. - **`distinct_insiders_selling` (required)** `integer` — Insiders with disposition transactions in the window. - **`governance_pressure_score` (required)** `number` — Coarse pressure score \[0, 1+] composed of insider-disposition intensity, distinct-insider count, and SC13 filing volume. - **`rank` (required)** `integer` — 1-indexed rank in this leaderboard. - **`sc13_filings_count` (required)** `integer` — Schedule 13D/G filings naming this issuer (by name match) in the window. - **`company_name`** `object` — Modal issuer name across the window's filings. - **`tickers`** `object` — Issuer ticker symbols when known. * **`window` (required)** `object` — Window the leaderboard ranks over. - **`lookback_days` (required)** `integer` — Window length in days (until - since). - **`since` (required)** `string`, format: `date` — Window start (inclusive). - **`until` (required)** `string`, format: `date` — Window end (inclusive). **Example:** ```json { "window": { "since": "", "until": "", "lookback_days": 1 }, "data": [ { "rank": 1, "cik": "", "company_name": "", "tickers": [ "" ], "governance_pressure_score": 1, "distinct_insiders_selling": 1, "dispositions_dollars": "", "sc13_filings_count": 1 } ] } ``` ### GovernancePressureRow - **Type:**`object` * **`cik` (required)** `string` — Issuer SEC Central Index Key (short form). * **`dispositions_dollars` (required)** `string` — Sum of disposed-share value (USD) in the window. * **`distinct_insiders_selling` (required)** `integer` — Insiders with disposition transactions in the window. * **`governance_pressure_score` (required)** `number` — Coarse pressure score \[0, 1+] composed of insider-disposition intensity, distinct-insider count, and SC13 filing volume. * **`rank` (required)** `integer` — 1-indexed rank in this leaderboard. * **`sc13_filings_count` (required)** `integer` — Schedule 13D/G filings naming this issuer (by name match) in the window. * **`company_name`** `object` — Modal issuer name across the window's filings. * **`tickers`** `object` — Issuer ticker symbols when known. **Example:** ```json { "rank": 1, "cik": "", "company_name": "", "tickers": [ "" ], "governance_pressure_score": 1, "distinct_insiders_selling": 1, "dispositions_dollars": "", "sc13_filings_count": 1 } ``` ### GovernanceSc13Features - **Type:**`object` Schedule 13D / 13G component of the governance feature vector. - **`distinct_filers` (required)** `integer` — Distinct reporting persons across all 13D/G filings in the window - **`has_group_member_flag` (required)** `boolean` — True if any reporting person was flagged as a group member (coordinated filing pattern detected) - **`sc13_filings_count` (required)** `integer` — Total 13D + 13G filings in window - **`sc13d_filings_count` (required)** `integer` — Activist (13D) filings only — signals intent to influence control - **`sc13g_filings_count` (required)** `integer` — Passive (13G) filings only — qualified institutional holders - **`max_percent_of_class`** `object` — Largest stake (percent of class) reported by any reporting person on any 13D/G filing in the window - **`most_recent_event_date`** `object` — Most recent event\_date across the window's 13D/G filings **Example:** ```json { "sc13_filings_count": 1, "sc13d_filings_count": 1, "sc13g_filings_count": 1, "distinct_filers": 1, "most_recent_event_date": "", "max_percent_of_class": "", "has_group_member_flag": true } ``` ### GroupMember - **Type:**`object` One flagged group-member reporting person from the parent SC13. - **`record_index` (required)** `integer` — Per-filing 0-based ordinal of this person row - **`aggregate_amount`** `object` — Aggregate beneficial ownership reported (Item 11) - **`cik`** `object` — Reporting person CIK (where assigned) - **`citizenship`** `object` — Citizenship or place of organization (Item 6) - **`group_member_a`** `object` — Item 2(a): person is a member of a Section 13(d) group - **`group_member_b`** `object` — Item 2(b): person is excluded from the group - **`names`** `object` — Reporting person name (Item 1 on the cover page) - **`percent_of_class`** `object` — Percent of class reported (Item 13) - **`reporting_person_type`** `object` — Cover-page Item 2 type code (e.g., IN, OO, BD) - **`shared_voting_power`** `object` — Shared voting power (Item 8) - **`sole_voting_power`** `object` — Sole voting power (Item 7) **Example:** ```json { "record_index": 1, "cik": "", "names": "", "aggregate_amount": "", "percent_of_class": "", "sole_voting_power": "", "shared_voting_power": "", "citizenship": "", "reporting_person_type": "", "group_member_a": true, "group_member_b": true } ``` ### HealthCheckStatus - **Type:**`object` Health check results for each dependency. - **`apisix_admin` (required)** `boolean` — APISIX Admin API connectivity - **`database` (required)** `boolean` — Hoth database connectivity - **`nhost_database` (required)** `boolean` — Nhost database connectivity **Example:** ```json { "database": true, "nhost_database": true, "apisix_admin": true } ``` ### HealthResponse - **Type:**`object` Response for GET /health endpoint. Returns overall service health based on critical dependencies: - healthy: All dependencies available - degraded: Service running but some dependencies unavailable - down: Critical dependencies unavailable * **`checks` (required)** `object` — Dependency check results * **`service` (required)** `string` — Service name * **`status` (required)** `string`, possible values: `"healthy", "degraded", "down"` — Overall health status * **`timestamp` (required)** `string` — ISO 8601 timestamp (UTC) * **`version` (required)** `string` — Service version * **`data_as_of`** `object` — Latest reporting period present in each major filing family. Null if the freshness probe was skipped (e.g. database unavailable). Helps clients detect ETL staleness without a per-family probe. **Example:** ```json { "checks": { "apisix_admin": true, "database": true, "nhost_database": true }, "data_as_of": { "form_13f_latest_period": "2022-12-31" }, "service": "Tatooine API", "status": "healthy", "timestamp": "2024-10-28T12:00:00Z", "version": "1.0.0" } ``` ### HolderTypeBreakdown - **Type:**`object` One holder-type bucket — either 13F institutional managers or N-PORT registered fund series. Both views key on CUSIP directly. - **`aggregate_value` (required)** `string` — Total reported value (USD) - **`holder_count` (required)** `integer` — Distinct holders in this bucket - **`holder_type` (required)** `string` — 'institutional\_manager\_13f' (13F filers) or 'registered\_fund\_nport' (N-PORT registered investment companies). These overlap conceptually but disclosure regimes differ: 13F captures investment managers at the firm level; N-PORT captures individual fund series. - **`aggregate_shares`** `object` — Total reported shares (where comparable) **Example:** ```json { "holder_type": "", "holder_count": 1, "aggregate_value": "", "aggregate_shares": "" } ``` ### InsiderBiographyIssuerRollup - **Type:**`object` Per-issuer lifetime rollup for a single insider. - **`buys_dollars` (required)** `string` — Sum of acquired-share value (USD) across the lifetime. - **`filing_count` (required)** `integer` — Form 3/4/5 filings for this issuer. - **`sells_dollars` (required)** `string` — Sum of disposed-share value (USD) across the lifetime. - **`transaction_count` (required)** `integer` — Nonderivative transactions for this issuer. - **`first_transaction_date`** `object` — Earliest reportable transaction\_date for this issuer. - **`is_director`** `object` — Whether the insider was flagged as a director on any filing. - **`is_officer`** `object` — Whether the insider was flagged as an officer on any filing. - **`is_ten_percent_owner`** `object` — Whether the insider was flagged as a 10%+ owner on any filing. - **`issuer_cik`** `object` — Issuer CIK (canonical short form). - **`issuer_name`** `object` — Issuer name. - **`issuer_trading_symbol`** `object` — Issuer ticker symbol. - **`last_transaction_date`** `object` — Latest reportable transaction\_date for this issuer. **Example:** ```json { "issuer_cik": "", "issuer_name": "", "issuer_trading_symbol": "", "is_director": true, "is_officer": true, "is_ten_percent_owner": true, "filing_count": 1, "transaction_count": 1, "buys_dollars": "", "sells_dollars": "", "first_transaction_date": "", "last_transaction_date": "" } ``` ### InsiderBiographyResponse - **Type:**`object` * **`issuers` (required)** `array` — Per-issuer lifetime rollups, sorted by \`last\_transaction\_date\` descending. **Items:** - **`buys_dollars` (required)** `string` — Sum of acquired-share value (USD) across the lifetime. - **`filing_count` (required)** `integer` — Form 3/4/5 filings for this issuer. - **`sells_dollars` (required)** `string` — Sum of disposed-share value (USD) across the lifetime. - **`transaction_count` (required)** `integer` — Nonderivative transactions for this issuer. - **`first_transaction_date`** `object` — Earliest reportable transaction\_date for this issuer. - **`is_director`** `object` — Whether the insider was flagged as a director on any filing. - **`is_officer`** `object` — Whether the insider was flagged as an officer on any filing. - **`is_ten_percent_owner`** `object` — Whether the insider was flagged as a 10%+ owner on any filing. - **`issuer_cik`** `object` — Issuer CIK (canonical short form). - **`issuer_name`** `object` — Issuer name. - **`issuer_trading_symbol`** `object` — Issuer ticker symbol. - **`last_transaction_date`** `object` — Latest reportable transaction\_date for this issuer. * **`rpt_owner_cik` (required)** `string` — Reporting owner CIK queried (canonical short form). * **`total_filings` (required)** `integer` — Total Form 3/4/5 filings on file. * **`total_transactions` (required)** `integer` — Total nonderivative transactions on file. * **`rpt_owner_name`** `object` — Modal insider name across the lifetime. **Example:** ```json { "rpt_owner_cik": "", "rpt_owner_name": "", "total_filings": 1, "total_transactions": 1, "issuers": [ { "issuer_cik": "", "issuer_name": "", "issuer_trading_symbol": "", "is_director": true, "is_officer": true, "is_ten_percent_owner": true, "filing_count": 1, "transaction_count": 1, "buys_dollars": "", "sells_dollars": "", "first_transaction_date": "", "last_transaction_date": "" } ] } ``` ### InsiderBuySellRatioResponse - **Type:**`object` Result of /insiders/buy-sell-ratio. - **`buys_count` (required)** `integer` — Buy transaction count in the window. - **`buys_dollars` (required)** `string` — Sum of acquired-share value (USD). - **`sells_count` (required)** `integer` — Sell transaction count in the window. - **`sells_dollars` (required)** `string` — Sum of disposed-share value (USD). - **`since` (required)** `string`, format: `date` — Window start applied to transaction\_date. - **`until` (required)** `string`, format: `date` — Window end applied to transaction\_date. - **`buy_sell_ratio`** `object` — buys\_dollars / (buys\_dollars + sells\_dollars), in \[0, 1]. Null when both totals are zero. - **`cik`** `object` — Issuer CIK queried (canonical short form), when supplied. - **`sic`** `object` — Filer SIC filter applied, when supplied. - **`ticker`** `object` — Issuer ticker queried, when supplied. **Example:** ```json { "cik": "", "ticker": "", "sic": "", "since": "", "until": "", "buys_dollars": "", "sells_dollars": "", "buys_count": 1, "sells_count": 1, "buy_sell_ratio": 1 } ``` ### InsiderBuyingLeaderboardResponse - **Type:**`object` * **`data` (required)** `array` — Issuers ranked by \`buys\_dollars\` descending. **Items:** - **`buys_count` (required)** `integer` — Number of buy transactions over the window. - **`buys_dollars` (required)** `string` — Sum of acquired-share value (USD) over the window. - **`cik` (required)** `string` — Issuer SEC Central Index Key (short form). - **`distinct_insiders_buying` (required)** `integer` — Distinct reporting owners with at least one buy in the window. - **`rank` (required)** `integer` — 1-indexed rank in this leaderboard. - **`company_name`** `object` — Modal issuer name across the window's filings. - **`tickers`** `object` — Issuer ticker symbols when known. * **`window` (required)** `object` — Window the leaderboard ranks over. - **`lookback_days` (required)** `integer` — Window length in days (until - since). - **`since` (required)** `string`, format: `date` — Window start (inclusive). - **`until` (required)** `string`, format: `date` — Window end (inclusive). **Example:** ```json { "window": { "since": "", "until": "", "lookback_days": 1 }, "data": [ { "rank": 1, "cik": "", "company_name": "", "tickers": [ "" ], "buys_dollars": "", "buys_count": 1, "distinct_insiders_buying": 1 } ] } ``` ### InsiderBuyingRow - **Type:**`object` * **`buys_count` (required)** `integer` — Number of buy transactions over the window. * **`buys_dollars` (required)** `string` — Sum of acquired-share value (USD) over the window. * **`cik` (required)** `string` — Issuer SEC Central Index Key (short form). * **`distinct_insiders_buying` (required)** `integer` — Distinct reporting owners with at least one buy in the window. * **`rank` (required)** `integer` — 1-indexed rank in this leaderboard. * **`company_name`** `object` — Modal issuer name across the window's filings. * **`tickers`** `object` — Issuer ticker symbols when known. **Example:** ```json { "rank": 1, "cik": "", "company_name": "", "tickers": [ "" ], "buys_dollars": "", "buys_count": 1, "distinct_insiders_buying": 1 } ``` ### InsiderClusterEvent - **Type:**`object` One cluster-buying event — ≥`min_insiders` distinct insiders making same-direction transactions within `window_days` for one issuer. - **`aggregate_dollars` (required)** `string` — Total USD value of insider transactions in the cluster - **`has_senior_member` (required)** `boolean` — True if at least one cluster member is a director, officer, or ≥10% owner - **`issuer_cik` (required)** `string` — Issuer (company) CIK - **`member_count` (required)** `integer` — Distinct insiders contributing to the cluster - **`members` (required)** `array` — Per-insider rollup **Items:** - **`aggregate_dollars` (required)** `string` — Total USD value of this insider's transactions in the cluster window - **`is_senior` (required)** `boolean` — True if the insider is a director, officer, or ≥10% owner - **`rpt_owner_cik` (required)** `string` — Reporting owner (insider) CIK - **`transaction_count` (required)** `integer` — Distinct transactions this insider made within the cluster window - **`rpt_owner_name`** `object` — Reporting owner name - **`window_end` (required)** `string`, format: `date` — Cluster window end (latest transaction date) - **`window_start` (required)** `string`, format: `date` — Cluster window start (earliest transaction date) - **`issuer_trading_symbol`** `object` — Issuer ticker symbol **Example:** ```json { "issuer_cik": "", "issuer_trading_symbol": "", "window_start": "", "window_end": "", "member_count": 1, "members": [ { "rpt_owner_cik": "", "rpt_owner_name": "", "transaction_count": 1, "aggregate_dollars": "", "is_senior": true } ], "aggregate_dollars": "", "has_senior_member": true } ``` ### InsiderClusterMember - **Type:**`object` One insider participating in a cluster event. - **`aggregate_dollars` (required)** `string` — Total USD value of this insider's transactions in the cluster window - **`is_senior` (required)** `boolean` — True if the insider is a director, officer, or ≥10% owner - **`rpt_owner_cik` (required)** `string` — Reporting owner (insider) CIK - **`transaction_count` (required)** `integer` — Distinct transactions this insider made within the cluster window - **`rpt_owner_name`** `object` — Reporting owner name **Example:** ```json { "rpt_owner_cik": "", "rpt_owner_name": "", "transaction_count": 1, "aggregate_dollars": "", "is_senior": true } ``` ### InsiderClustersListResponse - **Type:**`object` * **`data` (required)** `array` — Page of cluster-buying events **Items:** - **`aggregate_dollars` (required)** `string` — Total USD value of insider transactions in the cluster - **`has_senior_member` (required)** `boolean` — True if at least one cluster member is a director, officer, or ≥10% owner - **`issuer_cik` (required)** `string` — Issuer (company) CIK - **`member_count` (required)** `integer` — Distinct insiders contributing to the cluster - **`members` (required)** `array` — Per-insider rollup **Items:** - **`aggregate_dollars` (required)** `string` — Total USD value of this insider's transactions in the cluster window - **`is_senior` (required)** `boolean` — True if the insider is a director, officer, or ≥10% owner - **`rpt_owner_cik` (required)** `string` — Reporting owner (insider) CIK - **`transaction_count` (required)** `integer` — Distinct transactions this insider made within the cluster window - **`rpt_owner_name`** `object` — Reporting owner name - **`window_end` (required)** `string`, format: `date` — Cluster window end (latest transaction date) - **`window_start` (required)** `string`, format: `date` — Cluster window start (earliest transaction date) - **`issuer_trading_symbol`** `object` — Issuer ticker symbol * **`page_size` (required)** `integer` — Results per page * **`page`** `integer`, default: `1` — Current page number (1-indexed) * **`total`** `integer`, default: `0` — Total count of matching rows * **`total_pages`** `integer`, default: `1` — Total number of pages **Example:** ```json { "total": 0, "page": 1, "page_size": 1, "total_pages": 1, "data": [ { "issuer_cik": "", "issuer_trading_symbol": "", "window_start": "", "window_end": "", "member_count": 1, "members": [], "aggregate_dollars": "", "has_senior_member": true } ] } ``` ### InsiderConvictionLeadersResponse - **Type:**`object` Top-N issuers ranked by insider-conviction score. - **`as_of` (required)** `string`, format: `date` — Anchor date used - **`direction` (required)** `string` — Ranking direction (bullish or bearish) - **`results` (required)** `array` — Top-N issuer scores **Items:** - **`as_of` (required)** `string`, format: `date` — Anchor date for the trailing window - **`components` (required)** `object` — Component breakdown - **`distinct_insiders` (required)** `integer` — Distinct insiders contributing transactions in the window - **`score` (required)** `number` — Composite conviction score in \[-1, 1]; positive = bullish insider activity, negative = bearish - **`total_dollars` (required)** `string` — Total USD value of insider activity in the window - **`window_days` (required)** `integer` — Window length in days - **`issuer_cik`** `object` — Issuer CIK - **`issuer_trading_symbol`** `object` — Issuer ticker symbol - **`window_days` (required)** `integer` — Trailing window applied **Example:** ```json { "as_of": "", "window_days": 1, "direction": "", "results": [ { "as_of": "2024-04-01", "components": { "breadth": 0.38, "dollar_imbalance": 0.65, "seniority_weight": 0.55 }, "distinct_insiders": 7, "issuer_cik": "0000320193", "issuer_trading_symbol": "AAPL", "score": 0.42, "total_dollars": "8420000.00", "window_days": 90 } ] } ``` ### InsiderConvictionResponse - **Type:**`object` Composite insider-conviction score for one issuer over a trailing window. - **`as_of` (required)** `string`, format: `date` — Anchor date for the trailing window - **`components` (required)** `object` — Component breakdown - **`distinct_insiders` (required)** `integer` — Distinct insiders contributing transactions in the window - **`score` (required)** `number` — Composite conviction score in \[-1, 1]; positive = bullish insider activity, negative = bearish - **`total_dollars` (required)** `string` — Total USD value of insider activity in the window - **`window_days` (required)** `integer` — Window length in days - **`issuer_cik`** `object` — Issuer CIK - **`issuer_trading_symbol`** `object` — Issuer ticker symbol **Example:** ```json { "as_of": "2024-04-01", "components": { "breadth": 0.38, "dollar_imbalance": 0.65, "seniority_weight": 0.55 }, "distinct_insiders": 7, "issuer_cik": "0000320193", "issuer_trading_symbol": "AAPL", "score": 0.42, "total_dollars": "8420000.00", "window_days": 90 } ``` ### InsiderFilingDetail - **Type:**`object` Per-filing detail — filing summary plus all five child row-sets: reporting owners, non-derivative holdings + transactions, and derivative holdings + transactions. - **`accession_num` (required)** `object` — EDGAR accession number derived from filing\_id (e.g., '0000320193-24-000123') - **`cik` (required)** `string` — Filer (insider) SEC Central Index Key - **`filing_id` (required)** `string` — Unique filing identifier - **`form_type` (required)** `string` — SEC form type ('3', '3/A', '4', '4/A', '5', '5/A') - **`rpt_owner_cik` (required)** `string` — Alias of \`cik\` — the reporting owner's CIK. Matches the \`{rpt\_owner\_cik}\` path parameter on \`/insiders/owners/...\` so callers can pass it through without remapping. - **`source_url` (required)** `object` — Canonical SEC EDGAR Archives URL pointing at the filing's index page - **`accepted_time`** `object` — When the SEC accepted the filing - **`aff10b5_one`** `object` — True if any reported transaction was made under a Rule 10b5-1 trading plan - **`deriv_holdings`** `array` — All derivative holding rows for this filing **Items:** - **`record_index` (required)** `integer` — Per-filing 0-based ordinal of this derivative-holding row - **`conversion_or_exercise_price`** `object` — Strike / conversion price per share - **`direct_or_indirect_ownership`** `object` — 'D' = direct ownership, 'I' = indirect - **`exercise_date`** `object` — Earliest date the derivative becomes exercisable - **`expiration_date`** `object` — Date the derivative expires - **`nature_of_ownership`** `object` — Free-text describing indirect ownership - **`security_title`** `object` — Derivative title (e.g., 'Stock Option (Right to Buy)', 'RSU') - **`shares_owned_following_transaction`** `object` — Derivative-instrument count owned after the most recent transaction - **`underlying_security_shares`** `object` — Number of underlying shares the derivative covers - **`underlying_security_title`** `object` — Underlying security title (typically 'Common Stock') - **`underlying_security_value`** `object` — USD value of the underlying shares - **`value_owned_following_transaction`** `object` — USD value of derivatives owned after the most recent transaction - **`deriv_transactions`** `array` — All derivative transaction rows for this filing **Items:** - **`record_index` (required)** `integer` — Per-filing 0-based ordinal of this derivative-transaction row - **`conversion_or_exercise_price`** `object` — Strike / conversion price per share - **`direct_or_indirect_ownership`** `object` — 'D' = direct ownership, 'I' = indirect - **`exercise_date`** `object` — Earliest date the derivative becomes exercisable - **`expiration_date`** `object` — Date the derivative expires - **`security_title`** `object` — Derivative title - **`shares_owned_following_transaction`** `object` — Total derivative instruments owned after this transaction - **`transaction_acquired_disposed_code`** `object` — 'A' = acquired, 'D' = disposed - **`transaction_code`** `object` — Single-letter transaction code (see NonderivTransactionResponse) - **`transaction_date`** `object` — Date the transaction occurred - **`transaction_price_per_share`** `object` — Price per derivative instrument - **`transaction_shares`** `object` — Number of derivative instruments involved - **`transaction_total_value`** `object` — Total USD value of the transaction - **`underlying_security_shares`** `object` — Number of underlying shares the derivative covers - **`underlying_security_title`** `object` — Underlying security title (typically 'Common Stock') - **`underlying_security_value`** `object` — USD value of the underlying shares - **`document_type`** `object` — EDGAR document type label - **`filer_name`** `object` — Filer (insider) name - **`footnotes`** `object` — Footnote payload (XML-derived JSON of footnote text + targets) - **`form3_holdings_reported`** `object` — True if Form 3 initial-holdings table is reported - **`form4_transactions_reported`** `object` — True if Form 4 transactions are reported - **`is_amendment`** `object` — True if this filing is an amendment ('/A' suffix) - **`is_valid`** `object` — Whether the filing passed validation - **`issuer_cik`** `object` — Issuer (company) CIK — the company whose securities are being reported - **`issuer_name`** `object` — Issuer (company) legal name - **`issuer_trading_symbol`** `object` — Issuer ticker symbol - **`no_securities_owned`** `object` — True if filer reports no securities owned (typical Form 3) - **`nonderiv_holdings`** `array` — All non-derivative holding rows for this filing **Items:** - **`record_index` (required)** `integer` — Per-filing 0-based ordinal of this holding row - **`direct_or_indirect_ownership`** `object` — 'D' = direct ownership, 'I' = indirect (e.g., via trust or family member) - **`nature_of_ownership`** `object` — Free-text describing indirect ownership (e.g., 'By spouse', 'By trust') - **`security_title`** `object` — Security name (e.g., 'Common Stock', 'Class A Common') - **`shares_owned_following_transaction`** `object` — Total shares beneficially owned after the most recent transaction - **`value_owned_following_transaction`** `object` — Total USD value beneficially owned after the most recent transaction - **`nonderiv_transactions`** `array` — All non-derivative transaction rows for this filing **Items:** - **`record_index` (required)** `integer` — Per-filing 0-based ordinal of this transaction row - **`direct_or_indirect_ownership`** `object` — 'D' = direct ownership, 'I' = indirect - **`security_title`** `object` — Security name (e.g., 'Common Stock') - **`shares_owned_following_transaction`** `object` — Total shares owned after this transaction settles - **`transaction_acquired_disposed_code`** `object` — 'A' = shares acquired, 'D' = shares disposed - **`transaction_code`** `object` — Single-letter transaction code (e.g., P=open-market purchase, S=open-market sale, A=grant, M=option exercise, F=tax-withholding) - **`transaction_date`** `object` — Date the transaction occurred - **`transaction_price_per_share`** `object` — Price per share; 0 for grants, gifts, and other no-cost transactions - **`transaction_shares`** `object` — Number of shares involved in the transaction - **`not_subject_to_section16`** `object` — True if filer claims exemption from Section 16 reporting - **`period_of_report`** `object` — Reporting period end date - **`remarks`** `object` — Free-text remarks attached to the filing - **`reporting_owners`** `array` — All reporting-owner rows for this filing **Items:** - **`record_index` (required)** `integer` — Per-filing 0-based ordinal of this owner row - **`is_director`** `object` — True if reporting owner is a director of the issuer - **`is_officer`** `object` — True if reporting owner is an officer of the issuer - **`is_other`** `object` — True if reporting owner falls into none of the above categories — see \`other\_text\` - **`is_ten_percent_owner`** `object` — True if reporting owner holds 10%+ of the issuer's stock - **`officer_title`** `object` — Officer title (e.g., 'Chief Executive Officer'); blank if not an officer - **`other_text`** `object` — Free-text description when \`is\_other\` is True - **`rpt_owner_cik`** `object` — Reporting owner (insider) SEC CIK - **`rpt_owner_name`** `object` — Reporting owner (insider) legal name - **`schema_version`** `object` — EDGAR XML schema version this filing was produced under - **`signatures`** `object` — Signatures payload (signing party + date) **Example:** ```json { "filing_id": "", "cik": "", "form_type": "", "is_amendment": true, "period_of_report": "", "accepted_time": "", "is_valid": true, "filer_name": "", "issuer_cik": "", "issuer_name": "", "issuer_trading_symbol": "", "document_type": "", "schema_version": "", "not_subject_to_section16": true, "form3_holdings_reported": true, "form4_transactions_reported": true, "no_securities_owned": true, "aff10b5_one": true, "remarks": "", "footnotes": null, "signatures": null, "reporting_owners": [ { "record_index": 1, "rpt_owner_cik": "", "rpt_owner_name": "", "officer_title": "", "is_director": true, "is_officer": true, "is_ten_percent_owner": true, "is_other": true, "other_text": "" } ], "nonderiv_holdings": [ { "record_index": 1, "security_title": "", "shares_owned_following_transaction": "", "value_owned_following_transaction": "", "direct_or_indirect_ownership": "", "nature_of_ownership": "" } ], "nonderiv_transactions": [ { "record_index": 1, "security_title": "", "transaction_date": "", "transaction_code": "", "transaction_acquired_disposed_code": "", "transaction_shares": "", "transaction_price_per_share": "", "shares_owned_following_transaction": "", "direct_or_indirect_ownership": "" } ], "deriv_holdings": [ { "record_index": 1, "security_title": "", "conversion_or_exercise_price": "", "exercise_date": "", "expiration_date": "", "underlying_security_title": "", "underlying_security_shares": "", "underlying_security_value": "", "shares_owned_following_transaction": "", "value_owned_following_transaction": "", "direct_or_indirect_ownership": "", "nature_of_ownership": "" } ], "deriv_transactions": [ { "record_index": 1, "security_title": "", "conversion_or_exercise_price": "", "transaction_date": "", "transaction_code": "", "transaction_acquired_disposed_code": "", "transaction_shares": "", "transaction_total_value": "", "transaction_price_per_share": "", "exercise_date": "", "expiration_date": "", "underlying_security_title": "", "underlying_security_shares": "", "underlying_security_value": "", "shares_owned_following_transaction": "", "direct_or_indirect_ownership": "" } ], "accession_num": "", "source_url": "", "rpt_owner_cik": "" } ``` ### InsiderFilingSummary - **Type:**`object` Filing-level metadata for /insiders list endpoint. - **`accession_num` (required)** `object` — EDGAR accession number derived from filing\_id (e.g., '0000320193-24-000123') - **`cik` (required)** `string` — Filer (insider) SEC Central Index Key - **`filing_id` (required)** `string` — Unique filing identifier - **`form_type` (required)** `string` — SEC form type ('3', '3/A', '4', '4/A', '5', '5/A') - **`rpt_owner_cik` (required)** `string` — Alias of \`cik\` — the reporting owner's CIK. Matches the \`{rpt\_owner\_cik}\` path parameter on \`/insiders/owners/...\` so callers can pass it through without remapping. - **`source_url` (required)** `object` — Canonical SEC EDGAR Archives URL pointing at the filing's index page - **`accepted_time`** `object` — When the SEC accepted the filing - **`filer_name`** `object` — Filer (insider) name - **`is_amendment`** `object` — True if this filing is an amendment ('/A' suffix) - **`is_valid`** `object` — Whether the filing passed validation - **`issuer_cik`** `object` — Issuer (company) CIK — the company whose securities are being reported - **`issuer_name`** `object` — Issuer (company) legal name - **`issuer_trading_symbol`** `object` — Issuer ticker symbol - **`period_of_report`** `object` — Reporting period end date **Example:** ```json { "filing_id": "", "cik": "", "form_type": "", "is_amendment": true, "period_of_report": "", "accepted_time": "", "is_valid": true, "filer_name": "", "issuer_cik": "", "issuer_name": "", "issuer_trading_symbol": "", "accession_num": "", "source_url": "", "rpt_owner_cik": "" } ``` ### InsiderSellingLeaderboardResponse - **Type:**`object` * **`data` (required)** `array` — Issuers ranked by \`sells\_dollars\` descending. **Items:** - **`cik` (required)** `string` — Issuer SEC Central Index Key (short form). - **`distinct_insiders_selling` (required)** `integer` — Distinct reporting owners with at least one sell in the window. - **`rank` (required)** `integer` — 1-indexed rank in this leaderboard. - **`sells_count` (required)** `integer` — Number of sell transactions over the window. - **`sells_dollars` (required)** `string` — Sum of disposed-share value (USD) over the window. - **`company_name`** `object` — Modal issuer name across the window's filings. - **`tickers`** `object` — Issuer ticker symbols when known. * **`exclude_10b51` (required)** `boolean` — When true, sells flagged \`aff10b5\_one=true\` are excluded from \`sells\_dollars\` (discretionary-only ranking). * **`window` (required)** `object` — Window the leaderboard ranks over. - **`lookback_days` (required)** `integer` — Window length in days (until - since). - **`since` (required)** `string`, format: `date` — Window start (inclusive). - **`until` (required)** `string`, format: `date` — Window end (inclusive). **Example:** ```json { "window": { "since": "", "until": "", "lookback_days": 1 }, "exclude_10b51": true, "data": [ { "rank": 1, "cik": "", "company_name": "", "tickers": [ "" ], "sells_dollars": "", "sells_count": 1, "distinct_insiders_selling": 1 } ] } ``` ### InsiderSellingRow - **Type:**`object` * **`cik` (required)** `string` — Issuer SEC Central Index Key (short form). * **`distinct_insiders_selling` (required)** `integer` — Distinct reporting owners with at least one sell in the window. * **`rank` (required)** `integer` — 1-indexed rank in this leaderboard. * **`sells_count` (required)** `integer` — Number of sell transactions over the window. * **`sells_dollars` (required)** `string` — Sum of disposed-share value (USD) over the window. * **`company_name`** `object` — Modal issuer name across the window's filings. * **`tickers`** `object` — Issuer ticker symbols when known. **Example:** ```json { "rank": 1, "cik": "", "company_name": "", "tickers": [ "" ], "sells_dollars": "", "sells_count": 1, "distinct_insiders_selling": 1 } ``` ### InsiderSentimentBySicResponse - **Type:**`object` * **`data` (required)** `array` — SIC sectors ranked by absolute \`buys\_dollars + sells\_dollars\` descending. **Items:** - **`buys_count` (required)** `integer` — Buy transaction count in the window. - **`buys_dollars` (required)** `string` — Sum of acquired-share value (USD) — \`transaction\_acquired\_disposed\_code='A'\`. - **`sells_count` (required)** `integer` — Sell transaction count in the window. - **`sells_dollars` (required)** `string` — Sum of disposed-share value (USD) — \`transaction\_acquired\_disposed\_code='D'\`. - **`buy_sell_ratio`** `object` — buys\_dollars / (buys\_dollars + sells\_dollars), in \[0, 1]. Null when both totals are zero. - **`sic`** `object` — Form 4 filer's SIC code (4 digits, when known). - **`sic_description`** `object` — SIC description (modal across the rollup). * **`since`** `object` — Window start applied to transaction\_date, when supplied. * **`until`** `object` — Window end applied to transaction\_date, when supplied. **Example:** ```json { "since": "", "until": "", "data": [ { "sic": "", "sic_description": "", "buys_dollars": "", "sells_dollars": "", "buys_count": 1, "sells_count": 1, "buy_sell_ratio": 1 } ] } ``` ### InsiderSentimentBySicRow - **Type:**`object` * **`buys_count` (required)** `integer` — Buy transaction count in the window. * **`buys_dollars` (required)** `string` — Sum of acquired-share value (USD) — \`transaction\_acquired\_disposed\_code='A'\`. * **`sells_count` (required)** `integer` — Sell transaction count in the window. * **`sells_dollars` (required)** `string` — Sum of disposed-share value (USD) — \`transaction\_acquired\_disposed\_code='D'\`. * **`buy_sell_ratio`** `object` — buys\_dollars / (buys\_dollars + sells\_dollars), in \[0, 1]. Null when both totals are zero. * **`sic`** `object` — Form 4 filer's SIC code (4 digits, when known). * **`sic_description`** `object` — SIC description (modal across the rollup). **Example:** ```json { "sic": "", "sic_description": "", "buys_dollars": "", "sells_dollars": "", "buys_count": 1, "sells_count": 1, "buy_sell_ratio": 1 } ``` ### InsiderTradeClassificationLeaderRow - **Type:**`object` * **`cik` (required)** `string` — Issuer SEC Central Index Key (short form). * **`discretionary_dollars` (required)** `string` — Discretionary disposed-share value (USD) — code 'S' AND aff10b5\_one=false. * **`discretionary_pct` (required)** `number` — discretionary\_dollars / sum(all classes), clamped to \[0, 1]. * **`other_dollars` (required)** `string` — Other disposed-share value (USD) — neither discretionary, plan, nor tax. * **`plan_dollars` (required)** `string` — Plan-driven disposed-share value (USD) — aff10b5\_one=true. * **`rank` (required)** `integer` — 1-indexed rank in this leaderboard. * **`tax_dollars` (required)** `string` — Tax-related disposed-share value (USD) — codes F, M. * **`transaction_count` (required)** `integer` — Total disposition transactions counted in the window. * **`company_name`** `object` — Modal issuer name across the window's filings. * **`tickers`** `object` — Issuer ticker symbols when known. **Example:** ```json { "rank": 1, "cik": "", "company_name": "", "tickers": [ "" ], "discretionary_dollars": "", "plan_dollars": "", "tax_dollars": "", "other_dollars": "", "discretionary_pct": 1, "transaction_count": 1 } ``` ### InsiderTradeClassificationLeadersResponse - **Type:**`object` * **`data` (required)** `array` — Issuers ranked by the chosen \`rank\_by\` metric, descending. **Items:** - **`cik` (required)** `string` — Issuer SEC Central Index Key (short form). - **`discretionary_dollars` (required)** `string` — Discretionary disposed-share value (USD) — code 'S' AND aff10b5\_one=false. - **`discretionary_pct` (required)** `number` — discretionary\_dollars / sum(all classes), clamped to \[0, 1]. - **`other_dollars` (required)** `string` — Other disposed-share value (USD) — neither discretionary, plan, nor tax. - **`plan_dollars` (required)** `string` — Plan-driven disposed-share value (USD) — aff10b5\_one=true. - **`rank` (required)** `integer` — 1-indexed rank in this leaderboard. - **`tax_dollars` (required)** `string` — Tax-related disposed-share value (USD) — codes F, M. - **`transaction_count` (required)** `integer` — Total disposition transactions counted in the window. - **`company_name`** `object` — Modal issuer name across the window's filings. - **`tickers`** `object` — Issuer ticker symbols when known. * **`rank_by` (required)** `string`, possible values: `"discretionary_dollars", "discretionary_pct"` — Whether the leaderboard ranks by absolute USD or by ratio. * **`window` (required)** `object` — Window the leaderboard ranks over. - **`lookback_days` (required)** `integer` — Window length in days (until - since). - **`since` (required)** `string`, format: `date` — Window start (inclusive). - **`until` (required)** `string`, format: `date` — Window end (inclusive). **Example:** ```json { "window": { "since": "", "until": "", "lookback_days": 1 }, "rank_by": "discretionary_dollars", "data": [ { "rank": 1, "cik": "", "company_name": "", "tickers": [ "" ], "discretionary_dollars": "", "plan_dollars": "", "tax_dollars": "", "other_dollars": "", "discretionary_pct": 1, "transaction_count": 1 } ] } ``` ### InsiderTradeClassificationResponse - **Type:**`object` Insider-disposition classification rollup for one issuer over a window. - **`breakdown` (required)** `object` — Per-bucket dollar and percent rollup - **`dollar_total` (required)** `string` — Total USD value of dispositions in the window - **`since` (required)** `string`, format: `date` — Window start applied - **`transaction_count` (required)** `integer` — Total disposition transactions in the window - **`until` (required)** `string`, format: `date` — Window end applied - **`issuer_cik`** `object` — Issuer CIK - **`issuer_trading_symbol`** `object` — Issuer ticker symbol **Example:** ```json { "issuer_cik": "", "issuer_trading_symbol": "", "since": "", "until": "", "transaction_count": 1, "dollar_total": "", "breakdown": { "discretionary_dollars": "", "discretionary_pct": 1, "plan_dollars": "", "plan_pct": 1, "tax_dollars": "", "tax_pct": 1, "other_dollars": "", "other_pct": 1 } } ``` ### InsiderTransactionAggregateResponse - **Type:**`object` * **`data` (required)** `array` — Per-bucket aggregates sorted by \`group\_key\`. **Items:** - **`buys_count` (required)** `integer` — Buy transactions in this bucket. - **`buys_dollars` (required)** `string` — Sum of acquired-share value (USD). - **`group_key` (required)** `string` — Bucket key — for \`groupby=date|week|month\` this is an ISO date (period start); for \`insider\` it's the rpt\_owner\_cik; for \`issuer\` it's the issuer\_cik. - **`sells_count` (required)** `integer` — Sell transactions in this bucket. - **`sells_dollars` (required)** `string` — Sum of disposed-share value (USD). - **`bucket_start`** `object` — Start date of the bucket when grouping by date/week/month. - **`buy_sell_ratio`** `object` — buys\_dollars / (buys\_dollars + sells\_dollars), in \[0, 1]; null when both are zero. - **`group_label`** `object` — Human-readable label (e.g., insider name, issuer name). * **`groupby` (required)** `string`, possible values: `"date", "week", "month", "insider", "issuer"` — Group key applied to the rollup. * **`since` (required)** `string`, format: `date` — Window start applied to transaction\_date. * **`until` (required)** `string`, format: `date` — Window end applied to transaction\_date. **Example:** ```json { "groupby": "date", "since": "", "until": "", "data": [ { "group_key": "", "group_label": "", "bucket_start": "", "buys_dollars": "", "sells_dollars": "", "buys_count": 1, "sells_count": 1, "buy_sell_ratio": 1 } ] } ``` ### InsiderTransactionAggregateRow - **Type:**`object` One bucket of the transaction-aggregate rollup. - **`buys_count` (required)** `integer` — Buy transactions in this bucket. - **`buys_dollars` (required)** `string` — Sum of acquired-share value (USD). - **`group_key` (required)** `string` — Bucket key — for \`groupby=date|week|month\` this is an ISO date (period start); for \`insider\` it's the rpt\_owner\_cik; for \`issuer\` it's the issuer\_cik. - **`sells_count` (required)** `integer` — Sell transactions in this bucket. - **`sells_dollars` (required)** `string` — Sum of disposed-share value (USD). - **`bucket_start`** `object` — Start date of the bucket when grouping by date/week/month. - **`buy_sell_ratio`** `object` — buys\_dollars / (buys\_dollars + sells\_dollars), in \[0, 1]; null when both are zero. - **`group_label`** `object` — Human-readable label (e.g., insider name, issuer name). **Example:** ```json { "group_key": "", "group_label": "", "bucket_start": "", "buys_dollars": "", "sells_dollars": "", "buys_count": 1, "sells_count": 1, "buy_sell_ratio": 1 } ``` ### InsiderTransactionRow - **Type:**`object` Unified transaction row from the /insiders/transactions cross-filing stream. Fields specific to derivatives are Optional and populated only when `transaction_kind` is `deriv`. - **`filing_id` (required)** `string` — Filing the transaction belongs to - **`record_index` (required)** `integer` — Per-filing 0-based ordinal of the row - **`transaction_kind` (required)** `object` — Whether this row came from the non-derivative or derivative table - **`conversion_or_exercise_price`** `object` — Deriv only: strike / conversion price per underlying share - **`direct_or_indirect_ownership`** `object` — 'D' = direct ownership, 'I' = indirect - **`exercise_date`** `object` — Deriv only: earliest exercise date - **`expiration_date`** `object` — Deriv only: expiration date - **`filer_cik`** `object` — Reporting owner CIK(s) for this filing. Distinct values, no implied ordering with \`filer\_name\`. - **`filer_name`** `object` — Reporting owner name(s) for this filing. Multiple owners are joined with \`; \` (alphabetical) — Form 4 filings occasionally list more than one reporting person. - **`issuer_cik`** `object` — Issuer (company) CIK - **`issuer_trading_symbol`** `object` — Issuer ticker symbol - **`security_title`** `object` — Security name (e.g., 'Common Stock', 'Stock Option') - **`shares_owned_following_transaction`** `object` — Total shares (or derivatives) owned after this transaction - **`transaction_acquired_disposed_code`** `object` — 'A' = acquired, 'D' = disposed - **`transaction_code`** `object` — Single-letter transaction code (P, S, A, M, G, F, etc.) - **`transaction_date`** `object` — Date the transaction occurred - **`transaction_price_per_share`** `object` — Price per share; 0 for grants and gifts - **`transaction_shares`** `object` — Number of shares (or derivative instruments) involved - **`transaction_total_value`** `object` — Total USD value — for deriv rows the form's transaction\_total\_value; for nonderiv rows shares × price\_per\_share - **`underlying_security_shares`** `object` — Deriv only: number of underlying shares the derivative covers - **`underlying_security_title`** `object` — Deriv only: underlying security title **Example:** ```json { "direct_or_indirect_ownership": "D", "filer_cik": [ "0001214156" ], "filer_name": "Cook Timothy D.", "filing_id": "0000320193_0001127602-24-031337", "issuer_cik": "0000320193", "issuer_trading_symbol": "AAPL", "record_index": 0, "security_title": "Common Stock", "shares_owned_following_transaction": "248500", "transaction_acquired_disposed_code": "D", "transaction_code": "S", "transaction_date": "2024-03-15", "transaction_kind": "nonderiv", "transaction_price_per_share": "172.50", "transaction_shares": "12000", "transaction_total_value": "2070000.00" } ``` ### InsiderTransactionsListResponse - **Type:**`object` * **`data` (required)** `array` — Page of insider-transaction rows **Items:** - **`filing_id` (required)** `string` — Filing the transaction belongs to - **`record_index` (required)** `integer` — Per-filing 0-based ordinal of the row - **`transaction_kind` (required)** `object` — Whether this row came from the non-derivative or derivative table - **`conversion_or_exercise_price`** `object` — Deriv only: strike / conversion price per underlying share - **`direct_or_indirect_ownership`** `object` — 'D' = direct ownership, 'I' = indirect - **`exercise_date`** `object` — Deriv only: earliest exercise date - **`expiration_date`** `object` — Deriv only: expiration date - **`filer_cik`** `object` — Reporting owner CIK(s) for this filing. Distinct values, no implied ordering with \`filer\_name\`. - **`filer_name`** `object` — Reporting owner name(s) for this filing. Multiple owners are joined with \`; \` (alphabetical) — Form 4 filings occasionally list more than one reporting person. - **`issuer_cik`** `object` — Issuer (company) CIK - **`issuer_trading_symbol`** `object` — Issuer ticker symbol - **`security_title`** `object` — Security name (e.g., 'Common Stock', 'Stock Option') - **`shares_owned_following_transaction`** `object` — Total shares (or derivatives) owned after this transaction - **`transaction_acquired_disposed_code`** `object` — 'A' = acquired, 'D' = disposed - **`transaction_code`** `object` — Single-letter transaction code (P, S, A, M, G, F, etc.) - **`transaction_date`** `object` — Date the transaction occurred - **`transaction_price_per_share`** `object` — Price per share; 0 for grants and gifts - **`transaction_shares`** `object` — Number of shares (or derivative instruments) involved - **`transaction_total_value`** `object` — Total USD value — for deriv rows the form's transaction\_total\_value; for nonderiv rows shares × price\_per\_share - **`underlying_security_shares`** `object` — Deriv only: number of underlying shares the derivative covers - **`underlying_security_title`** `object` — Deriv only: underlying security title * **`page_size` (required)** `integer` — Results per page * **`page`** `integer`, default: `1` — Current page number (1-indexed) * **`total`** `integer`, default: `0` — Total count of matching rows * **`total_pages`** `integer`, default: `1` — Total number of pages **Example:** ```json { "total": 0, "page": 1, "page_size": 1, "total_pages": 1, "data": [ { "direct_or_indirect_ownership": "D", "filer_cik": [ "0001214156" ], "filer_name": "Cook Timothy D.", "filing_id": "0000320193_0001127602-24-031337", "issuer_cik": "0000320193", "issuer_trading_symbol": "AAPL", "record_index": 0, "security_title": "Common Stock", "shares_owned_following_transaction": "248500", "transaction_acquired_disposed_code": "D", "transaction_code": "S", "transaction_date": "2024-03-15", "transaction_kind": "nonderiv", "transaction_price_per_share": "172.50", "transaction_shares": "12000", "transaction_total_value": "2070000.00" } ] } ``` ### InsidersEntitiesListResponse - **Type:**`object` * **`data` (required)** `array` — Page of issuers with Form 3/4/5 data on file. **Items:** - **`cik` (required)** `string` — Required. Issuer SEC Central Index Key (canonical short form, no leading zeros). - **`filing_count` (required)** `integer` — Required. Total Form 3/4/5 filings on file naming this issuer. - **`company_name`** `object` — Optional. Modal issuer name across the issuer's Form 3/4/5 filings. - **`period_max`** `object` — Optional. Latest period\_of\_report observed for this issuer. - **`period_min`** `object` — Optional. Earliest period\_of\_report observed for this issuer. - **`tickers`** `object` — Optional. Issuer ticker symbols sampled from one filing's \`filer\_tickers\`. * **`page_size` (required)** `integer` — Results per page * **`page`** `integer`, default: `1` — Current page number (1-indexed) * **`total`** `integer`, default: `0` — Total count of matching rows * **`total_pages`** `integer`, default: `1` — Total number of pages **Example:** ```json { "total": 0, "page": 1, "page_size": 1, "total_pages": 1, "data": [ { "cik": "320193", "company_name": "Apple Inc.", "filing_count": 184, "period_max": "2024-03-15", "period_min": "2018-04-30", "tickers": [ "AAPL" ] } ] } ``` ### InsidersEntitySummary - **Type:**`object` Per-issuer summary of Form 3/4/5 filing availability. One row per distinct `issuer_cik` with the modal `issuer_name` across that issuer's filings (mode dodges the spelling drift caught in the round-4 audit), filing count, and the period-of-report range observed for the issuer. - **`cik` (required)** `string` — Required. Issuer SEC Central Index Key (canonical short form, no leading zeros). - **`filing_count` (required)** `integer` — Required. Total Form 3/4/5 filings on file naming this issuer. - **`company_name`** `object` — Optional. Modal issuer name across the issuer's Form 3/4/5 filings. - **`period_max`** `object` — Optional. Latest period\_of\_report observed for this issuer. - **`period_min`** `object` — Optional. Earliest period\_of\_report observed for this issuer. - **`tickers`** `object` — Optional. Issuer ticker symbols sampled from one filing's \`filer\_tickers\`. **Example:** ```json { "cik": "320193", "company_name": "Apple Inc.", "filing_count": 184, "period_max": "2024-03-15", "period_min": "2018-04-30", "tickers": [ "AAPL" ] } ``` ### InsidersListResponse - **Type:**`object` * **`data` (required)** `array` — Page of Form 3/4/5 filing rows **Items:** - **`accession_num` (required)** `object` — EDGAR accession number derived from filing\_id (e.g., '0000320193-24-000123') - **`cik` (required)** `string` — Filer (insider) SEC Central Index Key - **`filing_id` (required)** `string` — Unique filing identifier - **`form_type` (required)** `string` — SEC form type ('3', '3/A', '4', '4/A', '5', '5/A') - **`rpt_owner_cik` (required)** `string` — Alias of \`cik\` — the reporting owner's CIK. Matches the \`{rpt\_owner\_cik}\` path parameter on \`/insiders/owners/...\` so callers can pass it through without remapping. - **`source_url` (required)** `object` — Canonical SEC EDGAR Archives URL pointing at the filing's index page - **`accepted_time`** `object` — When the SEC accepted the filing - **`filer_name`** `object` — Filer (insider) name - **`is_amendment`** `object` — True if this filing is an amendment ('/A' suffix) - **`is_valid`** `object` — Whether the filing passed validation - **`issuer_cik`** `object` — Issuer (company) CIK — the company whose securities are being reported - **`issuer_name`** `object` — Issuer (company) legal name - **`issuer_trading_symbol`** `object` — Issuer ticker symbol - **`period_of_report`** `object` — Reporting period end date * **`page_size` (required)** `integer` — Results per page * **`page`** `integer`, default: `1` — Current page number (1-indexed) * **`total`** `integer`, default: `0` — Total count of matching rows * **`total_pages`** `integer`, default: `1` — Total number of pages **Example:** ```json { "total": 0, "page": 1, "page_size": 1, "total_pages": 1, "data": [ { "filing_id": "", "cik": "", "form_type": "", "is_amendment": true, "period_of_report": "", "accepted_time": "", "is_valid": true, "filer_name": "", "issuer_cik": "", "issuer_name": "", "issuer_trading_symbol": "", "accession_num": "", "source_url": "", "rpt_owner_cik": "" } ] } ``` ### InstitutionalCrossHoldingsResponse - **Type:**`object` * **`data` (required)** `array` — Page of 13F holding rows **Items:** - **`filing_id` (required)** `string` — Filing this holding belongs to - **`record_index` (required)** `integer` — Per-filing 0-based ordinal of this holding row - **`cusip`** `object` — 9-character CUSIP of the held security - **`figi`** `object` — OpenFIGI Financial Instrument Global Identifier (12 chars) - **`filing_manager_cik`** `object` — Filing manager CIK - **`filing_manager_name`** `object` — Filing manager legal name - **`investment_discretion`** `object` — Investment discretion: 'SOLE', 'DFND' (defined), 'OTR' (other shared) - **`name_of_issuer`** `object` — Issuer name of the held security - **`period_of_report`** `object` — Reporting period end date (calendar quarter end) - **`ssh_prnamt`** `object` — Number of shares or principal amount held - **`ssh_prnamt_type`** `object` — Type of \`ssh\_prnamt\` units: 'SH' = shares, 'PRN' = principal amount (debt) - **`title_of_class`** `object` — Title of class (e.g., 'COM', 'CL A', 'PFD CL B') - **`value`** `object` — Position value in thousands of USD (per Form 13F reporting convention) - **`voting_none`** `object` — Shares with no voting authority - **`voting_shared`** `object` — Shares with shared voting authority - **`voting_sole`** `object` — Shares with sole voting authority * **`page_size` (required)** `integer` — Results per page * **`page`** `integer`, default: `1` — Current page number (1-indexed) * **`total`** `integer`, default: `0` — Total count of matching rows * **`total_pages`** `integer`, default: `1` — Total number of pages **Example:** ```json { "total": 0, "page": 1, "page_size": 1, "total_pages": 1, "data": [ { "cusip": "037833100", "figi": "BBG000B9XRY4", "filing_id": "0001067983_0001067983-24-000012", "filing_manager_cik": "0001067983", "filing_manager_name": "BERKSHIRE HATHAWAY INC", "investment_discretion": "DFND", "name_of_issuer": "APPLE INC", "period_of_report": "2024-03-31", "record_index": 42, "ssh_prnamt": "789368450", "ssh_prnamt_type": "SH", "title_of_class": "COM", "value": "135360500", "voting_none": "0", "voting_shared": "0", "voting_sole": "789368450" } ] } ``` ### InstitutionalFilingDetail - **Type:**`object` Per-filing detail — filing summary plus the other-managers list. Holdings are NOT bundled (they can hit 50k+ rows per filing); fetch them via /institutional-holdings/holdings. - **`accession_num` (required)** `object` — EDGAR accession number derived from filing\_id (e.g., '0000320193-24-000123') - **`cik` (required)** `string` — Filer SEC Central Index Key - **`filing_id` (required)** `string` — Unique filing identifier - **`form_type` (required)** `string` — SEC form type (e.g., '13F-HR', '13F-NT', '13F-HR/A') - **`source_url` (required)** `object` — Canonical SEC EDGAR Archives URL pointing at the filing's index page - **`accepted_time`** `object` — When the SEC accepted the filing - **`additional_information`** `object` — Free-text additional information narrative from the filing - **`amendment_no`** `object` — Amendment number (1, 2, ...) for amendment filings - **`filer_name`** `object` — Filer entity name - **`filer_tickers`** `object` — Ticker symbols associated with the filer - **`filing_manager_cik`** `object` — Filing manager CIK (institutional investment manager) - **`filing_manager_city`** `object` — Filing manager city - **`filing_manager_name`** `object` — Filing manager legal name - **`filing_manager_state_or_country`** `object` — Filing manager state code or country code (US states or ISO country) - **`filing_manager_street1`** `object` — Filing manager street address - **`holdings_count`** `object` — Total holdings rows on this filing (mirrors table\_entry\_total). Fetch the rows via /institutional-holdings/holdings?filing\_id={filing\_id}. - **`holdings_url`** `object` — Convenience link to fetch the holdings rows for this filing - **`is_amendment`** `object` — True if this filing is an amendment - **`is_confidential_omitted`** `object` — True if confidential treatment caused holdings to be omitted - **`is_valid`** `object` — Whether the filing passed validation - **`other_included_managers_count`** `object` — Count of other managers also included on this filing - **`other_managers`** `array` — Other managers also included on this filing **Items:** - **`record_index` (required)** `integer` — Per-filing 0-based ordinal of this manager row - **`crd_number`** `object` — FINRA CRD number for the other manager - **`form13_f_file_number`** `object` — Form 13F file number (e.g., '028-12345') - **`other_manager_cik`** `object` — Other manager SEC CIK - **`other_manager_name`** `object` — Other manager legal name - **`sec_file_number`** `object` — SEC file number for the other manager (e.g., '801-12345' for advisers) - **`period_of_report`** `object` — Reporting period end date (calendar quarter end) - **`report_calendar_or_quarter`** `object` — Reported calendar quarter / period (e.g., '03-31-2024') - **`report_type`** `object` — 13F report type code: 'HR', 'NT', or 'CR' (see query-param doc) - **`submission_type`** `object` — EDGAR submission type - **`table_entry_total`** `object` — Total number of holdings rows reported on this filing - **`table_value_total`** `object` — Total reported portfolio value (in thousands of USD per Form 13F convention) **Example:** ```json { "filing_id": "", "cik": "", "form_type": "", "period_of_report": "", "accepted_time": "", "is_valid": true, "filer_name": "", "filer_tickers": [ "" ], "filing_manager_cik": "", "filing_manager_name": "", "submission_type": "", "report_type": "", "is_amendment": true, "amendment_no": 1, "other_included_managers_count": 1, "table_entry_total": 1, "table_value_total": "", "filing_manager_street1": "", "filing_manager_city": "", "filing_manager_state_or_country": "", "report_calendar_or_quarter": "", "additional_information": "", "is_confidential_omitted": true, "other_managers": [ { "record_index": 1, "other_manager_cik": "", "other_manager_name": "", "form13_f_file_number": "", "crd_number": "", "sec_file_number": "" } ], "holdings_count": 1, "holdings_url": "", "accession_num": "", "source_url": "" } ``` ### InstitutionalFilingSummary - **Type:**`object` Filing-level summary for one Form 13F submission. - **`accession_num` (required)** `object` — EDGAR accession number derived from filing\_id (e.g., '0000320193-24-000123') - **`cik` (required)** `string` — Filer SEC Central Index Key - **`filing_id` (required)** `string` — Unique filing identifier - **`form_type` (required)** `string` — SEC form type (e.g., '13F-HR', '13F-NT', '13F-HR/A') - **`source_url` (required)** `object` — Canonical SEC EDGAR Archives URL pointing at the filing's index page - **`accepted_time`** `object` — When the SEC accepted the filing - **`amendment_no`** `object` — Amendment number (1, 2, ...) for amendment filings - **`filer_name`** `object` — Filer entity name - **`filer_tickers`** `object` — Ticker symbols associated with the filer - **`filing_manager_cik`** `object` — Filing manager CIK (institutional investment manager) - **`filing_manager_name`** `object` — Filing manager legal name - **`is_amendment`** `object` — True if this filing is an amendment - **`is_valid`** `object` — Whether the filing passed validation - **`other_included_managers_count`** `object` — Count of other managers also included on this filing - **`period_of_report`** `object` — Reporting period end date (calendar quarter end) - **`report_type`** `object` — 13F report type code: 'HR', 'NT', or 'CR' (see query-param doc) - **`submission_type`** `object` — EDGAR submission type - **`table_entry_total`** `object` — Total number of holdings rows reported on this filing - **`table_value_total`** `object` — Total reported portfolio value (in thousands of USD per Form 13F convention) **Example:** ```json { "filing_id": "", "cik": "", "form_type": "", "period_of_report": "", "accepted_time": "", "is_valid": true, "filer_name": "", "filer_tickers": [ "" ], "filing_manager_cik": "", "filing_manager_name": "", "submission_type": "", "report_type": "", "is_amendment": true, "amendment_no": 1, "other_included_managers_count": 1, "table_entry_total": 1, "table_value_total": "", "accession_num": "", "source_url": "" } ``` ### InstitutionalHoldingResponse - **Type:**`object` One holding row from the 13F information table — a single position held by a filing manager at the period end. - **`filing_id` (required)** `string` — Filing this holding belongs to - **`record_index` (required)** `integer` — Per-filing 0-based ordinal of this holding row - **`cusip`** `object` — 9-character CUSIP of the held security - **`figi`** `object` — OpenFIGI Financial Instrument Global Identifier (12 chars) - **`filing_manager_cik`** `object` — Filing manager CIK - **`filing_manager_name`** `object` — Filing manager legal name - **`investment_discretion`** `object` — Investment discretion: 'SOLE', 'DFND' (defined), 'OTR' (other shared) - **`name_of_issuer`** `object` — Issuer name of the held security - **`period_of_report`** `object` — Reporting period end date (calendar quarter end) - **`ssh_prnamt`** `object` — Number of shares or principal amount held - **`ssh_prnamt_type`** `object` — Type of \`ssh\_prnamt\` units: 'SH' = shares, 'PRN' = principal amount (debt) - **`title_of_class`** `object` — Title of class (e.g., 'COM', 'CL A', 'PFD CL B') - **`value`** `object` — Position value in thousands of USD (per Form 13F reporting convention) - **`voting_none`** `object` — Shares with no voting authority - **`voting_shared`** `object` — Shares with shared voting authority - **`voting_sole`** `object` — Shares with sole voting authority **Example:** ```json { "cusip": "037833100", "figi": "BBG000B9XRY4", "filing_id": "0001067983_0001067983-24-000012", "filing_manager_cik": "0001067983", "filing_manager_name": "BERKSHIRE HATHAWAY INC", "investment_discretion": "DFND", "name_of_issuer": "APPLE INC", "period_of_report": "2024-03-31", "record_index": 42, "ssh_prnamt": "789368450", "ssh_prnamt_type": "SH", "title_of_class": "COM", "value": "135360500", "voting_none": "0", "voting_shared": "0", "voting_sole": "789368450" } ``` ### InstitutionalHoldingsListResponse - **Type:**`object` * **`data` (required)** `array` — Page of 13F filing rows **Items:** - **`accession_num` (required)** `object` — EDGAR accession number derived from filing\_id (e.g., '0000320193-24-000123') - **`cik` (required)** `string` — Filer SEC Central Index Key - **`filing_id` (required)** `string` — Unique filing identifier - **`form_type` (required)** `string` — SEC form type (e.g., '13F-HR', '13F-NT', '13F-HR/A') - **`source_url` (required)** `object` — Canonical SEC EDGAR Archives URL pointing at the filing's index page - **`accepted_time`** `object` — When the SEC accepted the filing - **`amendment_no`** `object` — Amendment number (1, 2, ...) for amendment filings - **`filer_name`** `object` — Filer entity name - **`filer_tickers`** `object` — Ticker symbols associated with the filer - **`filing_manager_cik`** `object` — Filing manager CIK (institutional investment manager) - **`filing_manager_name`** `object` — Filing manager legal name - **`is_amendment`** `object` — True if this filing is an amendment - **`is_valid`** `object` — Whether the filing passed validation - **`other_included_managers_count`** `object` — Count of other managers also included on this filing - **`period_of_report`** `object` — Reporting period end date (calendar quarter end) - **`report_type`** `object` — 13F report type code: 'HR', 'NT', or 'CR' (see query-param doc) - **`submission_type`** `object` — EDGAR submission type - **`table_entry_total`** `object` — Total number of holdings rows reported on this filing - **`table_value_total`** `object` — Total reported portfolio value (in thousands of USD per Form 13F convention) * **`page_size` (required)** `integer` — Results per page * **`page`** `integer`, default: `1` — Current page number (1-indexed) * **`total`** `integer`, default: `0` — Total count of matching rows * **`total_pages`** `integer`, default: `1` — Total number of pages **Example:** ```json { "total": 0, "page": 1, "page_size": 1, "total_pages": 1, "data": [ { "filing_id": "", "cik": "", "form_type": "", "period_of_report": "", "accepted_time": "", "is_valid": true, "filer_name": "", "filer_tickers": [ "" ], "filing_manager_cik": "", "filing_manager_name": "", "submission_type": "", "report_type": "", "is_amendment": true, "amendment_no": 1, "other_included_managers_count": 1, "table_entry_total": 1, "table_value_total": "", "accession_num": "", "source_url": "" } ] } ``` ### IntakeBucket - **Type:**`object` One bucket of the intake histogram. - **`bucket_start` (required)** `string`, format: `date` — Start date of this bucket (inclusive). - **`family` (required)** `object` — Filing family this bucket counts. - **`filing_count`** `integer`, default: `0` — Filings accepted within this bucket. **Example:** ```json { "bucket_start": "", "family": "insiders", "filing_count": 0 } ``` ### IntakeResponse - **Type:**`object` * **`data` (required)** `array` — Per-(bucket, family) counts. Empty (bucket, family) pairs are omitted; clients should treat absent rows as zero. **Items:** - **`bucket_start` (required)** `string`, format: `date` — Start date of this bucket (inclusive). - **`family` (required)** `object` — Filing family this bucket counts. - **`filing_count`** `integer`, default: `0` — Filings accepted within this bucket. * **`lookback_days` (required)** `integer` — Window length in days, ending at the most recent accepted\_time. * **`period` (required)** `string`, possible values: `"daily", "weekly", "monthly"` — Bucket size used for the histogram. **Example:** ```json { "period": "daily", "lookback_days": 1, "data": [ { "bucket_start": "", "family": null, "filing_count": 0 } ] } ``` ### IssuerCoverageResponse - **Type:**`object` * **`cik` (required)** `string` — Resolved issuer CIK (canonical short form, no leading zeros). * **`families` (required)** `object` — Per-family filing coverage for this issuer. Families with no filings on file are omitted. * **`company_name`** `object` — Modal company name across the issuer's filings. * **`tickers`** `object` — Ticker symbols associated with the issuer (when known). **Example:** ```json { "cik": "", "company_name": "", "tickers": [ "" ], "families": { "additionalProperty": { "filing_count": 0, "period_min": "", "period_max": "", "accepted_time_max": "" } } } ``` ### IssuerFamilyCoverage - **Type:**`object` Per-family slice of a single issuer's coverage. - **`accepted_time_max`** `object` — Latest accepted\_time observed for this issuer. - **`filing_count`** `integer`, default: `0` — Filings on file for this (issuer, family) pair. - **`period_max`** `object` — Latest period\_of\_report for this issuer. - **`period_min`** `object` — Earliest period\_of\_report for this issuer. **Example:** ```json { "filing_count": 0, "period_min": "", "period_max": "", "accepted_time_max": "" } ``` ### LargestFormDLeaderboardResponse - **Type:**`object` * **`data` (required)** `array` — Form D filings ranked by \`total\_offering\_amount\` descending. **Items:** - **`cik` (required)** `string` — Filer SEC Central Index Key (short form). - **`filing_id` (required)** `string` — Form D filing identifier. - **`rank` (required)** `integer` — 1-indexed rank in this leaderboard. - **`accepted_time`** `object` — When the SEC accepted the filing. - **`company_name`** `object` — Filer name on the filing. - **`industry_group_type`** `object` — Form D industry-group classification (e.g., 'Technology'). - **`period_of_report`** `object` — Filing's period\_of\_report. - **`total_offering_amount`** `object` — Total offering amount (USD) reported on the filing. * **`window` (required)** `object` — Window the leaderboard ranks over. - **`lookback_days` (required)** `integer` — Window length in days (until - since). - **`since` (required)** `string`, format: `date` — Window start (inclusive). - **`until` (required)** `string`, format: `date` — Window end (inclusive). **Example:** ```json { "window": { "since": "", "until": "", "lookback_days": 1 }, "data": [ { "rank": 1, "filing_id": "", "cik": "", "company_name": "", "accepted_time": "", "period_of_report": "", "total_offering_amount": "", "industry_group_type": "" } ] } ``` ### LargestFormDRow - **Type:**`object` * **`cik` (required)** `string` — Filer SEC Central Index Key (short form). * **`filing_id` (required)** `string` — Form D filing identifier. * **`rank` (required)** `integer` — 1-indexed rank in this leaderboard. * **`accepted_time`** `object` — When the SEC accepted the filing. * **`company_name`** `object` — Filer name on the filing. * **`industry_group_type`** `object` — Form D industry-group classification (e.g., 'Technology'). * **`period_of_report`** `object` — Filing's period\_of\_report. * **`total_offering_amount`** `object` — Total offering amount (USD) reported on the filing. **Example:** ```json { "rank": 1, "filing_id": "", "cik": "", "company_name": "", "accepted_time": "", "period_of_report": "", "total_offering_amount": "", "industry_group_type": "" } ``` ### LateInsiderFilingRow - **Type:**`object` One Form 4 transaction filed late under Section 16(a). - **`accepted_time` (required)** `string`, format: `date-time` — When the SEC accepted the filing. - **`business_days_late` (required)** `integer` — Business-days delay between transaction\_date and accepted\_time. - **`days_late` (required)** `integer` — Calendar-days delay (informational; the regulatory deadline is in business days). - **`filing_id` (required)** `string` — Form 4 filing identifier. - **`transaction_date` (required)** `string`, format: `date` — Date of the reportable transaction. - **`issuer_cik`** `object` — Issuer CIK (canonical short form). - **`issuer_name`** `object` — Issuer name on the filing. - **`issuer_trading_symbol`** `object` — Issuer ticker symbol. - **`rpt_owner_cik`** `object` — Reporting owner CIK on the filing (canonical short form). - **`rpt_owner_name`** `object` — Reporting owner name. **Example:** ```json { "filing_id": "", "rpt_owner_cik": "", "rpt_owner_name": "", "issuer_cik": "", "issuer_name": "", "issuer_trading_symbol": "", "transaction_date": "", "accepted_time": "", "business_days_late": 1, "days_late": 1 } ``` ### LateInsiderFilingsResponse - **Type:**`object` * **`data` (required)** `array` — Late filings sorted by \`business\_days\_late\` descending. **Items:** - **`accepted_time` (required)** `string`, format: `date-time` — When the SEC accepted the filing. - **`business_days_late` (required)** `integer` — Business-days delay between transaction\_date and accepted\_time. - **`days_late` (required)** `integer` — Calendar-days delay (informational; the regulatory deadline is in business days). - **`filing_id` (required)** `string` — Form 4 filing identifier. - **`transaction_date` (required)** `string`, format: `date` — Date of the reportable transaction. - **`issuer_cik`** `object` — Issuer CIK (canonical short form). - **`issuer_name`** `object` — Issuer name on the filing. - **`issuer_trading_symbol`** `object` — Issuer ticker symbol. - **`rpt_owner_cik`** `object` — Reporting owner CIK on the filing (canonical short form). - **`rpt_owner_name`** `object` — Reporting owner name. * **`deadline_business_days` (required)** `integer` — Number of business days after transaction\_date by which Form 4 must be filed under Section 16(a) — currently 2. * **`page_size` (required)** `integer` — Results per page * **`page`** `integer`, default: `1` — Current page number (1-indexed) * **`total`** `integer`, default: `0` — Total count of matching rows * **`total_pages`** `integer`, default: `1` — Total number of pages **Example:** ```json { "total": 0, "page": 1, "page_size": 1, "total_pages": 1, "deadline_business_days": 1, "data": [ { "filing_id": "", "rpt_owner_cik": "", "rpt_owner_name": "", "issuer_cik": "", "issuer_name": "", "issuer_trading_symbol": "", "transaction_date": "", "accepted_time": "", "business_days_late": 1, "days_late": 1 } ] } ``` ### LeaderboardWindow - **Type:**`object` Window the leaderboard ranks over. - **`lookback_days` (required)** `integer` — Window length in days (until - since). - **`since` (required)** `string`, format: `date` — Window start (inclusive). - **`until` (required)** `string`, format: `date` — Window end (inclusive). **Example:** ```json { "since": "", "until": "", "lookback_days": 1 } ``` ### LiquidAssetsTimeseriesResponse - **Type:**`object` * **`data` (required)** `array` — Page of liquid-assets time-series points **Items:** - **`filing_id` (required)** `string` — Filing this point came from - **`record_index` (required)** `integer` — Per-filing 0-based ordinal of this point - **`date`** `object` — Date of this observation - **`granularity`** `object` — 'monthly' (filing date) or 'daily' (intra-month) - **`percentage_daily_liquid_assets`** `object` — Daily-liquid assets as a percent of total assets - **`percentage_weekly_liquid_assets`** `object` — Weekly-liquid assets as a percent of total assets - **`series_id`** `object` — SEC fund series identifier - **`series_name`** `object` — Fund series display name - **`total_value_daily_liquid_assets`** `object` — Total daily-liquid assets at this date (USD) - **`total_value_weekly_liquid_assets`** `object` — Total weekly-liquid assets at this date (USD) * **`page_size` (required)** `integer` — Results per page * **`page`** `integer`, default: `1` — Current page number (1-indexed) * **`total`** `integer`, default: `0` — Total count of matching rows * **`total_pages`** `integer`, default: `1` — Total number of pages **Example:** ```json { "total": 0, "page": 1, "page_size": 1, "total_pages": 1, "data": [ { "filing_id": "", "record_index": 1, "series_id": "", "series_name": "", "date": "", "total_value_daily_liquid_assets": "", "total_value_weekly_liquid_assets": "", "percentage_daily_liquid_assets": "", "percentage_weekly_liquid_assets": "", "granularity": "" } ] } ``` ### LiquidAssetsTimeseriesRow - **Type:**`object` One series-liquidity time-series point — one date's daily and weekly liquid-asset breakdown for a fund series. - **`filing_id` (required)** `string` — Filing this point came from - **`record_index` (required)** `integer` — Per-filing 0-based ordinal of this point - **`date`** `object` — Date of this observation - **`granularity`** `object` — 'monthly' (filing date) or 'daily' (intra-month) - **`percentage_daily_liquid_assets`** `object` — Daily-liquid assets as a percent of total assets - **`percentage_weekly_liquid_assets`** `object` — Weekly-liquid assets as a percent of total assets - **`series_id`** `object` — SEC fund series identifier - **`series_name`** `object` — Fund series display name - **`total_value_daily_liquid_assets`** `object` — Total daily-liquid assets at this date (USD) - **`total_value_weekly_liquid_assets`** `object` — Total weekly-liquid assets at this date (USD) **Example:** ```json { "filing_id": "", "record_index": 1, "series_id": "", "series_name": "", "date": "", "total_value_daily_liquid_assets": "", "total_value_weekly_liquid_assets": "", "percentage_daily_liquid_assets": "", "percentage_weekly_liquid_assets": "", "granularity": "" } ``` ### ManagerStancePosition - **Type:**`object` One classified 13F position for the queried manager. - **`classification` (required)** `object` — Stance classification (see StanceClassification enum) - **`cusip`** `object` — Security CUSIP - **`has_historical_13d`** `boolean`, default: `false` — True if the manager has ever filed a 13D on this issuer - **`has_historical_13g`** `boolean`, default: `false` — True if the manager has ever filed a 13G on this issuer - **`most_recent_schedule_date`** `object` — event\_date of the most recent SC13 filing - **`most_recent_schedule_type`** `object` — 'D' or 'G' from the manager's most recent SC13 filing on this issuer - **`name_of_issuer`** `object` — Issuer name - **`value`** `object` — 13F-reported position value (thousands of USD) **Example:** ```json { "cusip": "", "name_of_issuer": "", "value": "", "classification": "passive", "most_recent_schedule_type": "", "most_recent_schedule_date": "", "has_historical_13d": false, "has_historical_13g": false } ``` ### ManagerStanceResponse - **Type:**`object` Stance breakdown for one (manager, period) — percent of portfolio in each stance bucket plus the per-position classifications. - **`filing_manager_cik` (required)** `string` — Filing manager CIK - **`pct_active` (required)** `number` — Share of total\_value classified active (0-1) - **`pct_passive` (required)** `number` — Share of total\_value classified passive (0-1) - **`pct_transitioned` (required)** `number` — Share of total\_value classified transitioned (0-1) - **`pct_unclassified` (required)** `number` — Share of total\_value classified unclassified (0-1) - **`period_of_report` (required)** `string`, format: `date` — 13F period analyzed - **`positions` (required)** `array` — Per-position rows **Items:** - **`classification` (required)** `object` — Stance classification (see StanceClassification enum) - **`cusip`** `object` — Security CUSIP - **`has_historical_13d`** `boolean`, default: `false` — True if the manager has ever filed a 13D on this issuer - **`has_historical_13g`** `boolean`, default: `false` — True if the manager has ever filed a 13G on this issuer - **`most_recent_schedule_date`** `object` — event\_date of the most recent SC13 filing - **`most_recent_schedule_type`** `object` — 'D' or 'G' from the manager's most recent SC13 filing on this issuer - **`name_of_issuer`** `object` — Issuer name - **`value`** `object` — 13F-reported position value (thousands of USD) - **`total_value` (required)** `string` — Total portfolio value across all positions (thousands of USD) - **`filing_manager_name`** `object` — Filing manager legal name **Example:** ```json { "filing_manager_cik": "", "filing_manager_name": "", "period_of_report": "", "total_value": "", "pct_passive": 1, "pct_active": 1, "pct_transitioned": 1, "pct_unclassified": 1, "positions": [ { "cusip": "", "name_of_issuer": "", "value": "", "classification": null, "most_recent_schedule_type": "", "most_recent_schedule_date": "", "has_historical_13d": false, "has_historical_13g": false } ] } ``` ### ManagerStanceTransitionRow - **Type:**`object` One position whose stance classification changed between periods. - **`current_classification` (required)** `object` — Stance at the current period. - **`prior_classification` (required)** `object` — Stance at the prior period. - **`current_value`** `object` — Position value at the current period (thousands of USD). - **`cusip`** `object` — Security CUSIP. - **`name_of_issuer`** `object` — Issuer name (modal across the two periods' rows). - **`prior_value`** `object` — Position value at the prior period (thousands of USD). **Example:** ```json { "cusip": "", "name_of_issuer": "", "prior_classification": "passive", "current_classification": "passive", "prior_value": "", "current_value": "" } ``` ### ManagerStanceTransitionsResponse - **Type:**`object` * **`current_period` (required)** `string`, format: `date` — Current 13F period compared. * **`filing_manager_cik` (required)** `string` — Filing manager CIK queried. * **`prior_period` (required)** `string`, format: `date` — Prior 13F period compared. * **`transitions` (required)** `array` — Positions whose classification changed between the two periods (excluding \`unclassified → unclassified\`). Sorted by absolute current\_value descending. **Items:** - **`current_classification` (required)** `object` — Stance at the current period. - **`prior_classification` (required)** `object` — Stance at the prior period. - **`current_value`** `object` — Position value at the current period (thousands of USD). - **`cusip`** `object` — Security CUSIP. - **`name_of_issuer`** `object` — Issuer name (modal across the two periods' rows). - **`prior_value`** `object` — Position value at the prior period (thousands of USD). * **`filing_manager_name`** `object` — Filing manager legal name. **Example:** ```json { "filing_manager_cik": "", "filing_manager_name": "", "prior_period": "", "current_period": "", "transitions": [ { "cusip": "", "name_of_issuer": "", "prior_classification": null, "current_classification": null, "prior_value": "", "current_value": "" } ] } ``` ### MetricFilter - **Type:**`object` Single metric filter for advanced multi-metric screening. - **`metric` (required)** `string` — Required. Metric name (e.g., 'revenue', 'net\_income'). - **`max_value`** `object` — Optional. Maximum value (inclusive). - **`min_value`** `object` — Optional. Minimum value (inclusive). **Example:** ```json { "metric": "", "min_value": 1, "max_value": 1 } ``` ### MetricScreenRequest - **Type:**`object` Request body for POST /companies/screen/advanced endpoint. Supports multiple metric filters with AND logic. - **`filters` (required)** `array` — Required. List of metric filters (AND logic). **Items:** - **`metric` (required)** `string` — Required. Metric name (e.g., 'revenue', 'net\_income'). - **`max_value`** `object` — Optional. Maximum value (inclusive). - **`min_value`** `object` — Optional. Minimum value (inclusive). - **`fiscal_year` (required)** `integer` — Required. Fiscal year to screen. - **`fiscal_quarter`** `object` — Optional. Fiscal quarter: 0=FY, 1-4=quarters (optional). - **`limit`** `integer`, default: `100` — Optional. Maximum results to return. **Example:** ```json { "filters": [ { "metric": "", "min_value": 1, "max_value": 1 } ], "fiscal_year": 1990, "fiscal_quarter": 0, "limit": 100 } ``` ### MetricScreenResponse - **Type:**`object` Response for single-metric screening. - **`data` (required)** `array` — Matching companies **Items:** - **`cik` (required)** `string` — SEC Central Index Key - **`fiscal_quarter` (required)** `integer` — Fiscal quarter - **`fiscal_year` (required)** `integer` — Fiscal year - **`metric` (required)** `string` — Metric name - **`company_name`** `object` — Company name - **`metric_value`** `object` — Metric value - **`period_label`** `object` — Period label - **`tickers`** `object` — Ticker symbols - **`total` (required)** `integer` — Total matching results **Example:** ```json { "data": [ { "cik": "", "company_name": "", "tickers": [ "" ], "fiscal_year": 1, "fiscal_quarter": 1, "period_label": "", "metric": "", "metric_value": 1 } ], "total": 1 } ``` ### MetricScreenResult - **Type:**`object` Single company result from metric screening. - **`cik` (required)** `string` — SEC Central Index Key - **`fiscal_quarter` (required)** `integer` — Fiscal quarter - **`fiscal_year` (required)** `integer` — Fiscal year - **`metric` (required)** `string` — Metric name - **`company_name`** `object` — Company name - **`metric_value`** `object` — Metric value - **`period_label`** `object` — Period label - **`tickers`** `object` — Ticker symbols **Example:** ```json { "cik": "", "company_name": "", "tickers": [ "" ], "fiscal_year": 1, "fiscal_quarter": 1, "period_label": "", "metric": "", "metric_value": 1 } ``` ### MoneyMarketFundFilingDetail - **Type:**`object` Per-filing detail — filing summary plus share classes and the full N-MFP2 portfolio metrics. Securities and the four time-series children are fetched via separate endpoints (linked by URL fields). - **`accession_num` (required)** `object` — EDGAR accession number derived from filing\_id (e.g., '0000320193-24-000123') - **`cik` (required)** `string` — Filer SEC Central Index Key - **`filing_id` (required)** `string` — Unique filing identifier - **`form_type` (required)** `string` — SEC form type (e.g., '4', '13F-HR', 'D') - **`source_url` (required)** `object` — Canonical SEC EDGAR Archives URL pointing at the filing's index page - **`accepted_time`** `object` — When SEC accepted the filing - **`administrator`** `object` — Fund administrator details - **`adviser`** `object` — Investment adviser firm details (one or more) - **`amortized_cost_portfolio_securities`** `object` — Amortized-cost value of portfolio securities (USD) - **`average_life_maturity`** `object` — Weighted average life maturity (WAL) in days, dollar-weighted - **`average_portfolio_maturity`** `object` — Weighted average portfolio maturity (WAM) in days, dollar-weighted - **`cash`** `object` — Total cash held by the fund (USD) - **`cash_mgmt_vehicle_affliated_fund_flag`** `object` — True if the fund is used as a cash-management vehicle by affiliated funds - **`class_flows_timeseries_count`** `object` — Total class-flows time-series points for this filing - **`class_flows_timeseries_url`** `object` — Convenience link to fetch class subscription/redemption time-series points - **`class_nav_timeseries_count`** `object` — Total class-NAV time-series points for this filing - **`class_nav_timeseries_url`** `object` — Convenience link to fetch class NAV time-series points - **`classes`** `array` — All share classes of this fund series **Items:** - **`record_index` (required)** `integer` — Per-filing 0-based ordinal of this class row - **`beneficial_record_owner_category`** `object` — Category of beneficial owner (e.g., 'Retail', 'NaturalPerson', 'Other') - **`class_full_name`** `object` — Share class display name (e.g., 'Institutional Class') - **`classes_id`** `object` — SEC share-class identifier (e.g., C000001234) - **`min_initial_investment`** `object` — Minimum initial investment for this share class (USD) - **`name_of_person_desc_expense_pay`** `object` — Name of the person paying expenses (where person\_pay\_for\_fund\_flag is true) - **`net_assets_of_class`** `object` — Net assets of the share class at period end (USD) - **`number_of_shares_outstanding`** `object` — Total shares outstanding for this class - **`person_pay_for_fund_flag`** `object` — True if a person (sponsor) is paying for fund expenses on behalf of this class - **`series_id`** `object` — SEC fund series identifier the class belongs to - **`series_name`** `object` — Fund series display name - **`seven_day_net_yield`** `object` — Class-level 7-day net yield (annualized, after fees) - **`shareholder_flows_monthly_redemptions`** `object` — Class-level total redemptions in the month (USD) - **`shareholder_flows_monthly_subscriptions`** `object` — Class-level total subscriptions in the month (USD) - **`feeder_fund_flag`** `object` — True if this is a feeder fund in a master-feeder structure - **`filer_name`** `object` — Filer entity name - **`filer_tickers`** `object` — Ticker symbols associated with the filer - **`fund_merged_or_acquired`** `object` — True if the fund merged with or was acquired by another fund - **`indp_pub_accountant`** `object` — Independent public accountant details - **`is_final_filing`** `object` — True if this is a final (de-registration) filing - **`is_valid`** `object` — Whether the filing passed validation - **`liquid_assets_timeseries_count`** `object` — Total liquid-assets time-series points for this filing - **`liquid_assets_timeseries_url`** `object` — Convenience link to fetch liquid-assets time-series points - **`liquidity_fee_fund_apply_flag`** `object` — True if the fund applied a liquidity fee in the period - **`master_fund_flag`** `object` — True if this is a master fund in a master-feeder structure - **`money_market_fund_category`** `object` — MMF category code (see query-param doc) - **`nav_timeseries_count`** `object` — Total series-NAV time-series points for this filing - **`nav_timeseries_url`** `object` — Convenience link to fetch series NAV time-series points - **`net_asset_of_series`** `object` — Net assets of the fund series at period end (USD) - **`period_of_report`** `object` — Reporting period end date - **`portfolio_dispositions`** `object` — JSON array of portfolio disposition events during the period - **`registrant_lei`** `object` — Fund registrant Legal Entity Identifier (20 chars) - **`registrant_name`** `object` — Fund registrant legal name - **`retail_money_market_fund_flag`** `object` — True if this is a retail (non-institutional) MMF - **`securities_act_file_number`** `object` — Securities Act file number (e.g., '333-12345') - **`securities_count`** `object` — Total portfolio securities reported on this filing - **`securities_url`** `object` — Convenience link to fetch this filing's securities rows - **`seek_stable_price_per_share`** `object` — True if the fund seeks to maintain a stable share price (versus a floating NAV) - **`series_id`** `object` — SEC fund series identifier - **`series_lei`** `object` — Fund series LEI - **`series_name`** `object` — Fund series display name - **`series_shares_outstanding`** `object` — Total shares outstanding across all classes of the series - **`seven_day_gross_yield`** `object` — Series-level 7-day gross yield (annualized) - **`signature`** `object` — Filing signature payload (signing officer + date) - **`stable_price_per_share`** `object` — Stable price per share if the fund seeks one (typically $1.0000) - **`sub_adviser`** `object` — Sub-adviser firm details (where applicable) - **`submission_type`** `object` — EDGAR submission type - **`total_share_classes`** `object` — Total share classes belonging to this series - **`total_value_liabilities`** `object` — Total liabilities of the fund (USD) - **`total_value_other_assets`** `object` — Total value of other assets (non-portfolio, non-cash) (USD) - **`total_value_portfolio_securities`** `object` — Total market value of portfolio securities (USD) - **`transfer_agent`** `object` — Transfer agent details **Example:** ```json { "filing_id": "", "cik": "", "form_type": "", "period_of_report": "", "accepted_time": "", "is_valid": true, "filer_name": "", "filer_tickers": [ "" ], "submission_type": "", "series_id": "", "registrant_name": "", "registrant_lei": "", "series_name": "", "series_lei": "", "total_share_classes": 1, "is_final_filing": true, "money_market_fund_category": "", "feeder_fund_flag": true, "master_fund_flag": true, "retail_money_market_fund_flag": true, "net_asset_of_series": "", "seven_day_gross_yield": "", "average_portfolio_maturity": "", "average_life_maturity": "", "cash": "", "total_value_portfolio_securities": "", "amortized_cost_portfolio_securities": "", "total_value_other_assets": "", "total_value_liabilities": "", "series_shares_outstanding": "", "stable_price_per_share": "", "seek_stable_price_per_share": true, "cash_mgmt_vehicle_affliated_fund_flag": true, "liquidity_fee_fund_apply_flag": true, "fund_merged_or_acquired": true, "securities_act_file_number": "", "portfolio_dispositions": null, "signature": null, "adviser": null, "sub_adviser": null, "indp_pub_accountant": null, "transfer_agent": null, "administrator": null, "classes": [ { "record_index": 1, "series_id": "", "series_name": "", "classes_id": "", "class_full_name": "", "min_initial_investment": "", "net_assets_of_class": "", "number_of_shares_outstanding": "", "seven_day_net_yield": "", "person_pay_for_fund_flag": true, "name_of_person_desc_expense_pay": "", "beneficial_record_owner_category": "", "shareholder_flows_monthly_subscriptions": "", "shareholder_flows_monthly_redemptions": "" } ], "securities_count": 1, "securities_url": "", "nav_timeseries_count": 1, "nav_timeseries_url": "", "liquid_assets_timeseries_count": 1, "liquid_assets_timeseries_url": "", "class_nav_timeseries_count": 1, "class_nav_timeseries_url": "", "class_flows_timeseries_count": 1, "class_flows_timeseries_url": "", "accession_num": "", "source_url": "" } ``` ### MoneyMarketFundFilingSummary - **Type:**`object` Filing-level summary for one Form N-MFP2 submission. - **`accession_num` (required)** `object` — EDGAR accession number derived from filing\_id (e.g., '0000320193-24-000123') - **`cik` (required)** `string` — Filer SEC Central Index Key - **`filing_id` (required)** `string` — Unique filing identifier - **`form_type` (required)** `string` — SEC form type (e.g., '4', '13F-HR', 'D') - **`source_url` (required)** `object` — Canonical SEC EDGAR Archives URL pointing at the filing's index page - **`accepted_time`** `object` — When SEC accepted the filing - **`feeder_fund_flag`** `object` — True if this is a feeder fund in a master-feeder structure - **`filer_name`** `object` — Filer entity name - **`filer_tickers`** `object` — Ticker symbols associated with the filer - **`is_final_filing`** `object` — True if this is a final (de-registration) filing - **`is_valid`** `object` — Whether the filing passed validation - **`master_fund_flag`** `object` — True if this is a master fund in a master-feeder structure - **`money_market_fund_category`** `object` — MMF category code (see query-param doc) - **`net_asset_of_series`** `object` — Net assets of the fund series at period end (USD) - **`period_of_report`** `object` — Reporting period end date - **`registrant_lei`** `object` — Fund registrant Legal Entity Identifier (20 chars) - **`registrant_name`** `object` — Fund registrant legal name - **`retail_money_market_fund_flag`** `object` — True if this is a retail (non-institutional) MMF - **`series_id`** `object` — SEC fund series identifier - **`series_lei`** `object` — Fund series LEI - **`series_name`** `object` — Fund series display name - **`seven_day_gross_yield`** `object` — Series-level 7-day gross yield (annualized) - **`submission_type`** `object` — EDGAR submission type - **`total_share_classes`** `object` — Total share classes belonging to this series **Example:** ```json { "filing_id": "", "cik": "", "form_type": "", "period_of_report": "", "accepted_time": "", "is_valid": true, "filer_name": "", "filer_tickers": [ "" ], "submission_type": "", "series_id": "", "registrant_name": "", "registrant_lei": "", "series_name": "", "series_lei": "", "total_share_classes": 1, "is_final_filing": true, "money_market_fund_category": "", "feeder_fund_flag": true, "master_fund_flag": true, "retail_money_market_fund_flag": true, "net_asset_of_series": "", "seven_day_gross_yield": "", "accession_num": "", "source_url": "" } ``` ### MoneyMarketFundsEntitiesListResponse - **Type:**`object` * **`data` (required)** `array` — Page of N-MFP2 registrants with money-market-fund data on file. **Items:** - **`cik` (required)** `string` — Required. Form\_cik (registrant CIK on N-MFP2; canonical short form). - **`filing_count` (required)** `integer` — Required. Total N-MFP2 filings on file for this registrant. - **`company_name`** `object` — Optional. Modal registrant name across the registrant's N-MFP2 filings. - **`period_max`** `object` — Optional. Latest period\_of\_report observed for this registrant. - **`period_min`** `object` — Optional. Earliest period\_of\_report observed for this registrant. - **`tickers`** `object` — Optional. Registrant ticker symbols sampled from one filing's \`filer\_tickers\`. * **`page_size` (required)** `integer` — Results per page * **`page`** `integer`, default: `1` — Current page number (1-indexed) * **`total`** `integer`, default: `0` — Total count of matching rows * **`total_pages`** `integer`, default: `1` — Total number of pages **Example:** ```json { "total": 0, "page": 1, "page_size": 1, "total_pages": 1, "data": [ { "cik": "", "company_name": "", "tickers": [ "" ], "filing_count": 1, "period_min": "", "period_max": "" } ] } ``` ### MoneyMarketFundsEntitySummary - **Type:**`object` Per-registrant summary of Form N-MFP2 filing availability. Grouped by `form_cik` (the established registrant proxy on this view — see api\_money\_market\_funds\_service.py:70 for the pattern). Modal `registrant_name` dodges the spelling drift caught in the round-4 audit. - **`cik` (required)** `string` — Required. Form\_cik (registrant CIK on N-MFP2; canonical short form). - **`filing_count` (required)** `integer` — Required. Total N-MFP2 filings on file for this registrant. - **`company_name`** `object` — Optional. Modal registrant name across the registrant's N-MFP2 filings. - **`period_max`** `object` — Optional. Latest period\_of\_report observed for this registrant. - **`period_min`** `object` — Optional. Earliest period\_of\_report observed for this registrant. - **`tickers`** `object` — Optional. Registrant ticker symbols sampled from one filing's \`filer\_tickers\`. **Example:** ```json { "cik": "", "company_name": "", "tickers": [ "" ], "filing_count": 1, "period_min": "", "period_max": "" } ``` ### MoneyMarketFundsListResponse - **Type:**`object` * **`data` (required)** `array` — Page of N-MFP2 filing rows **Items:** - **`accession_num` (required)** `object` — EDGAR accession number derived from filing\_id (e.g., '0000320193-24-000123') - **`cik` (required)** `string` — Filer SEC Central Index Key - **`filing_id` (required)** `string` — Unique filing identifier - **`form_type` (required)** `string` — SEC form type (e.g., '4', '13F-HR', 'D') - **`source_url` (required)** `object` — Canonical SEC EDGAR Archives URL pointing at the filing's index page - **`accepted_time`** `object` — When SEC accepted the filing - **`feeder_fund_flag`** `object` — True if this is a feeder fund in a master-feeder structure - **`filer_name`** `object` — Filer entity name - **`filer_tickers`** `object` — Ticker symbols associated with the filer - **`is_final_filing`** `object` — True if this is a final (de-registration) filing - **`is_valid`** `object` — Whether the filing passed validation - **`master_fund_flag`** `object` — True if this is a master fund in a master-feeder structure - **`money_market_fund_category`** `object` — MMF category code (see query-param doc) - **`net_asset_of_series`** `object` — Net assets of the fund series at period end (USD) - **`period_of_report`** `object` — Reporting period end date - **`registrant_lei`** `object` — Fund registrant Legal Entity Identifier (20 chars) - **`registrant_name`** `object` — Fund registrant legal name - **`retail_money_market_fund_flag`** `object` — True if this is a retail (non-institutional) MMF - **`series_id`** `object` — SEC fund series identifier - **`series_lei`** `object` — Fund series LEI - **`series_name`** `object` — Fund series display name - **`seven_day_gross_yield`** `object` — Series-level 7-day gross yield (annualized) - **`submission_type`** `object` — EDGAR submission type - **`total_share_classes`** `object` — Total share classes belonging to this series * **`page_size` (required)** `integer` — Results per page * **`page`** `integer`, default: `1` — Current page number (1-indexed) * **`total`** `integer`, default: `0` — Total count of matching rows * **`total_pages`** `integer`, default: `1` — Total number of pages **Example:** ```json { "total": 0, "page": 1, "page_size": 1, "total_pages": 1, "data": [ { "filing_id": "", "cik": "", "form_type": "", "period_of_report": "", "accepted_time": "", "is_valid": true, "filer_name": "", "filer_tickers": [ "" ], "submission_type": "", "series_id": "", "registrant_name": "", "registrant_lei": "", "series_name": "", "series_lei": "", "total_share_classes": 1, "is_final_filing": true, "money_market_fund_category": "", "feeder_fund_flag": true, "master_fund_flag": true, "retail_money_market_fund_flag": true, "net_asset_of_series": "", "seven_day_gross_yield": "", "accession_num": "", "source_url": "" } ] } ``` ### MoneyMarketSecuritiesResponse - **Type:**`object` * **`data` (required)** `array` — Page of N-MFP2 security rows **Items:** - **`filing_id` (required)** `string` — Filing this security belongs to - **`record_index` (required)** `integer` — Per-filing 0-based ordinal of this security row - **`coupon`** `object` — Coupon rate of the security (annualized) - **`cusip_member`** `object` — CUSIP of the held security - **`daily_liquid_asset_security_flag`** `object` — True if security counts as a daily-liquid asset - **`excluding_value_of_any_sponsor_support`** `object` — Security value excluding any sponsor support (USD) - **`final_legal_investment_maturity_date`** `object` — Final legal maturity date of the security - **`illiquid_security_flag`** `object` — True if security is classified as illiquid under Rule 2a-7 - **`including_value_of_any_sponsor_support`** `object` — Security value including any sponsor support (USD) - **`investment_category`** `object` — N-MFP2 investment category (see query-param doc) - **`investment_maturity_date_wal`** `object` — Days to maturity used for WAL calculation (regulatory definition) - **`investment_maturity_date_wam`** `object` — Days to maturity used for WAM calculation (regulatory definition) - **`isin_id`** `object` — ISIN of the held security (12 chars) - **`lei_id`** `object` — Issuer LEI (20 chars) - **`name_of_issuer`** `object` — Issuer name of the held security - **`percentage_of_money_market_fund_net_assets`** `object` — Security as a percent of fund net assets - **`period_of_report`** `object` — Reporting period end date - **`security_eligibility_flag`** `object` — Rule 2a-7 eligibility tier: 'First Tier' or 'Second Tier' - **`series_id`** `object` — SEC fund series identifier - **`series_name`** `object` — Fund series display name - **`title_of_issuer`** `object` — Title / description of the security - **`weekly_liquid_asset_security_flag`** `object` — True if security counts as a weekly-liquid asset - **`yield_of_the_security_as_of_reporting_date`** `object` — Security yield at the reporting date (annualized) * **`page_size` (required)** `integer` — Results per page * **`page`** `integer`, default: `1` — Current page number (1-indexed) * **`total`** `integer`, default: `0` — Total count of matching rows * **`total_pages`** `integer`, default: `1` — Total number of pages **Example:** ```json { "total": 0, "page": 1, "page_size": 1, "total_pages": 1, "data": [ { "filing_id": "", "record_index": 1, "period_of_report": "", "series_id": "", "series_name": "", "name_of_issuer": "", "title_of_issuer": "", "cusip_member": "", "isin_id": "", "lei_id": "", "investment_category": "", "security_eligibility_flag": "", "investment_maturity_date_wam": 1, "investment_maturity_date_wal": 1, "final_legal_investment_maturity_date": "", "yield_of_the_security_as_of_reporting_date": "", "including_value_of_any_sponsor_support": "", "excluding_value_of_any_sponsor_support": "", "percentage_of_money_market_fund_net_assets": "", "daily_liquid_asset_security_flag": true, "weekly_liquid_asset_security_flag": true, "illiquid_security_flag": true, "coupon": "" } ] } ``` ### MostActiveFilerRow - **Type:**`object` * **`cik` (required)** `string` — Issuer SEC Central Index Key (short form). * **`filing_count` (required)** `integer` — Filings accepted in the window for this (cik, family) pair. * **`rank` (required)** `integer` — 1-indexed rank in this leaderboard. * **`company_name`** `object` — Modal issuer name across the window's filings. * **`tickers`** `object` — Issuer ticker symbols when known. **Example:** ```json { "rank": 1, "cik": "", "company_name": "", "tickers": [ "" ], "filing_count": 1 } ``` ### MostActiveFilersLeaderboardResponse - **Type:**`object` * **`data` (required)** `array` — Filers ranked by \`filing\_count\` descending. **Items:** - **`cik` (required)** `string` — Issuer SEC Central Index Key (short form). - **`filing_count` (required)** `integer` — Filings accepted in the window for this (cik, family) pair. - **`rank` (required)** `integer` — 1-indexed rank in this leaderboard. - **`company_name`** `object` — Modal issuer name across the window's filings. - **`tickers`** `object` — Issuer ticker symbols when known. * **`family` (required)** `object` — Family this leaderboard is scoped to. * **`window` (required)** `object` — Window the leaderboard ranks over. - **`lookback_days` (required)** `integer` — Window length in days (until - since). - **`since` (required)** `string`, format: `date` — Window start (inclusive). - **`until` (required)** `string`, format: `date` — Window end (inclusive). **Example:** ```json { "window": { "since": "", "until": "", "lookback_days": 1 }, "family": "insiders", "data": [ { "rank": 1, "cik": "", "company_name": "", "tickers": [ "" ], "filing_count": 1 } ] } ``` ### MostAmendedFilerRow - **Type:**`object` * **`amendment_count` (required)** `integer` — Filings flagged as amendments within \`filing\_count\`. * **`amendment_ratio` (required)** `number` — amendment\_count / filing\_count, clamped to \[0, 1]. * **`cik` (required)** `string` — Issuer SEC Central Index Key (short form). * **`filing_count` (required)** `integer` — Filings accepted in the window for this (cik, family) pair. * **`rank` (required)** `integer` — 1-indexed rank in this leaderboard. * **`company_name`** `object` — Modal issuer name across the window's filings. * **`tickers`** `object` — Issuer ticker symbols when known. **Example:** ```json { "rank": 1, "cik": "", "company_name": "", "tickers": [ "" ], "filing_count": 1, "amendment_count": 1, "amendment_ratio": 1 } ``` ### MostAmendedLeaderboardResponse - **Type:**`object` * **`data` (required)** `array` — Filers ranked by \`amendment\_ratio\` descending. **Items:** - **`amendment_count` (required)** `integer` — Filings flagged as amendments within \`filing\_count\`. - **`amendment_ratio` (required)** `number` — amendment\_count / filing\_count, clamped to \[0, 1]. - **`cik` (required)** `string` — Issuer SEC Central Index Key (short form). - **`filing_count` (required)** `integer` — Filings accepted in the window for this (cik, family) pair. - **`rank` (required)** `integer` — 1-indexed rank in this leaderboard. - **`company_name`** `object` — Modal issuer name across the window's filings. - **`tickers`** `object` — Issuer ticker symbols when known. * **`family` (required)** `object` — Family this leaderboard is scoped to. * **`window` (required)** `object` — Window the leaderboard ranks over. - **`lookback_days` (required)** `integer` — Window length in days (until - since). - **`since` (required)** `string`, format: `date` — Window start (inclusive). - **`until` (required)** `string`, format: `date` — Window end (inclusive). **Example:** ```json { "window": { "since": "", "until": "", "lookback_days": 1 }, "family": "insiders", "data": [ { "rank": 1, "cik": "", "company_name": "", "tickers": [ "" ], "filing_count": 1, "amendment_count": 1, "amendment_ratio": 1 } ] } ``` ### MultiMetricScreenResponse - **Type:**`object` Response for multi-metric advanced screening. - **`data` (required)** `array` — Companies matching ALL metric criteria **Items:** - **`cik` (required)** `string` — SEC Central Index Key - **`company_name`** `object` — Company name - **`tickers`** `object` — Ticker symbols - **`filters_applied` (required)** `array` — Filters that were applied **Items:** - **`metric` (required)** `string` — Required. Metric name (e.g., 'revenue', 'net\_income'). - **`max_value`** `object` — Optional. Maximum value (inclusive). - **`min_value`** `object` — Optional. Minimum value (inclusive). - **`total` (required)** `integer` — Total matching companies **Example:** ```json { "data": [ { "cik": "", "company_name": "", "tickers": [ "" ] } ], "total": 1, "filters_applied": [ { "metric": "", "min_value": 1, "max_value": 1 } ] } ``` ### MultiMetricScreenResult - **Type:**`object` Company result from multi-metric screening (no specific metric values). - **`cik` (required)** `string` — SEC Central Index Key - **`company_name`** `object` — Company name - **`tickers`** `object` — Ticker symbols **Example:** ```json { "cik": "", "company_name": "", "tickers": [ "" ] } ``` ### NarrativeFilingDetail - **Type:**`object` Per-filing detail — filing summary only. Sections are NOT bundled (a single S-1 may have 20-50 multi-KB sections); fetch them via `sections_url`. - **`accession_num` (required)** `object` — EDGAR accession number derived from filing\_id (e.g., '0000320193-24-000123') - **`cik` (required)** `string` — Filer SEC Central Index Key - **`filing_id` (required)** `string` — Unique filing identifier - **`form_type` (required)** `string` — SEC form type (e.g., 'S-1', 'S-1/A', 'F-3') - **`source_url` (required)** `object` — Canonical SEC EDGAR Archives URL pointing at the filing's index page - **`accepted_time`** `object` — When the SEC accepted the filing - **`filer_name`** `object` — Filer entity name - **`filer_sic`** `object` — Filer Standard Industrial Classification (SIC) code (e.g., '7372' Prepackaged Software) - **`filer_tickers`** `object` — Ticker symbols associated with the filer - **`is_valid`** `object` — Whether the filing passed validation - **`period_of_report`** `object` — Reporting period end (datetime for prospectus filings) - **`section_count`** `object` — Total prospectus sections extracted from this filing - **`sections_url`** `object` — Link to /narratives/sections?filing\_id={filing\_id} for the per-filing section drill-down **Example:** ```json { "filing_id": "", "cik": "", "form_type": "", "period_of_report": "", "accepted_time": "", "is_valid": true, "filer_name": "", "filer_tickers": [ "" ], "filer_sic": "", "section_count": 1, "sections_url": "", "accession_num": "", "source_url": "" } ``` ### NarrativeFilingSummary - **Type:**`object` Filing-level summary for one registration-statement prospectus submission (S-1 / S-3 / S-3ASR / S-4 / S-11 / F-1 / F-3 / F-4 and their amendments). `accession_num` and `source_url` are derived from `filing_id` via FilingSourceMixin. - **`accession_num` (required)** `object` — EDGAR accession number derived from filing\_id (e.g., '0000320193-24-000123') - **`cik` (required)** `string` — Filer SEC Central Index Key - **`filing_id` (required)** `string` — Unique filing identifier - **`form_type` (required)** `string` — SEC form type (e.g., 'S-1', 'S-1/A', 'F-3') - **`source_url` (required)** `object` — Canonical SEC EDGAR Archives URL pointing at the filing's index page - **`accepted_time`** `object` — When the SEC accepted the filing - **`filer_name`** `object` — Filer entity name - **`filer_sic`** `object` — Filer Standard Industrial Classification (SIC) code (e.g., '7372' Prepackaged Software) - **`filer_tickers`** `object` — Ticker symbols associated with the filer - **`is_valid`** `object` — Whether the filing passed validation - **`period_of_report`** `object` — Reporting period end (datetime for prospectus filings) - **`section_count`** `object` — Total prospectus sections extracted from this filing **Example:** ```json { "filing_id": "", "cik": "", "form_type": "", "period_of_report": "", "accepted_time": "", "is_valid": true, "filer_name": "", "filer_tickers": [ "" ], "filer_sic": "", "section_count": 1, "accession_num": "", "source_url": "" } ``` ### NarrativeFilingsListResponse - **Type:**`object` * **`data` (required)** `array` — Page of registration-statement filing rows **Items:** - **`accession_num` (required)** `object` — EDGAR accession number derived from filing\_id (e.g., '0000320193-24-000123') - **`cik` (required)** `string` — Filer SEC Central Index Key - **`filing_id` (required)** `string` — Unique filing identifier - **`form_type` (required)** `string` — SEC form type (e.g., 'S-1', 'S-1/A', 'F-3') - **`source_url` (required)** `object` — Canonical SEC EDGAR Archives URL pointing at the filing's index page - **`accepted_time`** `object` — When the SEC accepted the filing - **`filer_name`** `object` — Filer entity name - **`filer_sic`** `object` — Filer Standard Industrial Classification (SIC) code (e.g., '7372' Prepackaged Software) - **`filer_tickers`** `object` — Ticker symbols associated with the filer - **`is_valid`** `object` — Whether the filing passed validation - **`period_of_report`** `object` — Reporting period end (datetime for prospectus filings) - **`section_count`** `object` — Total prospectus sections extracted from this filing * **`page_size` (required)** `integer` — Results per page * **`page`** `integer`, default: `1` — Current page number (1-indexed) * **`total`** `integer`, default: `0` — Total count of matching rows * **`total_pages`** `integer`, default: `1` — Total number of pages **Example:** ```json { "total": 0, "page": 1, "page_size": 1, "total_pages": 1, "data": [ { "filing_id": "", "cik": "", "form_type": "", "period_of_report": "", "accepted_time": "", "is_valid": true, "filer_name": "", "filer_tickers": [ "" ], "filer_sic": "", "section_count": 1, "accession_num": "", "source_url": "" } ] } ``` ### NarrativeSectionResponse - **Type:**`object` One prospectus section row — a categorized text section extracted from a registration-statement filing (e.g., 'Risk Factors', 'Use of Proceeds', 'Description of Capital Stock'). - **`filing_id` (required)** `string` — Filing this section belongs to - **`section_id` (required)** `string`, format: `uuid` — Unique section identifier (UUID v4) - **`accepted_time`** `object` — When the parent filing was accepted by the SEC - **`cik`** `object` — Filer CIK - **`filer_name`** `object` — Filer entity name - **`form_type`** `object` — SEC form type of the parent filing - **`is_valid`** `object` — Whether the parent filing passed validation - **`page_number`** `object` — Source page number(s) where this section appears in the filed PDF - **`period_of_report`** `object` — Reporting period of the parent filing - **`section_order`** `object` — 0-based ordinal of this section within the filing - **`section_title`** `object` — Section title as extracted from the prospectus (e.g., 'Risk Factors') - **`table_count`** `object` — Count of tables extracted from this section - **`table_json`** `object` — Structured tables extracted from the section (omitted when include\_text=false) - **`text_json`** `object` — Structured narrative text — paragraphs, lists, headings (omitted when include\_text=false) - **`text_length`** `object` — Total character length of the section's narrative text - **`validated_json`** `object` — Validated / normalized JSON extraction of the section's structured content **Example:** ```json { "section_id": "", "filing_id": "", "cik": "", "form_type": "", "accepted_time": "", "period_of_report": "", "is_valid": true, "filer_name": "", "section_title": "", "section_order": 1, "page_number": "", "text_length": 1, "table_count": 1, "text_json": null, "table_json": null, "validated_json": null } ``` ### NarrativeSectionsListResponse - **Type:**`object` * **`data` (required)** `array` — Page of prospectus section rows **Items:** - **`filing_id` (required)** `string` — Filing this section belongs to - **`section_id` (required)** `string`, format: `uuid` — Unique section identifier (UUID v4) - **`accepted_time`** `object` — When the parent filing was accepted by the SEC - **`cik`** `object` — Filer CIK - **`filer_name`** `object` — Filer entity name - **`form_type`** `object` — SEC form type of the parent filing - **`is_valid`** `object` — Whether the parent filing passed validation - **`page_number`** `object` — Source page number(s) where this section appears in the filed PDF - **`period_of_report`** `object` — Reporting period of the parent filing - **`section_order`** `object` — 0-based ordinal of this section within the filing - **`section_title`** `object` — Section title as extracted from the prospectus (e.g., 'Risk Factors') - **`table_count`** `object` — Count of tables extracted from this section - **`table_json`** `object` — Structured tables extracted from the section (omitted when include\_text=false) - **`text_json`** `object` — Structured narrative text — paragraphs, lists, headings (omitted when include\_text=false) - **`text_length`** `object` — Total character length of the section's narrative text - **`validated_json`** `object` — Validated / normalized JSON extraction of the section's structured content * **`page_size` (required)** `integer` — Results per page * **`page`** `integer`, default: `1` — Current page number (1-indexed) * **`total`** `integer`, default: `0` — Total count of matching rows * **`total_pages`** `integer`, default: `1` — Total number of pages **Example:** ```json { "total": 0, "page": 1, "page_size": 1, "total_pages": 1, "data": [ { "section_id": "", "filing_id": "", "cik": "", "form_type": "", "accepted_time": "", "period_of_report": "", "is_valid": true, "filer_name": "", "section_title": "", "section_order": 1, "page_number": "", "text_length": 1, "table_count": 1, "text_json": null, "table_json": null, "validated_json": null } ] } ``` ### NarrativesEntitiesListResponse - **Type:**`object` * **`data` (required)** `array` — Page of issuers with registration-statement narrative data on file. **Items:** - **`cik` (required)** `string` — Required. Issuer SEC Central Index Key (canonical short form, no leading zeros). - **`filing_count` (required)** `integer` — Required. Total registration-statement filings on file for this issuer. - **`company_name`** `object` — Optional. Modal issuer name across the issuer's narrative filings. - **`period_max`** `object` — Optional. Latest period\_of\_report observed for this issuer. - **`period_min`** `object` — Optional. Earliest period\_of\_report observed for this issuer. - **`tickers`** `object` — Optional. Issuer ticker symbols sampled from one filing's \`filer\_tickers\`. * **`page_size` (required)** `integer` — Results per page * **`page`** `integer`, default: `1` — Current page number (1-indexed) * **`total`** `integer`, default: `0` — Total count of matching rows * **`total_pages`** `integer`, default: `1` — Total number of pages **Example:** ```json { "total": 0, "page": 1, "page_size": 1, "total_pages": 1, "data": [ { "cik": "", "company_name": "", "tickers": [ "" ], "filing_count": 1, "period_min": "", "period_max": "" } ] } ``` ### NarrativesEntitySummary - **Type:**`object` Per-issuer summary of registration-statement filing availability. One row per distinct `cik` with modal `filer_name`, total filing count, and observed period-of-report range. - **`cik` (required)** `string` — Required. Issuer SEC Central Index Key (canonical short form, no leading zeros). - **`filing_count` (required)** `integer` — Required. Total registration-statement filings on file for this issuer. - **`company_name`** `object` — Optional. Modal issuer name across the issuer's narrative filings. - **`period_max`** `object` — Optional. Latest period\_of\_report observed for this issuer. - **`period_min`** `object` — Optional. Earliest period\_of\_report observed for this issuer. - **`tickers`** `object` — Optional. Issuer ticker symbols sampled from one filing's \`filer\_tickers\`. **Example:** ```json { "cik": "", "company_name": "", "tickers": [ "" ], "filing_count": 1, "period_min": "", "period_max": "" } ``` ### NavTimeseriesResponse - **Type:**`object` * **`data` (required)** `array` — Page of series-NAV time-series points **Items:** - **`filing_id` (required)** `string` — Filing this point came from - **`record_index` (required)** `integer` — Per-filing 0-based ordinal of this point - **`date`** `object` — Date of this NAV observation - **`granularity`** `object` — 'monthly' (filing date) or 'daily' (intra-month) - **`series_id`** `object` — SEC fund series identifier - **`series_name`** `object` — Fund series display name - **`value`** `object` — NAV value at this date (USD) * **`page_size` (required)** `integer` — Results per page * **`page`** `integer`, default: `1` — Current page number (1-indexed) * **`total`** `integer`, default: `0` — Total count of matching rows * **`total_pages`** `integer`, default: `1` — Total number of pages **Example:** ```json { "total": 0, "page": 1, "page_size": 1, "total_pages": 1, "data": [ { "filing_id": "", "record_index": 1, "series_id": "", "series_name": "", "date": "", "value": "", "granularity": "" } ] } ``` ### NavTimeseriesRow - **Type:**`object` One series-NAV time-series point — one date's NAV value for a fund series. - **`filing_id` (required)** `string` — Filing this point came from - **`record_index` (required)** `integer` — Per-filing 0-based ordinal of this point - **`date`** `object` — Date of this NAV observation - **`granularity`** `object` — 'monthly' (filing date) or 'daily' (intra-month) - **`series_id`** `object` — SEC fund series identifier - **`series_name`** `object` — Fund series display name - **`value`** `object` — NAV value at this date (USD) **Example:** ```json { "filing_id": "", "record_index": 1, "series_id": "", "series_name": "", "date": "", "value": "", "granularity": "" } ``` ### NcenClassResponse - **Type:**`object` One share-class row from an N-CEN filing — a single share class of a parent fund series. - **`record_index` (required)** `integer` — Per-filing 0-based ordinal of this class row - **`series_index` (required)** `integer` — record\_index of the parent series row in the same filing's series\[] list - **`class_id`** `object` — SEC share class identifier (e.g., C000001234) - **`extra_data`** `object` — Additional class-level fields (varies by investment-company type) - **`series_id`** `object` — SEC fund series identifier the class belongs to **Example:** ```json { "series_index": 1, "record_index": 1, "series_id": "", "class_id": "", "extra_data": null } ``` ### NcenSeriesResponse - **Type:**`object` One series row from an N-CEN filing — a fund series of the registrant (a registered investment company can house multiple fund series under the same registration). - **`record_index` (required)** `integer` — Per-filing 0-based ordinal of this series row - **`include_all_classes_flag`** `object` — True if the filing reports for all share classes of this series - **`registrant_cik`** `object` — Fund registrant CIK - **`registrant_name`** `object` — Fund registrant legal name - **`series_id`** `object` — SEC fund series identifier (e.g., S000001234) **Example:** ```json { "record_index": 1, "series_id": "", "include_all_classes_flag": true, "registrant_cik": "", "registrant_name": "" } ``` ### NmfpClassResponse - **Type:**`object` One share-class row from an N-MFP2 filing — share class of the parent fund series. A single MMF series can have multiple classes (e.g., 'Institutional', 'Retail', 'Capital'). - **`record_index` (required)** `integer` — Per-filing 0-based ordinal of this class row - **`beneficial_record_owner_category`** `object` — Category of beneficial owner (e.g., 'Retail', 'NaturalPerson', 'Other') - **`class_full_name`** `object` — Share class display name (e.g., 'Institutional Class') - **`classes_id`** `object` — SEC share-class identifier (e.g., C000001234) - **`min_initial_investment`** `object` — Minimum initial investment for this share class (USD) - **`name_of_person_desc_expense_pay`** `object` — Name of the person paying expenses (where person\_pay\_for\_fund\_flag is true) - **`net_assets_of_class`** `object` — Net assets of the share class at period end (USD) - **`number_of_shares_outstanding`** `object` — Total shares outstanding for this class - **`person_pay_for_fund_flag`** `object` — True if a person (sponsor) is paying for fund expenses on behalf of this class - **`series_id`** `object` — SEC fund series identifier the class belongs to - **`series_name`** `object` — Fund series display name - **`seven_day_net_yield`** `object` — Class-level 7-day net yield (annualized, after fees) - **`shareholder_flows_monthly_redemptions`** `object` — Class-level total redemptions in the month (USD) - **`shareholder_flows_monthly_subscriptions`** `object` — Class-level total subscriptions in the month (USD) **Example:** ```json { "record_index": 1, "series_id": "", "series_name": "", "classes_id": "", "class_full_name": "", "min_initial_investment": "", "net_assets_of_class": "", "number_of_shares_outstanding": "", "seven_day_net_yield": "", "person_pay_for_fund_flag": true, "name_of_person_desc_expense_pay": "", "beneficial_record_owner_category": "", "shareholder_flows_monthly_subscriptions": "", "shareholder_flows_monthly_redemptions": "" } ``` ### NmfpSecurityResponse - **Type:**`object` One portfolio security row from an N-MFP2 filing — a single holding in the money-market fund's portfolio. - **`filing_id` (required)** `string` — Filing this security belongs to - **`record_index` (required)** `integer` — Per-filing 0-based ordinal of this security row - **`coupon`** `object` — Coupon rate of the security (annualized) - **`cusip_member`** `object` — CUSIP of the held security - **`daily_liquid_asset_security_flag`** `object` — True if security counts as a daily-liquid asset - **`excluding_value_of_any_sponsor_support`** `object` — Security value excluding any sponsor support (USD) - **`final_legal_investment_maturity_date`** `object` — Final legal maturity date of the security - **`illiquid_security_flag`** `object` — True if security is classified as illiquid under Rule 2a-7 - **`including_value_of_any_sponsor_support`** `object` — Security value including any sponsor support (USD) - **`investment_category`** `object` — N-MFP2 investment category (see query-param doc) - **`investment_maturity_date_wal`** `object` — Days to maturity used for WAL calculation (regulatory definition) - **`investment_maturity_date_wam`** `object` — Days to maturity used for WAM calculation (regulatory definition) - **`isin_id`** `object` — ISIN of the held security (12 chars) - **`lei_id`** `object` — Issuer LEI (20 chars) - **`name_of_issuer`** `object` — Issuer name of the held security - **`percentage_of_money_market_fund_net_assets`** `object` — Security as a percent of fund net assets - **`period_of_report`** `object` — Reporting period end date - **`security_eligibility_flag`** `object` — Rule 2a-7 eligibility tier: 'First Tier' or 'Second Tier' - **`series_id`** `object` — SEC fund series identifier - **`series_name`** `object` — Fund series display name - **`title_of_issuer`** `object` — Title / description of the security - **`weekly_liquid_asset_security_flag`** `object` — True if security counts as a weekly-liquid asset - **`yield_of_the_security_as_of_reporting_date`** `object` — Security yield at the reporting date (annualized) **Example:** ```json { "filing_id": "", "record_index": 1, "period_of_report": "", "series_id": "", "series_name": "", "name_of_issuer": "", "title_of_issuer": "", "cusip_member": "", "isin_id": "", "lei_id": "", "investment_category": "", "security_eligibility_flag": "", "investment_maturity_date_wam": 1, "investment_maturity_date_wal": 1, "final_legal_investment_maturity_date": "", "yield_of_the_security_as_of_reporting_date": "", "including_value_of_any_sponsor_support": "", "excluding_value_of_any_sponsor_support": "", "percentage_of_money_market_fund_net_assets": "", "daily_liquid_asset_security_flag": true, "weekly_liquid_asset_security_flag": true, "illiquid_security_flag": true, "coupon": "" } ``` ### NonderivHoldingResponse - **Type:**`object` One non-derivative holding row from a Form 3/4/5 — a position in the issuer's common stock or other non-derivative securities. - **`record_index` (required)** `integer` — Per-filing 0-based ordinal of this holding row - **`direct_or_indirect_ownership`** `object` — 'D' = direct ownership, 'I' = indirect (e.g., via trust or family member) - **`nature_of_ownership`** `object` — Free-text describing indirect ownership (e.g., 'By spouse', 'By trust') - **`security_title`** `object` — Security name (e.g., 'Common Stock', 'Class A Common') - **`shares_owned_following_transaction`** `object` — Total shares beneficially owned after the most recent transaction - **`value_owned_following_transaction`** `object` — Total USD value beneficially owned after the most recent transaction **Example:** ```json { "record_index": 1, "security_title": "", "shares_owned_following_transaction": "", "value_owned_following_transaction": "", "direct_or_indirect_ownership": "", "nature_of_ownership": "" } ``` ### NonderivTransactionResponse - **Type:**`object` One non-derivative transaction row from a Form 4/5 — a buy, sell, grant, gift, or other transaction in the issuer's common stock. - **`record_index` (required)** `integer` — Per-filing 0-based ordinal of this transaction row - **`direct_or_indirect_ownership`** `object` — 'D' = direct ownership, 'I' = indirect - **`security_title`** `object` — Security name (e.g., 'Common Stock') - **`shares_owned_following_transaction`** `object` — Total shares owned after this transaction settles - **`transaction_acquired_disposed_code`** `object` — 'A' = shares acquired, 'D' = shares disposed - **`transaction_code`** `object` — Single-letter transaction code (e.g., P=open-market purchase, S=open-market sale, A=grant, M=option exercise, F=tax-withholding) - **`transaction_date`** `object` — Date the transaction occurred - **`transaction_price_per_share`** `object` — Price per share; 0 for grants, gifts, and other no-cost transactions - **`transaction_shares`** `object` — Number of shares involved in the transaction **Example:** ```json { "record_index": 1, "security_title": "", "transaction_date": "", "transaction_code": "", "transaction_acquired_disposed_code": "", "transaction_shares": "", "transaction_price_per_share": "", "shares_owned_following_transaction": "", "direct_or_indirect_ownership": "" } ``` ### NportHoldingResponse - **Type:**`object` One row from the N-PORT investments table — a single position held by a fund series at the report period end. - **`filing_id` (required)** `string` — Filing this holding belongs to - **`record_index` (required)** `integer` — Per-filing 0-based ordinal of this holding row - **`asset_cat`** `object` — N-PORT asset category code (e.g., 'EC' equity, 'DBT' debt, 'DCO' commodity) - **`balance`** `object` — Position size in \`units\` (shares, principal amount, contracts) - **`cur_cd`** `object` — ISO 4217 currency code of the underlying security - **`cusip`** `object` — CUSIP (8-9 chars); '000000000' / 'N/A' indicate not assigned - **`fair_val_level`** `object` — Fair-value hierarchy level: 1 (quoted), 2 (observable), 3 (unobservable) - **`inv_country`** `object` — Issuer country (ISO 3166-1 alpha-2 code) - **`is_restricted_sec`** `object` — True if this is a restricted security (Rule 144A etc.) - **`isin`** `object` — International Securities Identification Number (12 chars) - **`issuer_cat`** `object` — N-PORT issuer category code (e.g., 'CORP' corporate, 'TREA' treasury) - **`lei`** `object` — Issuer LEI (20-char Legal Entity Identifier) - **`name`** `object` — Issuer name of the held security - **`other_id`** `object` — Alternate security identifier (when CUSIP/ISIN unavailable) - **`other_id_desc`** `object` — Description of the identifier in \`other\_id\` (e.g., 'INTERNAL', 'TICKER') - **`payoff_profile`** `object` — Payoff direction: 'Long' or 'Short' (derivatives may be either) - **`pct_val`** `object` — Position as a percent of the fund series' net assets - **`period_of_report`** `object` — Reporting period end date - **`registrant_cik`** `object` — Fund registrant CIK - **`registrant_name`** `object` — Fund registrant legal name - **`series_id`** `object` — SEC fund series identifier - **`series_name`** `object` — Fund series display name - **`title`** `object` — Security title / description (e.g., '5.50% Senior Notes due 2030') - **`units`** `object` — Unit type for \`balance\` (NS=number of shares, PA=principal amount, NC=number of contracts) - **`val_usd`** `object` — Position value in USD at period-end mark **Example:** ```json { "asset_cat": "EC", "balance": "129084215", "cur_cd": "USD", "cusip": "037833100", "fair_val_level": 1, "filing_id": "0000884394_0001752724-24-049321", "inv_country": "US", "is_restricted_sec": false, "isin": "US0378331005", "issuer_cat": "CORP", "lei": "HWUPKR0MPOU8FGXBT394", "name": "APPLE INC", "payoff_profile": "Long", "pct_val": "6.84", "period_of_report": "2024-03-31", "record_index": 12, "registrant_cik": "0000884394", "registrant_name": "VANGUARD INDEX FUNDS", "series_id": "S000001234", "series_name": "Vanguard 500 Index Fund", "title": "Common Stock", "units": "NS", "val_usd": "22117483560.50" } ``` ### NpxVoteResponse - **Type:**`object` One vote record from a Form N-PX filing — a single proposal voted on at a single meeting for a single security. - **`record_index` (required)** `integer` — Per-filing 0-based ordinal of this vote row - **`cusip`** `object` — 9-character CUSIP of the security being voted - **`isin`** `object` — 12-character ISIN of the security being voted - **`issuer_name`** `object` — Issuer name (the company holding the meeting) - **`meeting_date`** `object` — Date of the shareholder meeting - **`shares_on_loan`** `object` — Shares of this security on loan (and therefore not available to vote) - **`shares_voted`** `object` — Number of shares the reporting fund voted - **`vote_categories`** `object` — Structured vote-category tags assigned to this proposal - **`vote_description`** `object` — Description of the proposal being voted on - **`vote_records`** `object` — Per-fund vote records (one filing may report votes for multiple funds) - **`vote_source`** `object` — Source of the vote decision (e.g., 'M' management recommendation, 'S' shareholder, 'B' both) **Example:** ```json { "record_index": 1, "meeting_date": "", "issuer_name": "", "cusip": "", "isin": "", "vote_description": "", "shares_voted": "", "shares_on_loan": "", "vote_source": "", "vote_categories": null, "vote_records": null } ``` ### OtherManagerResponse - **Type:**`object` One row from the 13F other-managers list — managers also included on this filing under a joint or umbrella arrangement. - **`record_index` (required)** `integer` — Per-filing 0-based ordinal of this manager row - **`crd_number`** `object` — FINRA CRD number for the other manager - **`form13_f_file_number`** `object` — Form 13F file number (e.g., '028-12345') - **`other_manager_cik`** `object` — Other manager SEC CIK - **`other_manager_name`** `object` — Other manager legal name - **`sec_file_number`** `object` — SEC file number for the other manager (e.g., '801-12345' for advisers) **Example:** ```json { "record_index": 1, "other_manager_cik": "", "other_manager_name": "", "form13_f_file_number": "", "crd_number": "", "sec_file_number": "" } ``` ### OwnershipAtlasResponse - **Type:**`object` Combined 13F + N-PORT ownership view for one security at one period. - **`breakdowns` (required)** `array` — Per-holder-type breakdowns (13F + N-PORT) **Items:** - **`aggregate_value` (required)** `string` — Total reported value (USD) - **`holder_count` (required)** `integer` — Distinct holders in this bucket - **`holder_type` (required)** `string` — 'institutional\_manager\_13f' (13F filers) or 'registered\_fund\_nport' (N-PORT registered investment companies). These overlap conceptually but disclosure regimes differ: 13F captures investment managers at the firm level; N-PORT captures individual fund series. - **`aggregate_shares`** `object` — Total reported shares (where comparable) - **`cusip` (required)** `string` — Security CUSIP queried - **`period_of_report` (required)** `string`, format: `date` — Period analyzed - **`top_10_share_pct_13f` (required)** `number` — Top-10 13F managers' share of 13F aggregate value (0-1) - **`top_10_share_pct_nport` (required)** `number` — Top-10 N-PORT funds' share of N-PORT aggregate value (0-1) - **`total_aggregate_value` (required)** `string` — Sum of aggregate\_value across types - **`total_holders` (required)** `integer` — Sum of holder\_count across types - **`name_of_issuer`** `object` — Issuer name **Example:** ```json { "cusip": "", "name_of_issuer": "", "period_of_report": "", "breakdowns": [ { "holder_type": "", "holder_count": 1, "aggregate_value": "", "aggregate_shares": "" } ], "total_holders": 1, "total_aggregate_value": "", "top_10_share_pct_13f": 1, "top_10_share_pct_nport": 1 } ``` ### PeriodType - **Type:**`string` Statement period types. **Example:** ### Position - **Type:**`object` One amendment-resolved 13F position — the canonical (post-amendment, confidential-treatment-lifted) holdings row for one (manager, period, security). - **`cusip`** `object` — Security CUSIP - **`figi`** `object` — OpenFIGI identifier (12 chars) - **`investment_discretion`** `object` — 'SOLE', 'DFND' (defined), or 'OTR' (other shared) - **`name_of_issuer`** `object` — Issuer name - **`ssh_prnamt`** `object` — Number of shares or principal amount - **`ssh_prnamt_type`** `object` — Type of ssh\_prnamt: 'SH' = shares, 'PRN' = principal - **`title_of_class`** `object` — Title of class (e.g., 'COM', 'CL A') - **`value`** `object` — Position value (in thousands of USD per Form 13F) - **`voting_none`** `object` — Shares with no voting authority - **`voting_shared`** `object` — Shares with shared voting authority - **`voting_sole`** `object` — Shares with sole voting authority **Example:** ```json { "cusip": "", "figi": "", "name_of_issuer": "", "title_of_class": "", "value": "", "ssh_prnamt": "", "ssh_prnamt_type": "", "voting_sole": "", "voting_shared": "", "voting_none": "", "investment_discretion": "" } ``` ### PrivateCapitalFormationResponse - **Type:**`object` Quarterly Form D capital-formation index across a window — aggregate totals plus per-quarter (and optionally per-industry) buckets. - **`aggregate_distinct_issuers` (required)** `integer` — Distinct issuers across the window - **`aggregate_filing_count` (required)** `integer` — Total Form D filings across the entire window - **`aggregate_total_offering` (required)** `string` — Total offering amount across the window (USD) - **`aggregate_total_sold` (required)** `string` — Total amount sold across the window (USD) - **`buckets` (required)** `array` — Quarterly (and optionally per-industry) buckets **Items:** - **`filing_count` (required)** `integer` — Form D filings in this bucket - **`is_40_act_count` (required)** `integer` — Filings flagged as Investment Company Act of 1940 funds - **`issuer_count` (required)** `integer` — Distinct issuers (issuer\_cik) in this bucket - **`period_end` (required)** `string`, format: `date` — Quarter end (e.g., '2025-09-30') - **`period_start` (required)** `string`, format: `date` — Quarter start (e.g., '2025-07-01') - **`total_amount_sold` (required)** `string` — Sum of total amount sold to date in this bucket (USD) - **`total_offering_amount` (required)** `string` — Sum of total offering amounts in this bucket (USD) - **`avg_offering_size`** `object` — Mean offering amount (total\_offering\_amount / filing\_count) - **`industry_group_type`** `object` — Industry bucket; null when include\_industry\_breakdown=false - **`include_industry_breakdown` (required)** `boolean` — Whether buckets are split per (quarter × industry) or per quarter only - **`since` (required)** `string`, format: `date` — Window start applied - **`until` (required)** `string`, format: `date` — Window end applied - **`industry_filter`** `object` — industry\_group\_type filter applied (if any) - **`is_40_act_filter`** `object` — 40 Act filter applied (true / false / null) **Example:** ```json { "since": "", "until": "", "industry_filter": "", "is_40_act_filter": true, "include_industry_breakdown": true, "aggregate_filing_count": 1, "aggregate_total_offering": "", "aggregate_total_sold": "", "aggregate_distinct_issuers": 1, "buckets": [ { "period_start": "", "period_end": "", "industry_group_type": "", "filing_count": 1, "issuer_count": 1, "total_offering_amount": "", "total_amount_sold": "", "avg_offering_size": "", "is_40_act_count": 1 } ] } ``` ### PrivateCapitalIndustryResponse - **Type:**`object` * **`data` (required)** `array` — Industries ranked by \`total\_offering\_amount\_sum\` descending. **Items:** - **`distinct_filer_count` (required)** `integer` — Distinct filer CIKs within this industry in the window. - **`filing_count` (required)** `integer` — Form D filings classified to this industry within the window. - **`industry_group_type` (required)** `string` — Form D \`industry\_group\_type\` value (e.g., 'Pooled Investment Fund'). - **`total_amount_sold_sum`** `object` — Sum of \`total\_amount\_sold\` (USD) across the filings in this industry. - **`total_offering_amount_sum`** `object` — Sum of \`total\_offering\_amount\` (USD) across the filings in this industry; null when no filing reports an amount. * **`since`** `object` — Window start applied to filings.accepted\_time, when supplied. * **`until`** `object` — Window end applied to filings.accepted\_time, when supplied. **Example:** ```json { "since": "", "until": "", "data": [ { "industry_group_type": "", "filing_count": 1, "distinct_filer_count": 1, "total_offering_amount_sum": "", "total_amount_sold_sum": "" } ] } ``` ### PrivateCapitalIndustryRow - **Type:**`object` * **`distinct_filer_count` (required)** `integer` — Distinct filer CIKs within this industry in the window. * **`filing_count` (required)** `integer` — Form D filings classified to this industry within the window. * **`industry_group_type` (required)** `string` — Form D \`industry\_group\_type\` value (e.g., 'Pooled Investment Fund'). * **`total_amount_sold_sum`** `object` — Sum of \`total\_amount\_sold\` (USD) across the filings in this industry. * **`total_offering_amount_sum`** `object` — Sum of \`total\_offering\_amount\` (USD) across the filings in this industry; null when no filing reports an amount. **Example:** ```json { "industry_group_type": "", "filing_count": 1, "distinct_filer_count": 1, "total_offering_amount_sum": "", "total_amount_sold_sum": "" } ``` ### PrivateOfferingDetail - **Type:**`object` Per-filing detail — filing summary plus issuers and related-persons rows. - **`accession_num` (required)** `object` — EDGAR accession number derived from filing\_id (e.g., '0000320193-24-000123') - **`cik` (required)** `string` — Filer SEC Central Index Key - **`filing_id` (required)** `string` — Unique filing identifier - **`form_type` (required)** `string` — SEC form type (e.g., '4', '13F-HR', 'D') - **`source_url` (required)** `object` — Canonical SEC EDGAR Archives URL pointing at the filing's index page - **`accepted_time`** `object` — When SEC accepted the filing - **`federal_exemptions_exclusions`** `object` — List of Securities Act exemption/exclusion citations (e.g., \['Rule 506(b)', 'Section 4(a)(2)']) - **`filer_name`** `object` — Filer entity name - **`filer_tickers`** `object` — Ticker symbols associated with the filer - **`form_data`** `object` — Full Form D form\_data JSON (omit by passing include\_form\_data=false on the request) - **`industry_group_type`** `object` — Form D industry group code (see query-param doc) - **`investment_fund_type`** `object` — Investment-fund type for fund issuers (see query-param doc) - **`is_40_act`** `object` — True if the issuer is a registered investment company under the 1940 Act - **`is_amendment`** `object` — True if this filing is an amendment - **`is_valid`** `object` — Whether the filing passed validation - **`issuers`** `array` — All issuer rows on this filing **Items:** - **`record_index` (required)** `integer` — Per-filing 0-based ordinal of this issuer row - **`entity_name`** `object` — Issuer legal name - **`entity_type`** `object` — Entity type (e.g., 'Corporation', 'Limited Partnership', 'Limited Liability Company') - **`issuer_cik`** `object` — Issuer SEC CIK (where the issuer has one) - **`issuer_city`** `object` — Issuer city - **`issuer_phone`** `object` — Issuer contact phone number - **`issuer_state_or_country`** `object` — Issuer state code or country code - **`issuer_state_or_country_description`** `object` — Human-readable state / country name - **`issuer_street1`** `object` — Issuer street address line 1 - **`issuer_street2`** `object` — Issuer street address line 2 - **`issuer_zip_code`** `object` — Issuer postal code - **`jurisdiction_of_inc`** `object` — State or country of incorporation/organization (e.g., 'DELAWARE') - **`year_of_inc`** `object` — Year of incorporation/organization - **`minimum_investment_accepted`** `object` — Minimum investment accepted from any one investor (USD) - **`period_of_report`** `object` — Reporting period end date - **`related_persons`** `array` — All related-person rows on this filing (officers, directors, promoters) **Items:** - **`record_index` (required)** `integer` — Per-filing 0-based ordinal of this person row - **`address_city`** `object` — Person's city - **`address_state_or_country`** `object` — Person's state code or country code - **`address_state_or_country_description`** `object` — Human-readable state / country name - **`address_street1`** `object` — Person's street address line 1 - **`address_street2`** `object` — Person's street address line 2 - **`address_zip_code`** `object` — Person's postal code - **`first_name`** `object` — Given name - **`last_name`** `object` — Family name - **`middle_name`** `object` — Middle name - **`relationship_clarification`** `object` — Free-text clarification of the relationship (where 'Other' is selected) - **`relationships`** `object` — Relationship tags (e.g., \['Executive Officer', 'Director', 'Promoter']) - **`submission_type`** `object` — EDGAR submission type - **`total_amount_sold`** `object` — Total amount sold to date (USD) - **`total_offering_amount`** `object` — Total offering amount (USD) - **`total_remaining`** `object` — Total amount remaining to be sold (USD; offering minus amount sold) **Example:** ```json { "filing_id": "", "cik": "", "form_type": "", "period_of_report": "", "accepted_time": "", "is_valid": true, "filer_name": "", "filer_tickers": [ "" ], "is_amendment": true, "submission_type": "", "industry_group_type": "", "investment_fund_type": "", "is_40_act": true, "total_offering_amount": "", "total_amount_sold": "", "total_remaining": "", "minimum_investment_accepted": "", "federal_exemptions_exclusions": null, "form_data": null, "issuers": [ { "record_index": 1, "issuer_cik": "", "entity_name": "", "jurisdiction_of_inc": "", "entity_type": "", "year_of_inc": "", "issuer_phone": "", "issuer_street1": "", "issuer_street2": "", "issuer_city": "", "issuer_state_or_country": "", "issuer_state_or_country_description": "", "issuer_zip_code": "" } ], "related_persons": [ { "record_index": 1, "first_name": "", "middle_name": "", "last_name": "", "address_street1": "", "address_street2": "", "address_city": "", "address_state_or_country": "", "address_state_or_country_description": "", "address_zip_code": "", "relationships": null, "relationship_clarification": "" } ], "accession_num": "", "source_url": "" } ``` ### PrivateOfferingSummary - **Type:**`object` Filing-level summary for one Form D submission. - **`accession_num` (required)** `object` — EDGAR accession number derived from filing\_id (e.g., '0000320193-24-000123') - **`cik` (required)** `string` — Filer SEC Central Index Key - **`filing_id` (required)** `string` — Unique filing identifier - **`form_type` (required)** `string` — SEC form type (e.g., '4', '13F-HR', 'D') - **`source_url` (required)** `object` — Canonical SEC EDGAR Archives URL pointing at the filing's index page - **`accepted_time`** `object` — When SEC accepted the filing - **`filer_name`** `object` — Filer entity name - **`filer_tickers`** `object` — Ticker symbols associated with the filer - **`industry_group_type`** `object` — Form D industry group code (see query-param doc) - **`investment_fund_type`** `object` — Investment-fund type for fund issuers (see query-param doc) - **`is_40_act`** `object` — True if the issuer is a registered investment company under the 1940 Act - **`is_amendment`** `object` — True if this filing is an amendment - **`is_valid`** `object` — Whether the filing passed validation - **`minimum_investment_accepted`** `object` — Minimum investment accepted from any one investor (USD) - **`period_of_report`** `object` — Reporting period end date - **`submission_type`** `object` — EDGAR submission type - **`total_amount_sold`** `object` — Total amount sold to date (USD) - **`total_offering_amount`** `object` — Total offering amount (USD) - **`total_remaining`** `object` — Total amount remaining to be sold (USD; offering minus amount sold) **Example:** ```json { "filing_id": "", "cik": "", "form_type": "", "period_of_report": "", "accepted_time": "", "is_valid": true, "filer_name": "", "filer_tickers": [ "" ], "is_amendment": true, "submission_type": "", "industry_group_type": "", "investment_fund_type": "", "is_40_act": true, "total_offering_amount": "", "total_amount_sold": "", "total_remaining": "", "minimum_investment_accepted": "", "accession_num": "", "source_url": "" } ``` ### PrivateOfferingsEntitiesListResponse - **Type:**`object` * **`data` (required)** `array` — Page of filers with Form D data on file. **Items:** - **`cik` (required)** `string` — Required. Filer SEC Central Index Key (canonical short form, no leading zeros). - **`filing_count` (required)** `integer` — Required. Total Form D filings on file for this filer. - **`company_name`** `object` — Optional. Modal filer name across the filer's Form D filings. - **`period_max`** `object` — Optional. Latest period\_of\_report observed for this filer. - **`period_min`** `object` — Optional. Earliest period\_of\_report observed for this filer. - **`tickers`** `object` — Optional. Filer ticker symbols sampled from one filing's \`filer\_tickers\`. - **`total_offering_amount_sum`** `object` — Optional. SUM of \`total\_offering\_amount\` across this filer's Form D filings (USD; null when no filing reports an amount). * **`page_size` (required)** `integer` — Results per page * **`page`** `integer`, default: `1` — Current page number (1-indexed) * **`total`** `integer`, default: `0` — Total count of matching rows * **`total_pages`** `integer`, default: `1` — Total number of pages **Example:** ```json { "total": 0, "page": 1, "page_size": 1, "total_pages": 1, "data": [ { "cik": "1234567", "company_name": "Acme Capital Partners LP", "filing_count": 12, "period_max": "2024-03-31", "period_min": "2019-06-30", "total_offering_amount_sum": "525000000" } ] } ``` ### PrivateOfferingsEntitySummary - **Type:**`object` Per-filer summary of Form D filing availability. One row per distinct filer `cik` with the modal `filer_name` across that filer's filings, filing count, period range, and the SUM of `total_offering_amount` across non-null filings. - **`cik` (required)** `string` — Required. Filer SEC Central Index Key (canonical short form, no leading zeros). - **`filing_count` (required)** `integer` — Required. Total Form D filings on file for this filer. - **`company_name`** `object` — Optional. Modal filer name across the filer's Form D filings. - **`period_max`** `object` — Optional. Latest period\_of\_report observed for this filer. - **`period_min`** `object` — Optional. Earliest period\_of\_report observed for this filer. - **`tickers`** `object` — Optional. Filer ticker symbols sampled from one filing's \`filer\_tickers\`. - **`total_offering_amount_sum`** `object` — Optional. SUM of \`total\_offering\_amount\` across this filer's Form D filings (USD; null when no filing reports an amount). **Example:** ```json { "cik": "1234567", "company_name": "Acme Capital Partners LP", "filing_count": 12, "period_max": "2024-03-31", "period_min": "2019-06-30", "total_offering_amount_sum": "525000000" } ``` ### PrivateOfferingsListResponse - **Type:**`object` * **`data` (required)** `array` — Page of Form D filing rows **Items:** - **`accession_num` (required)** `object` — EDGAR accession number derived from filing\_id (e.g., '0000320193-24-000123') - **`cik` (required)** `string` — Filer SEC Central Index Key - **`filing_id` (required)** `string` — Unique filing identifier - **`form_type` (required)** `string` — SEC form type (e.g., '4', '13F-HR', 'D') - **`source_url` (required)** `object` — Canonical SEC EDGAR Archives URL pointing at the filing's index page - **`accepted_time`** `object` — When SEC accepted the filing - **`filer_name`** `object` — Filer entity name - **`filer_tickers`** `object` — Ticker symbols associated with the filer - **`industry_group_type`** `object` — Form D industry group code (see query-param doc) - **`investment_fund_type`** `object` — Investment-fund type for fund issuers (see query-param doc) - **`is_40_act`** `object` — True if the issuer is a registered investment company under the 1940 Act - **`is_amendment`** `object` — True if this filing is an amendment - **`is_valid`** `object` — Whether the filing passed validation - **`minimum_investment_accepted`** `object` — Minimum investment accepted from any one investor (USD) - **`period_of_report`** `object` — Reporting period end date - **`submission_type`** `object` — EDGAR submission type - **`total_amount_sold`** `object` — Total amount sold to date (USD) - **`total_offering_amount`** `object` — Total offering amount (USD) - **`total_remaining`** `object` — Total amount remaining to be sold (USD; offering minus amount sold) * **`page_size` (required)** `integer` — Results per page * **`page`** `integer`, default: `1` — Current page number (1-indexed) * **`total`** `integer`, default: `0` — Total count of matching rows * **`total_pages`** `integer`, default: `1` — Total number of pages **Example:** ```json { "total": 0, "page": 1, "page_size": 1, "total_pages": 1, "data": [ { "filing_id": "", "cik": "", "form_type": "", "period_of_report": "", "accepted_time": "", "is_valid": true, "filer_name": "", "filer_tickers": [ "" ], "is_amendment": true, "submission_type": "", "industry_group_type": "", "investment_fund_type": "", "is_40_act": true, "total_offering_amount": "", "total_amount_sold": "", "total_remaining": "", "minimum_investment_accepted": "", "accession_num": "", "source_url": "" } ] } ``` ### ProposedSaleDetail - **Type:**`object` Per-filing detail — filing summary plus original-acquisition rows and Rule 144 prior-sales rows. - **`accession_num` (required)** `object` — EDGAR accession number derived from filing\_id (e.g., '0000320193-24-000123') - **`cik` (required)** `string` — Filer SEC Central Index Key - **`filing_id` (required)** `string` — Unique filing identifier - **`form_type` (required)** `string` — SEC form type (e.g., '4', '13F-HR', 'D') - **`source_url` (required)** `object` — Canonical SEC EDGAR Archives URL pointing at the filing's index page - **`accepted_time`** `object` — When SEC accepted the filing - **`acquisitions`** `array` — Original-acquisition rows for the securities being proposed for sale **Items:** - **`record_index` (required)** `integer` — Per-filing 0-based ordinal of this acquisition row - **`acquired_date`** `object` — Date the securities were originally acquired - **`amount_of_securities_acquired`** `object` — Number of units acquired in the original transaction - **`is_gift_transaction`** `object` — True if the original acquisition was a gift - **`name_of_person_from_whom_acquired`** `object` — Name of the prior owner (where applicable, e.g., for gifts or inheritances) - **`nature_of_acquisition_transaction`** `object` — Free-text description of how the securities were acquired (e.g., 'Stock Option Exercise', 'Gift', 'Inheritance') - **`nature_of_payment`** `object` — Free-text description of how payment was made - **`payment_date`** `object` — Date payment was made for the securities - **`securities_class_title`** `object` — Class of securities acquired - **`aggregate_market_value`** `object` — Aggregate market value of proposed sale (USD) - **`approx_sale_date`** `object` — Approximate date of proposed sale - **`broker_city`** `object` — Broker city - **`broker_name`** `object` — Executing broker name - **`broker_state_or_country`** `object` — Broker state code or country - **`broker_street1`** `object` — Broker street address line 1 - **`broker_zip_code`** `object` — Broker postal code - **`filer_name`** `object` — Filer entity name - **`filer_tickers`** `object` — Ticker symbols associated with the filer - **`is_valid`** `object` — Whether the filing passed validation - **`issuer_cik`** `object` — Issuer CIK (the company whose securities are being sold) - **`issuer_city`** `object` — Issuer city - **`issuer_name`** `object` — Issuer legal name - **`issuer_phone`** `object` — Issuer contact phone number - **`issuer_state_or_country`** `object` — Issuer state code or country - **`issuer_street1`** `object` — Issuer street address line 1 - **`issuer_zip_code`** `object` — Issuer postal code - **`no_of_units_outstanding`** `object` — Total units of this class outstanding - **`no_of_units_sold`** `object` — Number of units proposed for sale - **`nothing_to_report_past_3_months`** `object` — True if filer reports no Rule 144 sales of this security in the past 3 months - **`notice_date`** `object` — Date the notice of proposed sale was given - **`period_of_report`** `object` — Reporting period end date - **`plan_adoption_dates`** `object` — Rule 10b5-1 trading plan adoption dates (where the sale is made under such a plan) - **`previous_accession_number`** `object` — Accession number of the seller's prior Form 144 (where applicable) - **`prior_sales`** `array` — Rule 144 prior-sale rows for the past 3 months (volume-limit context) **Items:** - **`record_index` (required)** `integer` — Per-filing 0-based ordinal of this prior-sale row - **`amount_of_securities_sold`** `object` — Number of units sold in the prior sale - **`gross_proceeds`** `object` — Gross proceeds from the prior sale (USD) - **`sale_date`** `object` — Date of the prior sale - **`securities_class_title`** `object` — Class of securities previously sold - **`seller_name`** `object` — Name of the seller for this prior sale - **`relationships_to_issuer`** `object` — Seller's relationship(s) to the issuer (e.g., 'Officer', 'Director', '10% Shareholder') - **`remarks`** `object` — Free-text remarks attached to the filing - **`sec_file_number`** `object` — SEC file number of the issuer - **`securities_class_title`** `object` — Class of securities proposed for sale (e.g., 'Common Stock', 'Class A Common') - **`securities_exchange_name`** `object` — Exchange where the sale will occur (e.g., 'NYSE', 'NASDAQ') - **`seller_name`** `object` — Seller name (typically an officer, director, or major holder) - **`signature`** `object` — Seller signature attestation - **`submission_type`** `object` — EDGAR submission type **Example:** ```json { "filing_id": "", "cik": "", "form_type": "", "period_of_report": "", "accepted_time": "", "is_valid": true, "filer_name": "", "filer_tickers": [ "" ], "submission_type": "", "issuer_cik": "", "issuer_name": "", "seller_name": "", "securities_class_title": "", "no_of_units_sold": "", "aggregate_market_value": "", "no_of_units_outstanding": "", "approx_sale_date": "", "securities_exchange_name": "", "nothing_to_report_past_3_months": true, "notice_date": "", "previous_accession_number": "", "sec_file_number": "", "issuer_phone": "", "issuer_street1": "", "issuer_city": "", "issuer_state_or_country": "", "issuer_zip_code": "", "relationships_to_issuer": null, "broker_name": "", "broker_street1": "", "broker_city": "", "broker_state_or_country": "", "broker_zip_code": "", "plan_adoption_dates": null, "remarks": "", "signature": "", "acquisitions": [ { "record_index": 1, "securities_class_title": "", "acquired_date": "", "nature_of_acquisition_transaction": "", "name_of_person_from_whom_acquired": "", "is_gift_transaction": true, "amount_of_securities_acquired": "", "payment_date": "", "nature_of_payment": "" } ], "prior_sales": [ { "record_index": 1, "seller_name": "", "securities_class_title": "", "sale_date": "", "amount_of_securities_sold": "", "gross_proceeds": "" } ], "accession_num": "", "source_url": "" } ``` ### ProposedSaleSummary - **Type:**`object` Filing-level summary for one Form 144 submission. - **`accession_num` (required)** `object` — EDGAR accession number derived from filing\_id (e.g., '0000320193-24-000123') - **`cik` (required)** `string` — Filer SEC Central Index Key - **`filing_id` (required)** `string` — Unique filing identifier - **`form_type` (required)** `string` — SEC form type (e.g., '4', '13F-HR', 'D') - **`source_url` (required)** `object` — Canonical SEC EDGAR Archives URL pointing at the filing's index page - **`accepted_time`** `object` — When SEC accepted the filing - **`aggregate_market_value`** `object` — Aggregate market value of proposed sale (USD) - **`approx_sale_date`** `object` — Approximate date of proposed sale - **`filer_name`** `object` — Filer entity name - **`filer_tickers`** `object` — Ticker symbols associated with the filer - **`is_valid`** `object` — Whether the filing passed validation - **`issuer_cik`** `object` — Issuer CIK (the company whose securities are being sold) - **`issuer_name`** `object` — Issuer legal name - **`no_of_units_outstanding`** `object` — Total units of this class outstanding - **`no_of_units_sold`** `object` — Number of units proposed for sale - **`nothing_to_report_past_3_months`** `object` — True if filer reports no Rule 144 sales of this security in the past 3 months - **`notice_date`** `object` — Date the notice of proposed sale was given - **`period_of_report`** `object` — Reporting period end date - **`securities_class_title`** `object` — Class of securities proposed for sale (e.g., 'Common Stock', 'Class A Common') - **`securities_exchange_name`** `object` — Exchange where the sale will occur (e.g., 'NYSE', 'NASDAQ') - **`seller_name`** `object` — Seller name (typically an officer, director, or major holder) - **`submission_type`** `object` — EDGAR submission type **Example:** ```json { "filing_id": "", "cik": "", "form_type": "", "period_of_report": "", "accepted_time": "", "is_valid": true, "filer_name": "", "filer_tickers": [ "" ], "submission_type": "", "issuer_cik": "", "issuer_name": "", "seller_name": "", "securities_class_title": "", "no_of_units_sold": "", "aggregate_market_value": "", "no_of_units_outstanding": "", "approx_sale_date": "", "securities_exchange_name": "", "nothing_to_report_past_3_months": true, "notice_date": "", "accession_num": "", "source_url": "" } ``` ### ProposedSalesEntitiesListResponse - **Type:**`object` * **`data` (required)** `array` — Page of issuers with Form 144 data on file. **Items:** - **`cik` (required)** `string` — Required. Issuer SEC Central Index Key (canonical short form, no leading zeros). - **`filing_count` (required)** `integer` — Required. Total Form 144 filings on file naming this issuer. - **`company_name`** `object` — Optional. Modal issuer name across the issuer's Form 144 filings. - **`period_max`** `object` — Optional. Latest period\_of\_report observed for this issuer. - **`period_min`** `object` — Optional. Earliest period\_of\_report observed for this issuer. - **`tickers`** `object` — Optional. Issuer ticker symbols sampled from one filing's \`filer\_tickers\`. * **`page_size` (required)** `integer` — Results per page * **`page`** `integer`, default: `1` — Current page number (1-indexed) * **`total`** `integer`, default: `0` — Total count of matching rows * **`total_pages`** `integer`, default: `1` — Total number of pages **Example:** ```json { "total": 0, "page": 1, "page_size": 1, "total_pages": 1, "data": [ { "cik": "", "company_name": "", "tickers": [ "" ], "filing_count": 1, "period_min": "", "period_max": "" } ] } ``` ### ProposedSalesEntitySummary - **Type:**`object` Per-issuer summary of Form 144 filing availability. One row per distinct `issuer_cik` (the public company whose stock is being sold) with modal `issuer_name`, total filing count, and observed period-of-report range. - **`cik` (required)** `string` — Required. Issuer SEC Central Index Key (canonical short form, no leading zeros). - **`filing_count` (required)** `integer` — Required. Total Form 144 filings on file naming this issuer. - **`company_name`** `object` — Optional. Modal issuer name across the issuer's Form 144 filings. - **`period_max`** `object` — Optional. Latest period\_of\_report observed for this issuer. - **`period_min`** `object` — Optional. Earliest period\_of\_report observed for this issuer. - **`tickers`** `object` — Optional. Issuer ticker symbols sampled from one filing's \`filer\_tickers\`. **Example:** ```json { "cik": "", "company_name": "", "tickers": [ "" ], "filing_count": 1, "period_min": "", "period_max": "" } ``` ### ProposedSalesListResponse - **Type:**`object` * **`data` (required)** `array` — Page of Form 144 filing rows **Items:** - **`accession_num` (required)** `object` — EDGAR accession number derived from filing\_id (e.g., '0000320193-24-000123') - **`cik` (required)** `string` — Filer SEC Central Index Key - **`filing_id` (required)** `string` — Unique filing identifier - **`form_type` (required)** `string` — SEC form type (e.g., '4', '13F-HR', 'D') - **`source_url` (required)** `object` — Canonical SEC EDGAR Archives URL pointing at the filing's index page - **`accepted_time`** `object` — When SEC accepted the filing - **`aggregate_market_value`** `object` — Aggregate market value of proposed sale (USD) - **`approx_sale_date`** `object` — Approximate date of proposed sale - **`filer_name`** `object` — Filer entity name - **`filer_tickers`** `object` — Ticker symbols associated with the filer - **`is_valid`** `object` — Whether the filing passed validation - **`issuer_cik`** `object` — Issuer CIK (the company whose securities are being sold) - **`issuer_name`** `object` — Issuer legal name - **`no_of_units_outstanding`** `object` — Total units of this class outstanding - **`no_of_units_sold`** `object` — Number of units proposed for sale - **`nothing_to_report_past_3_months`** `object` — True if filer reports no Rule 144 sales of this security in the past 3 months - **`notice_date`** `object` — Date the notice of proposed sale was given - **`period_of_report`** `object` — Reporting period end date - **`securities_class_title`** `object` — Class of securities proposed for sale (e.g., 'Common Stock', 'Class A Common') - **`securities_exchange_name`** `object` — Exchange where the sale will occur (e.g., 'NYSE', 'NASDAQ') - **`seller_name`** `object` — Seller name (typically an officer, director, or major holder) - **`submission_type`** `object` — EDGAR submission type * **`page_size` (required)** `integer` — Results per page * **`page`** `integer`, default: `1` — Current page number (1-indexed) * **`total`** `integer`, default: `0` — Total count of matching rows * **`total_pages`** `integer`, default: `1` — Total number of pages **Example:** ```json { "total": 0, "page": 1, "page_size": 1, "total_pages": 1, "data": [ { "filing_id": "", "cik": "", "form_type": "", "period_of_report": "", "accepted_time": "", "is_valid": true, "filer_name": "", "filer_tickers": [ "" ], "submission_type": "", "issuer_cik": "", "issuer_name": "", "seller_name": "", "securities_class_title": "", "no_of_units_sold": "", "aggregate_market_value": "", "no_of_units_outstanding": "", "approx_sale_date": "", "securities_exchange_name": "", "nothing_to_report_past_3_months": true, "notice_date": "", "accession_num": "", "source_url": "" } ] } ``` ### ProxyVoteFilingDetail - **Type:**`object` Per-filing detail — filing summary plus all vote records. - **`accession_num` (required)** `object` — EDGAR accession number derived from filing\_id (e.g., '0000320193-24-000123') - **`cik` (required)** `string` — Filer SEC Central Index Key - **`filing_id` (required)** `string` — Unique filing identifier - **`form_type` (required)** `string` — SEC form type (e.g., '4', '13F-HR', 'D') - **`source_url` (required)** `object` — Canonical SEC EDGAR Archives URL pointing at the filing's index page - **`accepted_time`** `object` — When SEC accepted the filing - **`amendment_no`** `object` — Amendment number for amendment filings - **`amendment_type`** `object` — Type of amendment for amendment filings - **`confidential_treatment`** `object` — True if filing requested confidential treatment - **`file_number`** `object` — Investment Company Act file number - **`filer_name`** `object` — Filer entity name - **`filer_tickers`** `object` — Ticker symbols associated with the filer - **`form_data`** `object` — Full N-PX form\_data JSON (omit by passing include\_form\_data=false on the request) - **`is_amendment`** `object` — True if this filing is an amendment - **`is_valid`** `object` — Whether the filing passed validation - **`period_of_report`** `object` — Reporting period end date - **`registrant_type`** `object` — Registrant type code (see query-param doc) - **`report_calendar_year`** `object` — Calendar year of the proxy-voting report - **`report_quarter_year`** `object` — Quarter / year designator (e.g., 'Q4 2024') - **`report_type`** `object` — N-PX report type code - **`reporting_crd_number`** `object` — FINRA CRD number of the reporting entity - **`reporting_person_name`** `object` — Reporting-person name (where the filing is made on behalf of someone) - **`reporting_sec_file_number`** `object` — SEC file number of the reporting entity (e.g., '801-12345' for advisers) - **`submission_type`** `object` — EDGAR submission type - **`votes`** `array` — All vote records reported on this filing **Items:** - **`record_index` (required)** `integer` — Per-filing 0-based ordinal of this vote row - **`cusip`** `object` — 9-character CUSIP of the security being voted - **`isin`** `object` — 12-character ISIN of the security being voted - **`issuer_name`** `object` — Issuer name (the company holding the meeting) - **`meeting_date`** `object` — Date of the shareholder meeting - **`shares_on_loan`** `object` — Shares of this security on loan (and therefore not available to vote) - **`shares_voted`** `object` — Number of shares the reporting fund voted - **`vote_categories`** `object` — Structured vote-category tags assigned to this proposal - **`vote_description`** `object` — Description of the proposal being voted on - **`vote_records`** `object` — Per-fund vote records (one filing may report votes for multiple funds) - **`vote_source`** `object` — Source of the vote decision (e.g., 'M' management recommendation, 'S' shareholder, 'B' both) - **`year_or_quarter`** `object` — Period type the filing covers ('annual' or quarterly tag) **Example:** ```json { "filing_id": "", "cik": "", "form_type": "", "period_of_report": "", "accepted_time": "", "is_valid": true, "filer_name": "", "filer_tickers": [ "" ], "submission_type": "", "year_or_quarter": "", "report_calendar_year": 1, "report_quarter_year": "", "report_type": "", "confidential_treatment": true, "is_amendment": true, "amendment_no": "", "registrant_type": "", "reporting_person_name": "", "file_number": "", "amendment_type": "", "reporting_crd_number": "", "reporting_sec_file_number": "", "form_data": null, "votes": [ { "record_index": 1, "meeting_date": "", "issuer_name": "", "cusip": "", "isin": "", "vote_description": "", "shares_voted": "", "shares_on_loan": "", "vote_source": "", "vote_categories": null, "vote_records": null } ], "accession_num": "", "source_url": "" } ``` ### ProxyVoteFilingSummary - **Type:**`object` Filing-level summary for one Form N-PX submission. - **`accession_num` (required)** `object` — EDGAR accession number derived from filing\_id (e.g., '0000320193-24-000123') - **`cik` (required)** `string` — Filer SEC Central Index Key - **`filing_id` (required)** `string` — Unique filing identifier - **`form_type` (required)** `string` — SEC form type (e.g., '4', '13F-HR', 'D') - **`source_url` (required)** `object` — Canonical SEC EDGAR Archives URL pointing at the filing's index page - **`accepted_time`** `object` — When SEC accepted the filing - **`amendment_no`** `object` — Amendment number for amendment filings - **`confidential_treatment`** `object` — True if filing requested confidential treatment - **`file_number`** `object` — Investment Company Act file number - **`filer_name`** `object` — Filer entity name - **`filer_tickers`** `object` — Ticker symbols associated with the filer - **`is_amendment`** `object` — True if this filing is an amendment - **`is_valid`** `object` — Whether the filing passed validation - **`period_of_report`** `object` — Reporting period end date - **`registrant_type`** `object` — Registrant type code (see query-param doc) - **`report_calendar_year`** `object` — Calendar year of the proxy-voting report - **`report_quarter_year`** `object` — Quarter / year designator (e.g., 'Q4 2024') - **`report_type`** `object` — N-PX report type code - **`reporting_person_name`** `object` — Reporting-person name (where the filing is made on behalf of someone) - **`submission_type`** `object` — EDGAR submission type - **`year_or_quarter`** `object` — Period type the filing covers ('annual' or quarterly tag) **Example:** ```json { "filing_id": "", "cik": "", "form_type": "", "period_of_report": "", "accepted_time": "", "is_valid": true, "filer_name": "", "filer_tickers": [ "" ], "submission_type": "", "year_or_quarter": "", "report_calendar_year": 1, "report_quarter_year": "", "report_type": "", "confidential_treatment": true, "is_amendment": true, "amendment_no": "", "registrant_type": "", "reporting_person_name": "", "file_number": "", "accession_num": "", "source_url": "" } ``` ### ProxyVotesEntitiesListResponse - **Type:**`object` * **`data` (required)** `array` — Page of funds with N-PX data on file. **Items:** - **`cik` (required)** `string` — Required. Reporting fund SEC Central Index Key (canonical short form, no leading zeros). - **`filing_count` (required)** `integer` — Required. Total Form N-PX filings on file for this fund. - **`company_name`** `object` — Optional. Modal filer name across the fund's N-PX filings. - **`period_max`** `object` — Optional. Latest period\_of\_report observed for this fund. - **`period_min`** `object` — Optional. Earliest period\_of\_report observed for this fund. - **`tickers`** `object` — Optional. Filer ticker symbols sampled from one filing's \`filer\_tickers\`. * **`page_size` (required)** `integer` — Results per page * **`page`** `integer`, default: `1` — Current page number (1-indexed) * **`total`** `integer`, default: `0` — Total count of matching rows * **`total_pages`** `integer`, default: `1` — Total number of pages **Example:** ```json { "total": 0, "page": 1, "page_size": 1, "total_pages": 1, "data": [ { "cik": "", "company_name": "", "tickers": [ "" ], "filing_count": 1, "period_min": "", "period_max": "" } ] } ``` ### ProxyVotesEntitySummary - **Type:**`object` Per-registrant summary of N-PX filing availability. One row per distinct `filer_cik` (the reporting fund) with the modal `filer_name`, total filing count, and observed period-of-report range. - **`cik` (required)** `string` — Required. Reporting fund SEC Central Index Key (canonical short form, no leading zeros). - **`filing_count` (required)** `integer` — Required. Total Form N-PX filings on file for this fund. - **`company_name`** `object` — Optional. Modal filer name across the fund's N-PX filings. - **`period_max`** `object` — Optional. Latest period\_of\_report observed for this fund. - **`period_min`** `object` — Optional. Earliest period\_of\_report observed for this fund. - **`tickers`** `object` — Optional. Filer ticker symbols sampled from one filing's \`filer\_tickers\`. **Example:** ```json { "cik": "", "company_name": "", "tickers": [ "" ], "filing_count": 1, "period_min": "", "period_max": "" } ``` ### ProxyVotesListResponse - **Type:**`object` * **`data` (required)** `array` — Page of N-PX filing rows **Items:** - **`accession_num` (required)** `object` — EDGAR accession number derived from filing\_id (e.g., '0000320193-24-000123') - **`cik` (required)** `string` — Filer SEC Central Index Key - **`filing_id` (required)** `string` — Unique filing identifier - **`form_type` (required)** `string` — SEC form type (e.g., '4', '13F-HR', 'D') - **`source_url` (required)** `object` — Canonical SEC EDGAR Archives URL pointing at the filing's index page - **`accepted_time`** `object` — When SEC accepted the filing - **`amendment_no`** `object` — Amendment number for amendment filings - **`confidential_treatment`** `object` — True if filing requested confidential treatment - **`file_number`** `object` — Investment Company Act file number - **`filer_name`** `object` — Filer entity name - **`filer_tickers`** `object` — Ticker symbols associated with the filer - **`is_amendment`** `object` — True if this filing is an amendment - **`is_valid`** `object` — Whether the filing passed validation - **`period_of_report`** `object` — Reporting period end date - **`registrant_type`** `object` — Registrant type code (see query-param doc) - **`report_calendar_year`** `object` — Calendar year of the proxy-voting report - **`report_quarter_year`** `object` — Quarter / year designator (e.g., 'Q4 2024') - **`report_type`** `object` — N-PX report type code - **`reporting_person_name`** `object` — Reporting-person name (where the filing is made on behalf of someone) - **`submission_type`** `object` — EDGAR submission type - **`year_or_quarter`** `object` — Period type the filing covers ('annual' or quarterly tag) * **`page_size` (required)** `integer` — Results per page * **`page`** `integer`, default: `1` — Current page number (1-indexed) * **`total`** `integer`, default: `0` — Total count of matching rows * **`total_pages`** `integer`, default: `1` — Total number of pages **Example:** ```json { "total": 0, "page": 1, "page_size": 1, "total_pages": 1, "data": [ { "filing_id": "", "cik": "", "form_type": "", "period_of_report": "", "accepted_time": "", "is_valid": true, "filer_name": "", "filer_tickers": [ "" ], "submission_type": "", "year_or_quarter": "", "report_calendar_year": 1, "report_quarter_year": "", "report_type": "", "confidential_treatment": true, "is_amendment": true, "amendment_no": "", "registrant_type": "", "reporting_person_name": "", "file_number": "", "accession_num": "", "source_url": "" } ] } ``` ### RatioCategoriesResponse - **Type:**`object` Response for GET /ratios/categories. Carries both `categories` (legacy bespoke key) and `data` (canonical paginated-envelope key) so existing clients keep working while new ones can rely on the standard envelope. The bespoke key is a deprecation candidate for v2. - **`categories` (required)** `array` — Available ratio categories **Items:** `string` - **`data` (required)** `array` — Alias of \`categories\`, matching the canonical \`{data}\` envelope. **Items:** `string` **Example:** ```json { "categories": [ "" ], "data": [ "" ] } ``` ### RatioComparativeResponse - **Type:**`object` Response shape for /ratios/yoy and /ratios/qoq. - **`cik` (required)** `string` — Resolved issuer CIK (canonical short form). - **`comparison` (required)** `string` — 'yoy' (year-over-year) or 'qoq' (quarter-over-quarter). - **`data` (required)** `array` — Per-ratio current vs prior comparison rows. **Items:** - **`current` (required)** `object` — Current-period value. - **`ratio_name` (required)** `string` — Ratio name (e.g., 'gross\_margin\_pct'). - **`delta`** `object` — current.ratio\_value - prior.ratio\_value; null when either is missing. - **`pct_change`** `object` — delta / |prior.ratio\_value|, expressed as a fraction (e.g., 0.05 = +5%); null when prior is missing or zero. - **`prior`** `object` — Comparison-period value; null when no prior period is on file. - **`ratio_category`** `object` — Ratio category (e.g., 'profitability'). - **`fiscal_quarter` (required)** `integer` — Anchor fiscal quarter resolved. - **`fiscal_year` (required)** `integer` — Anchor fiscal year resolved. - **`company_name`** `object` — Issuer name. - **`ticker`** `object` — Issuer ticker queried, when supplied. **Example:** ```json { "cik": "", "ticker": "", "company_name": "", "comparison": "", "fiscal_year": 1, "fiscal_quarter": 1, "data": [ { "ratio_name": "", "ratio_category": "", "current": null, "prior": null, "delta": 1, "pct_change": 1 } ] } ``` ### RatioDeltaPoint - **Type:**`object` Anchored ratio value at a single fiscal period. - **`fiscal_quarter` (required)** `integer` — Fiscal quarter (0=annual, 1-4=Q1-Q4). - **`fiscal_year` (required)** `integer` — Fiscal year of the period. - **`filing_id`** `object` — Source filing\_id. - **`period_date`** `object` — Period\_date of the row. - **`ratio_value`** `object` — Ratio value at this period. **Example:** ```json { "fiscal_year": 1, "fiscal_quarter": 1, "period_date": "", "ratio_value": 1, "filing_id": "" } ``` ### RatioDeltaRow - **Type:**`object` One ratio\_name's current vs prior comparison. - **`current` (required)** `object` — Current-period value. - **`ratio_name` (required)** `string` — Ratio name (e.g., 'gross\_margin\_pct'). - **`delta`** `object` — current.ratio\_value - prior.ratio\_value; null when either is missing. - **`pct_change`** `object` — delta / |prior.ratio\_value|, expressed as a fraction (e.g., 0.05 = +5%); null when prior is missing or zero. - **`prior`** `object` — Comparison-period value; null when no prior period is on file. - **`ratio_category`** `object` — Ratio category (e.g., 'profitability'). **Example:** ```json { "ratio_name": "", "ratio_category": "", "current": { "fiscal_year": 1, "fiscal_quarter": 1, "period_date": "", "ratio_value": 1, "filing_id": "" }, "prior": { "fiscal_year": 1, "fiscal_quarter": 1, "period_date": "", "ratio_value": 1, "filing_id": "" }, "delta": 1, "pct_change": 1 } ``` ### RatioNamesResponse - **Type:**`object` Response for GET /ratios/names. Same dual-key pattern as :class:`RatioCategoriesResponse` — `ratio_names` is the legacy bespoke key, `data` is the canonical one. Slated for envelope unification in v2. - **`data` (required)** `array` — Alias of \`ratio\_names\`, matching the canonical \`{data}\` envelope. **Items:** `string` - **`ratio_names` (required)** `array` — Available ratio names **Items:** `string` - **`category`** `object` — Category filter applied (if any) **Example:** ```json { "ratio_names": [ "" ], "category": "", "data": [ "" ] } ``` ### RatioPercentileResponse - **Type:**`object` Result of /ratios/percentile. - **`cik` (required)** `string` — Resolved issuer CIK (canonical short form). - **`cohort_size` (required)** `integer` — Number of issuers in the SIC cohort with a ratio\_value at the same (fiscal\_year, fiscal\_quarter, ratio\_name). - **`fiscal_quarter` (required)** `integer` — Anchor fiscal quarter resolved. - **`fiscal_year` (required)** `integer` — Anchor fiscal year resolved. - **`peer_set` (required)** `string` — Peer-set used for the rank ('sic'). - **`ratio_name` (required)** `string` — Ratio name compared. - **`company_name`** `object` — Issuer name. - **`percentile`** `object` — Rank of this issuer in the cohort, in \[0, 1]. Higher = larger ratio value. Null when cohort\_size <= 1. - **`ratio_value`** `object` — The issuer's ratio value at the resolved period. - **`sic`** `object` — Issuer's SIC code (the partition key for the rank). - **`sic_description`** `object` — SIC description. - **`ticker`** `object` — Issuer ticker queried, when supplied. **Example:** ```json { "cik": "", "ticker": "", "company_name": "", "ratio_name": "", "ratio_value": 1, "fiscal_year": 1, "fiscal_quarter": 1, "peer_set": "", "sic": "", "sic_description": "", "cohort_size": 1, "percentile": 1 } ``` ### ReadinessResponse - **Type:**`object` Response for GET /health/ready endpoint. Returns readiness status based on database connectivity. - **`database` (required)** `string`, possible values: `"connected", "disconnected"` — Database connection status - **`service` (required)** `string` — Service name - **`status` (required)** `string`, possible values: `"ready", "not ready"` — Readiness status - **`version` (required)** `string` — Service version - **`error`** `object` — Error message if not ready **Example:** ```json { "database": "connected", "service": "Tatooine API", "status": "ready", "version": "1.0.0" } ``` ### RegAOfferingDetail - **Type:**`object` Per-filing detail — filing summary plus financial-statement summary, offering-terms detail, fees, jurisdictions, equity-class rows, and unregistered-securities rows. - **`accession_num` (required)** `object` — EDGAR accession number derived from filing\_id (e.g., '0000320193-24-000123') - **`cik` (required)** `string` — Filer SEC Central Index Key - **`filing_id` (required)** `string` — Unique filing identifier - **`form_type` (required)** `string` — SEC form type (e.g., '4', '13F-HR', 'D') - **`source_url` (required)** `object` — Canonical SEC EDGAR Archives URL pointing at the filing's index page - **`accepted_time`** `object` — When SEC accepted the filing - **`accounts_payable`** `object` — Accounts payable (USD) - **`accounts_receivable`** `object` — Accounts receivable (USD) - **`audit_status`** `object` — Audit status of the issuer's financial statements - **`auditor_fees`** `object` — Auditor fees (USD) - **`auditor_name`** `object` — Auditor name (offering-related) - **`bad_actor`** `object` — True if any 'bad-actor' disqualification disclosed - **`blue_sky_fees`** `object` — Blue-sky compliance fees (USD) - **`blue_sky_name`** `object` — Blue-sky compliance counsel name - **`cash_equivalents`** `object` — Cash and cash equivalents (USD) - **`concurrent_offering_aggregate`** `object` — Aggregate of concurrent offerings (USD) - **`cost_and_expenses_appl_to_revenues`** `object` — Cost and expenses applicable to revenues (USD) - **`deposits`** `object` — Deposits (USD) - **`depreciation_and_amortization`** `object` — Depreciation and amortization (USD) - **`earnings_per_share_basic`** `object` — Basic earnings per share (USD) - **`earnings_per_share_diluted`** `object` — Diluted earnings per share (USD) - **`equity_classes`** `array` — All equity-class rows for this filing **Items:** - **`record_index` (required)** `integer` — Per-filing 0-based ordinal of this class row - **`class_name`** `object` — Class name (e.g., 'Class A Common Stock') - **`cusip`** `object` — CUSIP of the class (where assigned) - **`equity_type`** `object` — Equity type (e.g., 'Common Equity', 'Preferred Equity') - **`outstanding`** `object` — Shares outstanding for this class - **`publicly_traded`** `object` — Public-trading designation (e.g., 'Yes' / 'No' / exchange name) - **`estimated_net_amount`** `object` — Estimated net amount to issuer after fees (USD) - **`filer_name`** `object` — Filer entity name - **`filer_tickers`** `object` — Ticker symbols associated with the filer - **`finders_fees_fees`** `object` — Finder fees (USD) - **`finders_fees_name`** `object` — Finder name - **`full_time_employees`** `object` — Issuer full-time employee count - **`investment_securities`** `object` — Investment securities (USD) - **`irs_num`** `object` — Issuer IRS Employer Identification Number (EIN) - **`is_valid`** `object` — Whether the filing passed validation - **`issuer_aggregate_offering`** `object` — Aggregate offering amount by issuer (USD) - **`issuer_auditor_name`** `object` — Name of issuer's external auditor - **`issuer_city`** `object` — Issuer city - **`issuer_contact_name`** `object` — Issuer contact person name - **`issuer_eligible`** `object` — True if issuer is eligible to use Regulation A+ - **`issuer_industry_group`** `object` — Issuer industry group classification - **`issuer_name`** `object` — Issuer legal name - **`issuer_phone_number`** `object` — Issuer contact phone number - **`issuer_state_or_country`** `object` — Issuer state code or country - **`issuer_street1`** `object` — Issuer street address line 1 - **`issuer_zip_code`** `object` — Issuer postal code - **`jurisdiction_of_organization`** `object` — Issuer state or country of organization - **`jurisdictions_dealers`** `object` — List of state / territory codes where dealers are located - **`jurisdictions_none`** `object` — True if offering is not made in any specific jurisdiction - **`jurisdictions_offered`** `object` — List of state / territory codes where the offering is made - **`jurisdictions_same_as_offering`** `object` — True if dealer jurisdictions are the same as offering jurisdictions - **`legal_fees`** `object` — Legal fees (USD) - **`legal_name`** `object` — Legal counsel name - **`loans_net`** `object` — Loans, net of allowance (USD) - **`long_term_debt`** `object` — Long-term debt (USD) - **`net_income`** `object` — Issuer net income for the reporting period (USD) - **`not_disqualified`** `object` — True if issuer is not disqualified under Rule 262 - **`offer_delayed_continuous`** `object` — True if offering is on a delayed or continuous basis - **`offering_after_qualification`** `object` — True if offering will commence after qualification - **`offering_best_efforts`** `object` — True if offering is on a best-efforts basis - **`offering_file_number`** `object` — Reg A+ offering file number (e.g., '024-12345') - **`offering_year`** `object` — True if offering will be made within one year - **`outstanding_securities`** `object` — Outstanding securities of this class - **`part_time_employees`** `object` — Issuer part-time employee count - **`period_of_report`** `object` — Reporting period end date - **`policy_liabilities_and_accruals`** `object` — Insurance policy liabilities and accruals (USD) - **`price_per_security`** `object` — Price per security (USD) - **`promoters_fees`** `object` — Promoter fees (USD) - **`promoters_name`** `object` — Promoter name - **`property_and_equipment`** `object` — Property and equipment (alternate label, USD) - **`property_plant_equipment`** `object` — Property, plant, and equipment (USD) - **`qualification_offering_aggregate`** `object` — Aggregate offering amount qualified to date (USD) - **`resale_affiliates`** `object` — True if offering includes resales by affiliates of the issuer - **`sales_commissions_fees`** `object` — Sales-commission fees (USD) - **`sales_commissions_name`** `object` — Name of party receiving sales commissions - **`securities_offered`** `object` — Number of securities offered - **`securities_offered_types`** `object` — List of security types offered (e.g., \['Equity', 'Debt', 'Other']) - **`security_holder_aggregate`** `object` — Aggregate offering amount by selling security holders (USD) - **`sic_code`** `object` — Issuer Standard Industrial Classification code - **`solicitation`** `object` — True if testing-the-waters / general solicitation occurred - **`submission_type`** `object` — EDGAR submission type - **`tier`** `object` — Reg A+ tier ('Tier 1' or 'Tier 2'); see query-param doc - **`total_aggregate_offering`** `object` — Total aggregate offering amount (USD) - **`total_assets`** `object` — Issuer total assets at period end (USD) - **`total_interest_expenses`** `object` — Total interest expense (USD) - **`total_interest_income`** `object` — Total interest income (USD) - **`total_investments`** `object` — Total investments (USD) - **`total_liabilities`** `object` — Total liabilities (USD) - **`total_liabilities_and_equity`** `object` — Total liabilities and stockholders' equity (USD) - **`total_revenues`** `object` — Issuer total revenues for the reporting period (USD) - **`total_stockholder_equity`** `object` — Total stockholders' equity (USD) - **`underwriters_fees`** `object` — Underwriter fees (USD) - **`underwriters_name`** `object` — Underwriter name (where applicable) - **`unregistered_act_exemption`** `object` — Securities Act exemption claimed for unregistered sales (e.g., 'Section 4(a)(2)', 'Rule 506') - **`unregistered_none`** `object` — True if no unregistered securities sold in the past year - **`unregistered_securities`** `array` — All unregistered-security rows for this filing (Item 6 disclosures) **Items:** - **`record_index` (required)** `integer` — Per-filing 0-based ordinal of this row - **`aggregate_amount`** `object` — Aggregate amount as reported (free-text; may include narrative) - **`issuer_name`** `object` — Name of the issuer of the unregistered securities - **`principal_holder_amount`** `object` — Amount sold to principal holders - **`title`** `object` — Security title (e.g., 'Series A Preferred Stock') - **`total_amount`** `object` — Total amount of unregistered securities sold - **`year_of_incorporation`** `object` — Year the issuer was incorporated / organized **Example:** ```json { "filing_id": "", "cik": "", "form_type": "", "period_of_report": "", "accepted_time": "", "is_valid": true, "filer_name": "", "filer_tickers": [ "" ], "submission_type": "", "offering_file_number": "", "issuer_name": "", "jurisdiction_of_organization": "", "year_of_incorporation": 1, "sic_code": "", "issuer_industry_group": "", "tier": "", "audit_status": "", "total_aggregate_offering": "", "estimated_net_amount": "", "total_assets": "", "total_revenues": "", "net_income": "", "irs_num": "", "full_time_employees": 1, "part_time_employees": 1, "issuer_street1": "", "issuer_city": "", "issuer_state_or_country": "", "issuer_zip_code": "", "issuer_phone_number": "", "issuer_contact_name": "", "issuer_auditor_name": "", "cash_equivalents": "", "investment_securities": "", "total_investments": "", "accounts_receivable": "", "loans_net": "", "property_plant_equipment": "", "property_and_equipment": "", "accounts_payable": "", "policy_liabilities_and_accruals": "", "deposits": "", "long_term_debt": "", "total_liabilities": "", "total_stockholder_equity": "", "total_liabilities_and_equity": "", "total_interest_income": "", "total_interest_expenses": "", "cost_and_expenses_appl_to_revenues": "", "depreciation_and_amortization": "", "earnings_per_share_basic": "", "earnings_per_share_diluted": "", "issuer_eligible": true, "not_disqualified": true, "bad_actor": true, "securities_offered_types": null, "offer_delayed_continuous": true, "offering_year": true, "offering_after_qualification": true, "offering_best_efforts": true, "solicitation": true, "resale_affiliates": true, "securities_offered": "", "outstanding_securities": "", "price_per_security": "", "issuer_aggregate_offering": "", "security_holder_aggregate": "", "qualification_offering_aggregate": "", "concurrent_offering_aggregate": "", "sales_commissions_name": "", "sales_commissions_fees": "", "auditor_name": "", "auditor_fees": "", "legal_name": "", "legal_fees": "", "blue_sky_name": "", "blue_sky_fees": "", "underwriters_name": "", "underwriters_fees": "", "promoters_name": "", "promoters_fees": "", "finders_fees_name": "", "finders_fees_fees": "", "jurisdictions_none": true, "jurisdictions_same_as_offering": true, "jurisdictions_offered": null, "jurisdictions_dealers": null, "unregistered_none": true, "unregistered_act_exemption": "", "equity_classes": [ { "record_index": 1, "equity_type": "", "class_name": "", "outstanding": "", "cusip": "", "publicly_traded": "" } ], "unregistered_securities": [ { "record_index": 1, "issuer_name": "", "title": "", "total_amount": "", "principal_holder_amount": "", "aggregate_amount": "" } ], "accession_num": "", "source_url": "" } ``` ### RegAOfferingSummary - **Type:**`object` Filing-level summary for one Form 1-A / 1-K / 1-U / 1-Z submission. - **`accession_num` (required)** `object` — EDGAR accession number derived from filing\_id (e.g., '0000320193-24-000123') - **`cik` (required)** `string` — Filer SEC Central Index Key - **`filing_id` (required)** `string` — Unique filing identifier - **`form_type` (required)** `string` — SEC form type (e.g., '4', '13F-HR', 'D') - **`source_url` (required)** `object` — Canonical SEC EDGAR Archives URL pointing at the filing's index page - **`accepted_time`** `object` — When SEC accepted the filing - **`audit_status`** `object` — Audit status of the issuer's financial statements - **`estimated_net_amount`** `object` — Estimated net amount to issuer after fees (USD) - **`filer_name`** `object` — Filer entity name - **`filer_tickers`** `object` — Ticker symbols associated with the filer - **`is_valid`** `object` — Whether the filing passed validation - **`issuer_industry_group`** `object` — Issuer industry group classification - **`issuer_name`** `object` — Issuer legal name - **`jurisdiction_of_organization`** `object` — Issuer state or country of organization - **`net_income`** `object` — Issuer net income for the reporting period (USD) - **`offering_file_number`** `object` — Reg A+ offering file number (e.g., '024-12345') - **`period_of_report`** `object` — Reporting period end date - **`sic_code`** `object` — Issuer Standard Industrial Classification code - **`submission_type`** `object` — EDGAR submission type - **`tier`** `object` — Reg A+ tier ('Tier 1' or 'Tier 2'); see query-param doc - **`total_aggregate_offering`** `object` — Total aggregate offering amount (USD) - **`total_assets`** `object` — Issuer total assets at period end (USD) - **`total_revenues`** `object` — Issuer total revenues for the reporting period (USD) - **`year_of_incorporation`** `object` — Year the issuer was incorporated / organized **Example:** ```json { "filing_id": "", "cik": "", "form_type": "", "period_of_report": "", "accepted_time": "", "is_valid": true, "filer_name": "", "filer_tickers": [ "" ], "submission_type": "", "offering_file_number": "", "issuer_name": "", "jurisdiction_of_organization": "", "year_of_incorporation": 1, "sic_code": "", "issuer_industry_group": "", "tier": "", "audit_status": "", "total_aggregate_offering": "", "estimated_net_amount": "", "total_assets": "", "total_revenues": "", "net_income": "", "accession_num": "", "source_url": "" } ``` ### RegAOfferingsEntitiesListResponse - **Type:**`object` * **`data` (required)** `array` — Page of issuers with Form 1-A data on file. **Items:** - **`cik` (required)** `string` — Required. Issuer SEC Central Index Key (canonical short form, no leading zeros). - **`filing_count` (required)** `integer` — Required. Total Form 1-A filings on file for this issuer. - **`company_name`** `object` — Optional. Modal issuer name across the issuer's Form 1-A filings. - **`period_max`** `object` — Optional. Latest period\_of\_report observed for this issuer. - **`period_min`** `object` — Optional. Earliest period\_of\_report observed for this issuer. - **`tickers`** `object` — Optional. Issuer ticker symbols sampled from one filing's \`filer\_tickers\`. * **`page_size` (required)** `integer` — Results per page * **`page`** `integer`, default: `1` — Current page number (1-indexed) * **`total`** `integer`, default: `0` — Total count of matching rows * **`total_pages`** `integer`, default: `1` — Total number of pages **Example:** ```json { "total": 0, "page": 1, "page_size": 1, "total_pages": 1, "data": [ { "cik": "", "company_name": "", "tickers": [ "" ], "filing_count": 1, "period_min": "", "period_max": "" } ] } ``` ### RegAOfferingsEntitySummary - **Type:**`object` Per-issuer summary of Form 1-A filing availability. One row per distinct `cik` (Form 1-A is filed by the issuer itself, so filer\_cik == issuer\_cik) with modal `filer_name`, total filing count, and observed period-of-report range. - **`cik` (required)** `string` — Required. Issuer SEC Central Index Key (canonical short form, no leading zeros). - **`filing_count` (required)** `integer` — Required. Total Form 1-A filings on file for this issuer. - **`company_name`** `object` — Optional. Modal issuer name across the issuer's Form 1-A filings. - **`period_max`** `object` — Optional. Latest period\_of\_report observed for this issuer. - **`period_min`** `object` — Optional. Earliest period\_of\_report observed for this issuer. - **`tickers`** `object` — Optional. Issuer ticker symbols sampled from one filing's \`filer\_tickers\`. **Example:** ```json { "cik": "", "company_name": "", "tickers": [ "" ], "filing_count": 1, "period_min": "", "period_max": "" } ``` ### RegAOfferingsListResponse - **Type:**`object` * **`data` (required)** `array` — Page of Reg A+ filing rows **Items:** - **`accession_num` (required)** `object` — EDGAR accession number derived from filing\_id (e.g., '0000320193-24-000123') - **`cik` (required)** `string` — Filer SEC Central Index Key - **`filing_id` (required)** `string` — Unique filing identifier - **`form_type` (required)** `string` — SEC form type (e.g., '4', '13F-HR', 'D') - **`source_url` (required)** `object` — Canonical SEC EDGAR Archives URL pointing at the filing's index page - **`accepted_time`** `object` — When SEC accepted the filing - **`audit_status`** `object` — Audit status of the issuer's financial statements - **`estimated_net_amount`** `object` — Estimated net amount to issuer after fees (USD) - **`filer_name`** `object` — Filer entity name - **`filer_tickers`** `object` — Ticker symbols associated with the filer - **`is_valid`** `object` — Whether the filing passed validation - **`issuer_industry_group`** `object` — Issuer industry group classification - **`issuer_name`** `object` — Issuer legal name - **`jurisdiction_of_organization`** `object` — Issuer state or country of organization - **`net_income`** `object` — Issuer net income for the reporting period (USD) - **`offering_file_number`** `object` — Reg A+ offering file number (e.g., '024-12345') - **`period_of_report`** `object` — Reporting period end date - **`sic_code`** `object` — Issuer Standard Industrial Classification code - **`submission_type`** `object` — EDGAR submission type - **`tier`** `object` — Reg A+ tier ('Tier 1' or 'Tier 2'); see query-param doc - **`total_aggregate_offering`** `object` — Total aggregate offering amount (USD) - **`total_assets`** `object` — Issuer total assets at period end (USD) - **`total_revenues`** `object` — Issuer total revenues for the reporting period (USD) - **`year_of_incorporation`** `object` — Year the issuer was incorporated / organized * **`page_size` (required)** `integer` — Results per page * **`page`** `integer`, default: `1` — Current page number (1-indexed) * **`total`** `integer`, default: `0` — Total count of matching rows * **`total_pages`** `integer`, default: `1` — Total number of pages **Example:** ```json { "total": 0, "page": 1, "page_size": 1, "total_pages": 1, "data": [ { "filing_id": "", "cik": "", "form_type": "", "period_of_report": "", "accepted_time": "", "is_valid": true, "filer_name": "", "filer_tickers": [ "" ], "submission_type": "", "offering_file_number": "", "issuer_name": "", "jurisdiction_of_organization": "", "year_of_incorporation": 1, "sic_code": "", "issuer_industry_group": "", "tier": "", "audit_status": "", "total_aggregate_offering": "", "estimated_net_amount": "", "total_assets": "", "total_revenues": "", "net_income": "", "accession_num": "", "source_url": "" } ] } ``` ### ReportingOwnerResponse - **Type:**`object` One reporting-owner row — the insider whose holdings or transactions are being reported. A single Form 4 may list multiple reporting owners (e.g., joint ownership). - **`record_index` (required)** `integer` — Per-filing 0-based ordinal of this owner row - **`is_director`** `object` — True if reporting owner is a director of the issuer - **`is_officer`** `object` — True if reporting owner is an officer of the issuer - **`is_other`** `object` — True if reporting owner falls into none of the above categories — see \`other\_text\` - **`is_ten_percent_owner`** `object` — True if reporting owner holds 10%+ of the issuer's stock - **`officer_title`** `object` — Officer title (e.g., 'Chief Executive Officer'); blank if not an officer - **`other_text`** `object` — Free-text description when \`is\_other\` is True - **`rpt_owner_cik`** `object` — Reporting owner (insider) SEC CIK - **`rpt_owner_name`** `object` — Reporting owner (insider) legal name **Example:** ```json { "record_index": 1, "rpt_owner_cik": "", "rpt_owner_name": "", "officer_title": "", "is_director": true, "is_officer": true, "is_ten_percent_owner": true, "is_other": true, "other_text": "" } ``` ### Sc13ExhibitResponse - **Type:**`object` One exhibit attached to the Schedule 13D/G filing. - **`record_index` (required)** `integer` — Per-filing 0-based ordinal of this exhibit - **`letter`** `object` — Exhibit letter or designator (e.g., 'A', 'B', '99') - **`schedule_type`** `object` — Schedule variant the exhibit belongs to - **`title`** `object` — Exhibit title or description **Example:** ```json { "record_index": 1, "schedule_type": "", "letter": "", "title": "" } ``` ### Sc13ReportingPersonResponse - **Type:**`object` One reporting-person row from a Schedule 13D/G — the cover-page breakdown of voting and dispositive power for an individual or entity claiming beneficial ownership. - **`record_index` (required)** `integer` — Per-filing 0-based ordinal of this person row - **`aggregate_amount`** `object` — Item 11: aggregate beneficial ownership reported by this person - **`citizenship`** `object` — Citizenship or place of organization (Item 6 of the cover page) - **`cusip`** `object` — CUSIP repeated on the reporting-person cover page - **`excludes_certain_shares`** `object` — Item 12: row 11 excludes certain shares - **`group_member_a`** `object` — Item 2(a): person is part of a Section 13(d) group - **`group_member_b`** `object` — Item 2(b): person is excluded from the group - **`legal_proceedings_required`** `object` — Item 5: legal-proceedings disclosure required for this person - **`names`** `object` — Reporting person name (Item 1 of the cover page) - **`percent_of_class`** `object` — Item 13: percent of class represented by row 11 (whole number, e.g. 5.2) - **`reporting_person_type`** `object` — Cover-page Item 2 type code (e.g., IN individual, OO other, BD broker-dealer) - **`sec_use_only`** `object` — Item 3: SEC use only — typically blank in filings - **`shared_dispositive_power`** `object` — Item 10: shares with shared dispositive power - **`shared_voting_power`** `object` — Item 8: shares with shared voting power - **`sole_dispositive_power`** `object` — Item 9: shares with sole dispositive power - **`sole_voting_power`** `object` — Item 7: shares with sole voting power - **`source_of_funds`** `object` — Item 4 source-of-funds codes (e.g., 'WC' working capital, 'PF' personal funds, 'AF' affiliate funds) **Example:** ```json { "record_index": 1, "cusip": "", "names": "", "citizenship": "", "reporting_person_type": "", "group_member_a": true, "group_member_b": true, "sec_use_only": "", "source_of_funds": "", "legal_proceedings_required": true, "sole_voting_power": "", "shared_voting_power": "", "sole_dispositive_power": "", "shared_dispositive_power": "", "aggregate_amount": "", "excludes_certain_shares": true, "percent_of_class": "" } ``` ### ScheduleType - **Type:**`string` Schedule 13 variants. SC 13D is the activist form (used when the holder intends to influence control); SC 13G is the passive form (used by qualified institutional investors with no such intent). The `/A` suffix indicates an amendment to a prior filing. **Example:** ### SecurityResolveResponse - **Type:**`object` Canonical mapping for one security across the four identifier spaces we expose. Fields are best-effort — populated when the underlying views carry the cross-reference. Coverage today: - cik ↔ company\_name ↔ tickers — rock solid via `vw_api_statements` - cusip → name — modal name across 13F / N-PORT holdings - cusip → cik / ticker — best-effort name match (falls back to `null` if no clean match) - isin → cusip / name — N-PORT only; sparse coverage - lei — N-PORT-only The `sources` field lists the views that contributed to the response so callers can audit provenance. - **`identifier` (required)** `string` — The identifier the caller passed in, normalized. - **`identifier_type` (required)** `string`, possible values: `"cusip", "isin", "ticker", "cik"` — Detected type of the input identifier. CIKs are stripped of leading zeros; tickers are uppercased; CUSIP/ISIN are passed through unchanged. - **`cik`** `object` — Issuer SEC CIK (canonical short form, no leading zeros). - **`company_name`** `object` — Issuer company name. Sourced from \`vw\_api\_statements\` when we have the CIK; otherwise the modal name across 13F / N-PORT holdings. - **`cusip`** `object` — 9-character CUSIP, or 8 if reported short. - **`entity_type`** `object` — Entity type from the registry: \`operating\`, \`investment\`, or \`other\`. - **`exchanges`** `object` — Exchanges the entity trades on (e.g., \`NYSE\`, \`Nasdaq\`). - **`filer_status_flags`** `object` — Filer status flags from the registry (e.g., \`Large Accelerated\`, \`Well Known Seasoned Issuer\`). - **`is_human`** `object` — Tri-state classification from the entity registry: \`true\` = confirmed human, \`false\` = confirmed company, \`null\` = either not in the registry or not yet classified. - **`isin`** `object` — 12-character ISIN (sparse coverage). - **`lei`** `object` — 20-character Legal Entity Identifier (N-PORT-sourced). - **`sic`** `object` — 4-digit Standard Industrial Classification code. - **`sic_description`** `object` — Plain-text SIC name. - **`sources`** `array` — Underlying views that contributed to the response. Useful for debugging coverage gaps. **Items:** `string` - **`state_of_incorp`** `object` — 2-letter state code or country code of incorporation. - **`tickers`** `object` — All ticker symbols associated with the issuer. **Example:** ```json { "cik": "320193", "company_name": "Apple Inc.", "cusip": "037833100", "identifier": "AAPL", "identifier_type": "ticker", "lei": "HWUPKR0MPOU8FGXBT394", "sources": [ "vw_api_statements", "vw_api_data_nport_holdings" ], "tickers": [ "AAPL" ] } ``` ### SmartMoneyAlignmentResponse - **Type:**`object` Smart-money alignment for one security at one period — combines insider trading flow (Form 4) with institutional positioning (13F) into a single alignment score and classification. - **`alignment_classification` (required)** `object` — Categorical alignment label (see AlignmentClassification enum) - **`alignment_score` (required)** `number` — Composite alignment score in \[-1, 1]. Magnitude reflects signal strength; sign reflects direction (positive = bullish alignment, negative = bearish, magnitude near 0 = neutral or divergent) - **`confidence` (required)** `number` — Bridge confidence between 13F (cusip-keyed) and Form 4 (CIK-keyed): 1.0 = exact name match with single CIK; 0.8 = name match with multiple CIK candidates (most-active chosen); 0.0 = no Form 4 match (insider features zeroed) - **`cusip` (required)** `string` — CUSIP of the analyzed security - **`distinct_insiders` (required)** `integer` — Distinct insiders transacting during the window - **`insider_acquired_dollars` (required)** `string` — Total insider acquisitions during the trailing window (USD) - **`insider_disposed_dollars` (required)** `string` — Total insider dispositions during the trailing window (USD) - **`insider_dollar_imbalance` (required)** `number` — (acquired − disposed) / total. Range \[-1, 1]; positive = net buying - **`insider_window_days` (required)** `integer` — Trailing window for Form 4 aggregation - **`institution_aggregate_value` (required)** `string` — Aggregate 13F-reported holding value (in thousands of USD per Form 13F convention) - **`institution_direction` (required)** `string` — Institutional positioning direction based on QoQ holder delta: 'accumulating', 'distributing', or 'neutral' - **`institution_n_holders` (required)** `integer` — Distinct 13F holders of this security at \`period\` - **`period` (required)** `string`, format: `date` — Reference date for the analysis - **`institution_qoq_holders_delta`** `object` — Change in distinct 13F holder count vs. the prior quarter (positive = accumulating) - **`matched_issuer_cik`** `object` — Form 4 issuer CIK matched to the 13F-listed \`name\_of\_issuer\` - **`name_of_issuer`** `object` — Issuer name resolved from 13F holdings **Example:** ```json { "alignment_classification": "divergent_insider_selling", "alignment_score": -0.35, "confidence": 1, "cusip": "037833100", "distinct_insiders": 4, "insider_acquired_dollars": "0", "insider_disposed_dollars": "12450000", "insider_dollar_imbalance": -1, "insider_window_days": 90, "institution_aggregate_value": "548320500", "institution_direction": "accumulating", "institution_n_holders": 4218, "institution_qoq_holders_delta": 47, "matched_issuer_cik": "0000320193", "name_of_issuer": "APPLE INC", "period": "2024-03-31" } ``` ### StaleIssuerRow - **Type:**`object` One row in the `/coverage/stale-issuers` list. - **`cik` (required)** `string` — Issuer CIK (canonical short form). - **`company_name`** `object` — Issuer name from the registry. - **`days_since_last_filing`** `object` — Whole days between today (UTC) and \`last\_accepted\_time\`. Null when no filings are on file. - **`families_on_file`** `array` — Families this issuer has at least one filing in. **Items:** `string`, possible values: `"insiders", "institutional_holdings", "private_offerings", "fund_portfolios", "beneficial_ownership", "proposed_sales", "fund_census", "money_market_funds", "proxy_votes", "reg_a_offerings", "narratives"` — Filing families surfaced by /api/v1/{family} resources. The eleven values below correspond 1:1 with the per-family routers registered in \`app/api/v1/router.py\`. Coverage / intake / data-as-of aggregate across exactly this set, so adding a new family means registering its view in \`app/services/api\_coverage\_service.py:FAMILY\_VIEWS\` and extending this enum in lockstep. - **`last_accepted_time`** `object` — Most recent accepted\_time across all families on file. **Example:** ```json { "cik": "", "company_name": "", "last_accepted_time": "", "days_since_last_filing": 1, "families_on_file": [ "insiders" ] } ``` ### StaleIssuersResponse - **Type:**`object` * **`data` (required)** `array` — Issuers ranked by \`last\_accepted\_time\` ascending (most stale first). **Items:** - **`cik` (required)** `string` — Issuer CIK (canonical short form). - **`company_name`** `object` — Issuer name from the registry. - **`days_since_last_filing`** `object` — Whole days between today (UTC) and \`last\_accepted\_time\`. Null when no filings are on file. - **`families_on_file`** `array` — Families this issuer has at least one filing in. **Items:** `string`, possible values: `"insiders", "institutional_holdings", "private_offerings", "fund_portfolios", "beneficial_ownership", "proposed_sales", "fund_census", "money_market_funds", "proxy_votes", "reg_a_offerings", "narratives"` — Filing families surfaced by /api/v1/{family} resources. The eleven values below correspond 1:1 with the per-family routers registered in \`app/api/v1/router.py\`. Coverage / intake / data-as-of aggregate across exactly this set, so adding a new family means registering its view in \`app/services/api\_coverage\_service.py:FAMILY\_VIEWS\` and extending this enum in lockstep. - **`last_accepted_time`** `object` — Most recent accepted\_time across all families on file. * **`page_size` (required)** `integer` — Results per page * **`page`** `integer`, default: `1` — Current page number (1-indexed) * **`total`** `integer`, default: `0` — Total count of matching rows * **`total_pages`** `integer`, default: `1` — Total number of pages **Example:** ```json { "total": 0, "page": 1, "page_size": 1, "total_pages": 1, "data": [ { "cik": "", "company_name": "", "last_accepted_time": "", "days_since_last_filing": 1, "families_on_file": [] } ] } ``` ### StanceClassification - **Type:**`string` Manager-stance classification per 13F position. - `passive` — manager has filed a 13G on this issuer (qualified institutional holder) - `active` — manager has filed a 13D on this issuer (intent to influence control) - `transitioned` — both schedule types appear in the manager's history on this issuer - `unclassified` — no SC13 filings by this manager on this issuer (didn't cross 5% threshold) **Example:** ### StatementType - **Type:**`string` Financial statement types. **Example:** ### TradeClassificationBreakdown - **Type:**`object` Dollar-and-percent breakdown of insider dispositions across the four classification buckets. - **`discretionary_dollars` (required)** `string` — USD value of open-market 'S' sales without Rule 10b5-1 plan affiliation (signal-bearing bucket) - **`discretionary_pct` (required)** `number` — Discretionary share of total dollars (0-1) - **`other_dollars` (required)** `string` — USD value of remaining transactions (gifts, awards, other) - **`other_pct` (required)** `number` — Other share of total dollars (0-1) - **`plan_dollars` (required)** `string` — USD value of trades flagged with aff10b5\_one (Rule 10b5-1 plan) - **`plan_pct` (required)** `number` — Plan share of total dollars (0-1) - **`tax_dollars` (required)** `string` — USD value of tax-withholding ('F') and exercise-related ('M') transactions - **`tax_pct` (required)** `number` — Tax share of total dollars (0-1) **Example:** ```json { "discretionary_dollars": "", "discretionary_pct": 1, "plan_dollars": "", "plan_pct": 1, "tax_dollars": "", "tax_pct": 1, "other_dollars": "", "other_pct": 1 } ``` ### TransactionKind - **Type:**`string` Type of insider transaction. `nonderiv` covers direct stock holdings and trades; `deriv` covers options, warrants, RSUs, and other derivative securities; `all` returns both. **Example:** ### ErrorResponse - **Type:**`object` Standardized error response structure. Error codes follow UPPERCASE\_SNAKE\_CASE format and are defined in app/core/exceptions.py. Common codes include: - INVALID\_PARAMETER, MISSING\_PARAMETER (400) - SIGNATURE\_VALIDATION\_FAILED, INVALID\_API\_KEY (401) - RESOURCE\_NOT\_FOUND (404) - CONSUMER\_ALREADY\_EXISTS (409) - QUERY\_ERROR, DATABASE\_ERROR (503) - APISIX\_ERROR (502) - UNEXPECTED\_ERROR (500) * **`code` (required)** `string` — Machine-readable error code (UPPERCASE\_SNAKE\_CASE) * **`message` (required)** `string` — Human-readable error message * **`details`** `object`, default: `null` — Additional error context * **`timestamp`** `string`, format: `date-time` — When the error occurred **Example:** ```json { "code": "INVALID_PARAMETER", "details": { "expected": "AAPL", "provided": "aapl" }, "message": "Invalid value for parameter 'ticker': must be uppercase", "timestamp": "2024-10-06T12:00:00Z" } ```