{"openapi":"3.1.0","info":{"title":"Metric Duck","description":"SEC filing data API: equity fundamentals updated daily from SEC EDGAR","version":"2.0.0"},"paths":{"/health":{"get":{"tags":["health"],"summary":"Health Check","description":"Basic health check endpoint (supports GET and HEAD)","operationId":"health_check_health_head","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HealthResponse"}}}}}},"head":{"tags":["health"],"summary":"Health Check","description":"Basic health check endpoint (supports GET and HEAD)","operationId":"health_check_health_head","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HealthResponse"}}}}}}},"/health/live":{"get":{"tags":["health"],"summary":"Liveness Probe","description":"True liveness probe endpoint (supports GET and HEAD).\n\nAlways returns 200 if the process is alive. This is the correct semantics\nfor a liveness probe - it should only fail if the process is deadlocked\nor otherwise unresponsive, not during initialization.\n\nUse /health/startup for startup probe (waits for init to complete).","operationId":"liveness_probe_health_live_head","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HealthResponse"}}}}}},"head":{"tags":["health"],"summary":"Liveness Probe","description":"True liveness probe endpoint (supports GET and HEAD).\n\nAlways returns 200 if the process is alive. This is the correct semantics\nfor a liveness probe - it should only fail if the process is deadlocked\nor otherwise unresponsive, not during initialization.\n\nUse /health/startup for startup probe (waits for init to complete).","operationId":"liveness_probe_health_live_head","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HealthResponse"}}}}}}},"/health/startup":{"get":{"tags":["health"],"summary":"Startup Probe","description":"Startup probe endpoint - returns 200 when lifespan completed, 503 otherwise.\n\nThis endpoint is used by Cloud Run's startupProbe to determine when the\ncontainer is ready to receive traffic. It waits until the app has completed\ninitialization before returning 200.","operationId":"startup_probe_health_startup_head","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}},"head":{"tags":["health"],"summary":"Startup Probe","description":"Startup probe endpoint - returns 200 when lifespan completed, 503 otherwise.\n\nThis endpoint is used by Cloud Run's startupProbe to determine when the\ncontainer is ready to receive traffic. It waits until the app has completed\ninitialization before returning 200.","operationId":"startup_probe_health_startup_head","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/health/ready":{"get":{"tags":["health"],"summary":"Readiness Probe","description":"Kubernetes readiness probe endpoint (supports GET and HEAD)\nChecks if the application is ready to serve traffic.\n\nUses caching to avoid expensive BigQuery/Supabase calls on every request.\nCache TTL is 30 seconds - this reduces costs and improves response time.","operationId":"readiness_probe_health_ready_head","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DetailedHealthResponse"}}}}}},"head":{"tags":["health"],"summary":"Readiness Probe","description":"Kubernetes readiness probe endpoint (supports GET and HEAD)\nChecks if the application is ready to serve traffic.\n\nUses caching to avoid expensive BigQuery/Supabase calls on every request.\nCache TTL is 30 seconds - this reduces costs and improves response time.","operationId":"readiness_probe_health_ready_head","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DetailedHealthResponse"}}}}}}},"/health/stripe-config":{"get":{"tags":["health"],"summary":"Stripe Config Health","description":"Stripe configuration health check - validates Stripe mode matches environment.\n\nThis endpoint validates that:\n1. API key mode (TEST vs LIVE) matches the environment\n2. Price IDs are configured for the correct mode\n3. No configuration drift has occurred\n\nUsed by post-deployment smoke tests and monitoring to detect\nmisconfigurations before they impact customers.\n\nReturns:\n    Dict with status, mode info, and validation results","operationId":"stripe_config_health_health_stripe_config_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","title":"Response Stripe Config Health Health Stripe Config Get"}}}}}}},"/warmup/warmup":{"get":{"tags":["warmup"],"summary":"Warmup Service","description":"Warmup endpoint called by Cloud Scheduler.\nPre-warms popular company data and ensures service is responsive.\n\nFree tier usage:\n- Cloud Scheduler: 3 jobs free (this uses 1)\n- Called every 15 minutes during business hours (9 AM - 6 PM EST)","operationId":"warmup_service_warmup_warmup_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WarmupResponse"}}}}}}},"/warmup/warmup/cache-stats":{"get":{"tags":["warmup"],"summary":"Get Cache Stats","description":"Get current cache statistics for monitoring (internal: Cloud Scheduler SA only).","operationId":"get_cache_stats_warmup_warmup_cache_stats_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CacheStatsResponse"}}}}}}},"/warmup/warmup/manual":{"post":{"tags":["warmup"],"summary":"Manual Warmup","description":"Manual warmup endpoint for specific tickers.\nUseful for pre-warming before expected traffic spikes.\n\nInternal: requires a Cloud Scheduler service-account OIDC token (drives\nBigQuery cost via peers warmup; not a public endpoint).","operationId":"manual_warmup_warmup_warmup_manual_post","requestBody":{"content":{"application/json":{"schema":{"items":{"type":"string"},"type":"array","title":"Tickers"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/warmup/warmup/health":{"get":{"tags":["warmup"],"summary":"Warmup Health","description":"Simple health check for the warmup service","operationId":"warmup_health_warmup_warmup_health_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/auth/health":{"get":{"tags":["authentication"],"summary":"Auth Health","description":"Auth service health check","operationId":"auth_health_auth_health_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/auth/v2/login":{"post":{"tags":["auth-cookies"],"summary":"Login","description":"Login endpoint using Supabase Auth with HTTP-only cookies.\nSets both access and refresh tokens for secure session management.","operationId":"login_auth_v2_login_post","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/auth/v2/register":{"post":{"tags":["auth-cookies"],"summary":"Register","description":"Register a new user with Supabase Auth.\nSets HTTP-only cookies if email confirmation is disabled.","operationId":"register_auth_v2_register_post","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/auth/v2/logout":{"post":{"tags":["auth-cookies"],"summary":"Logout","description":"Logout endpoint that revokes session, invalidates cache, and clears cookies.","operationId":"logout_auth_v2_logout_post","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/auth/v2/session":{"get":{"tags":["auth-cookies"],"summary":"Get Session","description":"Get current session information using Supabase tokens.\nReturns user data if authenticated, or guest info if not.\n\nIf the access token is expired/missing but a valid refresh token exists,\nautomatically refreshes the session (fixes \"Remember Me\" persistence).","operationId":"get_session_auth_v2_session_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/auth/v2/refresh":{"post":{"tags":["auth-cookies"],"summary":"Refresh Session","description":"Refresh session using Supabase refresh token with proper token rotation.\nInvalidates old tokens before setting new ones to prevent race conditions.","operationId":"refresh_session_auth_v2_refresh_post","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/auth/v2/confirm":{"get":{"tags":["auth-cookies"],"summary":"Confirm Email","description":"Handle email confirmation callback from Supabase.\nExchanges confirmation token for session tokens and sets cookies.","operationId":"confirm_email_auth_v2_confirm_get","parameters":[{"name":"token_hash","in":"query","required":true,"schema":{"type":"string","title":"Token Hash"}},{"name":"type","in":"query","required":true,"schema":{"type":"string","title":"Type"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/auth/v2/oauth/callback":{"post":{"tags":["auth-cookies"],"summary":"Oauth Callback","description":"Handle OAuth callback - exchanges Supabase OAuth session for API cookies.\nMaintains API as single source of truth for authentication.\n\nFlow:\n1. Frontend completes OAuth with Supabase (GitHub/Google)\n2. Callback sends tokens to this endpoint\n3. API validates tokens and sets session cookies\n4. User is authenticated with API session","operationId":"oauth_callback_auth_v2_oauth_callback_post","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/auth/v2/resend-verification":{"post":{"tags":["auth-cookies"],"summary":"Resend Verification","description":"Resend email verification link.\nRate limited by Supabase (1 per minute per email).","operationId":"resend_verification_auth_v2_resend_verification_post","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/auth/v2/reset-password":{"post":{"tags":["auth-cookies"],"summary":"Reset Password","description":"Request password reset email.\n\nSECURITY: Always returns generic success message to prevent email enumeration.\nThis follows OWASP best practices for password reset flows.\n\nRate limited by our own middleware + Supabase (1 per 60 seconds per email).","operationId":"reset_password_auth_v2_reset_password_post","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/auth/v2/update-password":{"post":{"tags":["auth-cookies"],"summary":"Update Password","description":"Update password for authenticated user (after recovery flow).\nRequires valid session cookie from recovery verification.","operationId":"update_password_auth_v2_update_password_post","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/auth/v2/mcp-grant":{"post":{"tags":["auth-cookies"],"summary":"Create Mcp Grant","description":"Create a short-lived signed grant for MCP OAuth authorization.\n\nCalled by the web app after the user approves the consent card on the MCP authorize\npage. Requires a valid session cookie (user must be logged in) and a JSON body\n`{\"return_to\": <the /authorize URL the page was handed>}` - the grant is BOUND to\nthat request's client_id, redirect_uri and code_challenge (#2698).\n\nReturns a signed JWT grant token (60s TTL, single-use) carrying user identity plus the\nbinding. The MCP worker redeems it, once, for exactly that authorize request.","operationId":"create_mcp_grant_auth_v2_mcp_grant_post","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/auth/v2/validate-mcp-grant":{"post":{"tags":["auth-cookies"],"summary":"Validate Mcp Grant","description":"Validate, bind-check and consume an MCP grant token.\n\nCalled by the MCP worker to exchange a grant for user identity. The grant must carry\nthe SAME client_id / redirect_uri / code_challenge as the request redeeming it\n(`grant_mismatch` otherwise), and its `jti` is consumed once (`grant_reused` on a\nsecond redemption). `detail` is a machine code on every refusal - the worker carries\nit into telemetry - never prose.","operationId":"validate_mcp_grant_auth_v2_validate_mcp_grant_post","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/auth/v2/validate-token":{"post":{"tags":["auth-cookies"],"summary":"Validate Bearer Token","description":"Validate a Supabase JWT and return user identity.\n\nCalled by the MCP worker's resolveExternalToken to validate Supabase JWTs\npassed as Bearer tokens by clients using the /mcp/setup page flow.","operationId":"validate_bearer_token_auth_v2_validate_token_post","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/users/profile":{"get":{"tags":["users"],"summary":"Get User Profile","description":"Get current user profile.\n\nReturns an explicit whitelist (UserProfileResponse), NOT the raw `users` row —\nstripe_*/utm_*/internal counters must never reach the client (#1556). Building\nthe model field-by-field (never passing profile_data through) plus the\nresponse_model make the whitelist structural, not a comment.","operationId":"get_user_profile_users_profile_get","security":[{"HTTPBearer":[]},{"APIKeyHeader":[]}],"parameters":[{"name":"api_key","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Api Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserProfileResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"put":{"tags":["users"],"summary":"Update User Profile","description":"Update user profile information","operationId":"update_user_profile_users_profile_put","security":[{"HTTPBearer":[]},{"APIKeyHeader":[]}],"parameters":[{"name":"api_key","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Api Key"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserProfileUpdate"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/users/usage":{"get":{"tags":["users"],"summary":"Get Usage Statistics","description":"Get current user's API usage statistics","operationId":"get_usage_statistics_users_usage_get","security":[{"HTTPBearer":[]},{"APIKeyHeader":[]}],"parameters":[{"name":"api_key","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Api Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UsageStatsResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/users/usage/daily":{"get":{"tags":["users"],"summary":"Get Daily Usage","description":"Free-tier daily DATA-API CREDIT usage (credit_ledger); the web meter reads /users/usage.\n\nFree tier has a per-day cap that resets midnight UTC; paid tiers don't\n(has_daily_cap=False).\n\n⚠ #2357 — a zero from this ledger is UNFALSIFIABLE. `credit_ledger` is written by\nexactly one route (`GET /api/v1/data/metrics`), so `used_today == 0` cannot\ndistinguish \"consumed nothing\" from \"consumed a plane this ledger cannot see\". It\nheld 3 rows all-time against 157,273 lifetime MCP calls, and this endpoint served\n\"0 / 500 · 500 left\" 653 times to 29 users — one of them on a 3,577-call day. We\ntherefore WITHHOLD rather than assert: no metered consumption ⇒ has_daily_cap=False,\ninstead of reporting a fabricated zero as fact.\n\nThis deliberately does NOT change enforcement, and does NOT repoint the counter at\n`api_usage_logs` — that would swap a fabricated zero for a fan-out over-count AND\nmake the 429 at data_api.py:263 newly reachable, i.e. switch on enforcement inside\na decision that was explicitly \"no enforcement\".","operationId":"get_daily_usage_users_usage_daily_get","security":[{"HTTPBearer":[]},{"APIKeyHeader":[]}],"parameters":[{"name":"api_key","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Api Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DailyUsageResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/users/usage/logs":{"get":{"tags":["users"],"summary":"Get Usage Logs","description":"The current user's real product calls (MCP / API key on /api/v1/), newest first.","operationId":"get_usage_logs_users_usage_logs_get","security":[{"HTTPBearer":[]},{"APIKeyHeader":[]}],"parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":100,"title":"Limit"}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","default":0,"title":"Offset"}},{"name":"api_key","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Api Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/ApiUsageLogResponse"},"title":"Response Get Usage Logs Users Usage Logs Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/users/subscription":{"get":{"tags":["users"],"summary":"Get Subscription Info","description":"Get current user's subscription information","operationId":"get_subscription_info_users_subscription_get","security":[{"HTTPBearer":[]},{"APIKeyHeader":[]}],"parameters":[{"name":"api_key","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Api Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/users/account":{"delete":{"tags":["users"],"summary":"Delete Account","description":"Delete user account and all associated data.\n\nRefused (409) while a Stripe subscription can still charge the user; see\n_refuse_delete_while_subscription_can_charge. Refused (503) unless the user's MCP OAuth\ngrants are revoked first; see _revoke_mcp_oauth_grants.","operationId":"delete_account_users_account_delete","security":[{"HTTPBearer":[]},{"APIKeyHeader":[]}],"parameters":[{"name":"api_key","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Api Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/users/reset-usage":{"post":{"tags":["users"],"summary":"Reset Monthly Usage","description":"Reset monthly usage counter (admin or development only)","operationId":"reset_monthly_usage_users_reset_usage_post","security":[{"HTTPBearer":[]},{"APIKeyHeader":[]}],"parameters":[{"name":"api_key","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Api Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/users/internal/reset-monthly-api-usage":{"post":{"tags":["users"],"summary":"Reset Monthly Api Usage Internal","description":"Internal endpoint for Cloud Scheduler to reset monthly API request counters.\n\nCalled automatically on the 1st of each month.\nThis endpoint calls the PostgreSQL function reset_monthly_api_requests().\n\nSecurity: Requires valid OIDC token from Cloud Scheduler service account.","operationId":"reset_monthly_api_usage_internal_users_internal_reset_monthly_api_usage_post","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/users/api-keys":{"post":{"tags":["users"],"summary":"Create Api Key","description":"Create a new API key for the authenticated user.\nThe actual key is only shown once during creation.\nRate limit: Maximum 10 active keys per account.","operationId":"create_api_key_users_api_keys_post","security":[{"HTTPBearer":[]},{"APIKeyHeader":[]}],"parameters":[{"name":"api_key","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Api Key"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiKeyCreate"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiKeyResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"get":{"tags":["users"],"summary":"List Api Keys","description":"List all API keys for the authenticated user","operationId":"list_api_keys_users_api_keys_get","security":[{"HTTPBearer":[]},{"APIKeyHeader":[]}],"parameters":[{"name":"api_key","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Api Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/ApiKeyListItem"},"title":"Response List Api Keys Users Api Keys Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/users/api-keys/{key_id}":{"delete":{"tags":["users"],"summary":"Revoke Api Key","description":"Revoke (delete) an API key","operationId":"revoke_api_key_users_api_keys__key_id__delete","security":[{"HTTPBearer":[]},{"APIKeyHeader":[]}],"parameters":[{"name":"key_id","in":"path","required":true,"schema":{"type":"string","title":"Key Id"}},{"name":"api_key","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Api Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/users/api-keys/{key_id}/toggle":{"patch":{"tags":["users"],"summary":"Toggle Api Key","description":"Toggle API key status between active and inactive","operationId":"toggle_api_key_users_api_keys__key_id__toggle_patch","security":[{"HTTPBearer":[]},{"APIKeyHeader":[]}],"parameters":[{"name":"key_id","in":"path","required":true,"schema":{"type":"string","title":"Key Id"}},{"name":"api_key","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Api Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/session":{"get":{"tags":["session"],"summary":"Get Session","description":"Get current session with usage limits and capabilities","operationId":"get_session_api_v1_session_get","deprecated":true,"security":[{"HTTPBearer":[]},{"APIKeyHeader":[]}],"parameters":[{"name":"api_key","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Api Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SessionResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/session/anonymous":{"post":{"tags":["session"],"summary":"Create Anonymous Session","description":"Create a new anonymous session with trial limits","operationId":"create_anonymous_session_api_v1_session_anonymous_post","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SessionResponse"}}}}},"deprecated":true}},"/api/v1/usage/check":{"post":{"tags":["session"],"summary":"Check Usage","description":"Check if user can make a request before actually making it","operationId":"check_usage_api_v1_usage_check_post","deprecated":true,"security":[{"HTTPBearer":[]},{"APIKeyHeader":[]}],"parameters":[{"name":"api_key","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Api Key"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UsageCheckRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UsageCheckResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/usage/increment":{"post":{"tags":["session"],"summary":"Increment Usage","description":"Increment usage counter after successful API call","operationId":"increment_usage_api_v1_usage_increment_post","deprecated":true,"security":[{"HTTPBearer":[]},{"APIKeyHeader":[]}],"parameters":[{"name":"endpoint","in":"query","required":true,"schema":{"type":"string","title":"Endpoint"}},{"name":"api_key","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Api Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/companies/search":{"get":{"tags":["companies","companies"],"summary":"Search Companies","description":"Search for companies by ticker, name, or CIK","operationId":"search_companies_api_v1_companies_search_get","security":[{"HTTPBearer":[]},{"APIKeyHeader":[]}],"parameters":[{"name":"query","in":"query","required":true,"schema":{"type":"string","minLength":1,"maxLength":100,"description":"Search query (ticker, name, or CIK)","title":"Query"},"description":"Search query (ticker, name, or CIK)"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Maximum number of results","default":20,"title":"Limit"},"description":"Maximum number of results"},{"name":"include_delisted","in":"query","required":false,"schema":{"anyOf":[{"type":"boolean"},{"type":"null"}],"description":"False = drop delisted companies from FUZZY tiers (prefix/name); an exact ticker / former-ticker / CIK hit always resolves, delisted or not. Omitted = legacy behavior (delisted included, tagged). This param was silently dropped by the route while advertised by callers (#2198).","title":"Include Delisted"},"description":"False = drop delisted companies from FUZZY tiers (prefix/name); an exact ticker / former-ticker / CIK hit always resolves, delisted or not. Omitted = legacy behavior (delisted included, tagged). This param was silently dropped by the route while advertised by callers (#2198)."},{"name":"api_key","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Api Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/CompanySearchResponse"},"title":"Response Search Companies Api V1 Companies Search Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/public/companies/search":{"get":{"tags":["companies","companies"],"summary":"Search Companies Public","description":"Public company search endpoint with rate limiting.\nReturns limited results for unauthenticated users.","operationId":"search_companies_public_api_v1_public_companies_search_get","security":[{"HTTPBearer":[]},{"APIKeyHeader":[]}],"parameters":[{"name":"query","in":"query","required":true,"schema":{"type":"string","minLength":1,"maxLength":100,"description":"Search query (ticker, name, or CIK)","title":"Query"},"description":"Search query (ticker, name, or CIK)"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":30,"minimum":1,"description":"Maximum number of results (max 30 for public)","default":10,"title":"Limit"},"description":"Maximum number of results (max 30 for public)"},{"name":"include_delisted","in":"query","required":false,"schema":{"anyOf":[{"type":"boolean"},{"type":"null"}],"description":"False = drop delisted companies from FUZZY tiers (prefix/name); exact ticker / former-ticker / CIK hits always resolve. Omitted = legacy behavior (delisted included, tagged).","title":"Include Delisted"},"description":"False = drop delisted companies from FUZZY tiers (prefix/name); exact ticker / former-ticker / CIK hits always resolve. Omitted = legacy behavior (delisted included, tagged)."},{"name":"api_key","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Api Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/CompanySearchResponse"},"title":"Response Search Companies Public Api V1 Public Companies Search Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/public/companies/by-ticker/{ticker}":{"get":{"tags":["companies","companies"],"summary":"Get Company By Ticker Public","description":"Fast exact ticker lookup with multi-layer caching.\nOptimized for SSR validation - returns in <50ms for cached tickers.\n\nSupports historical/alias tickers (e.g., FB → META):\n- Returns canonical ticker with is_alias=true if input was historical\n- Sets X-Canonical-Ticker header for frontend redirect support\n\nUses resolve_ticker() which has:\n- Layer 1: LRU in-memory cache (1000 entries)\n- Layer 2: Distributed cache (24h TTL)\n- Layer 3: BigQuery fallback with partition optimization\n\nReturns:\n    200: Company found\n    404: Company not in database (ticker doesn't exist)\n    503: Temporary infrastructure failure (BigQuery timeout, etc.)\n    500: Unexpected error","operationId":"get_company_by_ticker_public_api_v1_public_companies_by_ticker__ticker__get","parameters":[{"name":"ticker","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":10,"description":"Stock ticker symbol","title":"Ticker"},"description":"Stock ticker symbol"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/CompanySearchResponse"},{"type":"null"}],"title":"Response Get Company By Ticker Public Api V1 Public Companies By Ticker  Ticker  Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/public/companies/popular":{"get":{"tags":["companies","companies"],"summary":"Get Popular Companies","description":"Get popular/frequently searched companies for SEO and initial page load.\nThis endpoint is fully public and cached. Uses in-memory constants for instant response.","operationId":"get_popular_companies_api_v1_public_companies_popular_get","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":50,"minimum":1,"description":"Maximum number of results","default":20,"title":"Limit"},"description":"Maximum number of results"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/CompanySearchResponse"},"title":"Response Get Popular Companies Api V1 Public Companies Popular Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/peers/{cik_or_ticker}":{"get":{"tags":["companies","companies"],"summary":"Get Peers Comparison","description":"Get peer comparison data for a company.\n\nWhen tickers parameter is provided, compares target with specified companies.\nWhen tickers is omitted, auto-selects 2-11 peers by sector + market cap (default behavior).\nIncludes key comparison metrics: market cap, revenue, margins, ratios, growth.\n\nArgs:\n    cik_or_ticker: Company ticker symbol or CIK\n    tickers: Optional comma-separated peer tickers for custom comparison\n\nReturns:\n    PeersComparisonResponse with target company and peers list\n\nRaises:\n    HTTPException: 404 if company not found, 400 for invalid tickers, 500 on server error","operationId":"get_peers_comparison_api_v1_peers__cik_or_ticker__get","security":[{"HTTPBearer":[]},{"APIKeyHeader":[]}],"parameters":[{"name":"cik_or_ticker","in":"path","required":true,"schema":{"type":"string","description":"Company ticker or CIK","title":"Cik Or Ticker"},"description":"Company ticker or CIK"},{"name":"tickers","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Comma-separated list of peer tickers (e.g., 'AAPL,GOOGL,META'). If provided, uses these as peers instead of auto-selection.","examples":["AAPL,GOOGL,META"],"title":"Tickers"},"description":"Comma-separated list of peer tickers (e.g., 'AAPL,GOOGL,META'). If provided, uses these as peers instead of auto-selection."},{"name":"peer_mode","in":"query","required":false,"schema":{"anyOf":[{"type":"string","pattern":"^(tags|sector)?$"},{"type":"null"}],"description":"Peer selection mode: 'tags' uses Jaccard similarity on business model tags. Default uses sector + market cap range. Falls back to sector if company has no classification.","title":"Peer Mode"},"description":"Peer selection mode: 'tags' uses Jaccard similarity on business model tags. Default uses sector + market cap range. Falls back to sector if company has no classification."},{"name":"metrics","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Optional comma-separated metric_ids to render instead of the default curated table (e.g. 'dividend_payout_ratio,dividend_yield,ev_ebitda'). A confident near-miss (operating_margin) is read as the served id and listed in metadata.resolved_metrics; any other unknown id is listed in metadata.ignored_metrics with its closest ids. net_interest_income is served with period_type FY or Q only.","examples":["dividend_payout_ratio,dividend_yield"],"title":"Metrics"},"description":"Optional comma-separated metric_ids to render instead of the default curated table (e.g. 'dividend_payout_ratio,dividend_yield,ev_ebitda'). A confident near-miss (operating_margin) is read as the served id and listed in metadata.resolved_metrics; any other unknown id is listed in metadata.ignored_metrics with its closest ids. net_interest_income is served with period_type FY or Q only."},{"name":"period_type","in":"query","required":false,"schema":{"anyOf":[{"type":"string","pattern":"^(TTM|FY|Q)$"},{"type":"null"}],"description":"TTM (default), FY or Q. FY/Q compare each company's latest reported fiscal year or quarter, read from the same filing_metrics rows as metrics history, with year-over-year growth in metadata.growth_yoy (vs metadata.prior_period_end). At Q the ratios annualized from one quarter (P/E, EV multiples, ROE/ROA/ROIC, yields, turnover) are withheld: metadata.period_withheld_metrics.","title":"Period Type"},"description":"TTM (default), FY or Q. FY/Q compare each company's latest reported fiscal year or quarter, read from the same filing_metrics rows as metrics history, with year-over-year growth in metadata.growth_yoy (vs metadata.prior_period_end). At Q the ratios annualized from one quarter (P/E, EV multiples, ROE/ROA/ROIC, yields, turnover) are withheld: metadata.period_withheld_metrics."},{"name":"api_key","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Api Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PeersComparisonResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/peers/{cik_or_ticker}/suggestions":{"get":{"tags":["companies","companies"],"summary":"Get Peer Suggestions","description":"Get peer company suggestions prioritized by sector/industry match.\n\nReturns up to `limit` companies from the same sector, ranked by:\n1. Industry match (same SIC code) - highest priority\n2. Sector match (same sector, different industry) - medium priority\n3. Market cap similarity - additional ranking factor\n\nUse `exclude` to filter out already-added peers.\n\nArgs:\n    cik_or_ticker: Company ticker symbol or CIK\n    exclude: Comma-separated tickers to exclude\n    limit: Maximum number of suggestions (1-20, default 15)\n\nReturns:\n    PeerSuggestionsResponse with ranked suggestions and target sector/industry","operationId":"get_peer_suggestions_api_v1_peers__cik_or_ticker__suggestions_get","security":[{"HTTPBearer":[]},{"APIKeyHeader":[]}],"parameters":[{"name":"cik_or_ticker","in":"path","required":true,"schema":{"type":"string","description":"Company ticker or CIK","title":"Cik Or Ticker"},"description":"Company ticker or CIK"},{"name":"exclude","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Comma-separated tickers to exclude (already-added peers)","title":"Exclude"},"description":"Comma-separated tickers to exclude (already-added peers)"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":20,"minimum":1,"description":"Maximum suggestions to return","default":15,"title":"Limit"},"description":"Maximum suggestions to return"},{"name":"api_key","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Api Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PeerSuggestionsResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/companies/{ticker}/filings":{"get":{"tags":["companies","companies"],"summary":"Get Company Filings","description":"Get SEC filings for a specific company.\n\nLists from sec_filings by CIK (resolved from ticker) via `_build_enriched_filings`\n— same authoritative path as the public endpoint: acceptance_datetime ordering,\n8-K `items`, computed `sec_filing_url`, and first-party `period_end_date` / fiscal\nlabels from XBRL DEI (NULL for forms without DEI). `has_extracted_text` is left\nNone here to keep the agent/mcp path lean (no extra lookup).\n\nPhase AX A4: `years` parameter added to honor mcp-worker `list_filings`\nyears window. Without it, the 8-K path silently returned only the most\nrecent N rows (default cap), making historical filings (e.g., 2023 M&A\nanchors) unreachable from the canonical text-first agent path.","operationId":"get_company_filings_api_v1_companies__ticker__filings_get","security":[{"HTTPBearer":[]},{"APIKeyHeader":[]}],"parameters":[{"name":"ticker","in":"path","required":true,"schema":{"type":"string","description":"Company ticker symbol","title":"Ticker"},"description":"Company ticker symbol"},{"name":"form_type","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"SEC form type (10-K, 10-Q, 8-K)","title":"Form Type"},"description":"SEC form type (10-K, 10-Q, 8-K)"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":500,"minimum":1,"description":"Maximum number of results","default":100,"title":"Limit"},"description":"Maximum number of results"},{"name":"years","in":"query","required":false,"schema":{"anyOf":[{"type":"integer","maximum":10,"minimum":1},{"type":"null"}],"description":"Lookback window in years (filters filing_date). Omit to return most-recent up to limit.","title":"Years"},"description":"Lookback window in years (filters filing_date). Omit to return most-recent up to limit."},{"name":"api_key","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Api Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/FilingResponse"},"title":"Response Get Company Filings Api V1 Companies  Ticker  Filings Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/public/companies/{ticker}/filings":{"get":{"tags":["companies","companies"],"summary":"Get Company Filings Public","description":"Get SEC filings for a specific company (public, no auth required).\nUsed by the web overview \"Filings your agent reads\" card + enterprise demo page.\n\nLists from the authoritative SEC registry (sec_filings) via\n`_build_enriched_filings`: real `acceptance_datetime` ordering, 8-K `items`,\nserver-of-record `sec_filing_url`, and first-party `period_end_date` /\nfiscal labels from XBRL DEI (NULL — never faked — for forms without DEI).\n`has_extracted_text` marks which filings MetricDuck has read.","operationId":"get_company_filings_public_api_v1_public_companies__ticker__filings_get","parameters":[{"name":"ticker","in":"path","required":true,"schema":{"type":"string","description":"Company ticker symbol","title":"Ticker"},"description":"Company ticker symbol"},{"name":"form_type","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"SEC form type (10-K, 10-Q, 8-K)","title":"Form Type"},"description":"SEC form type (10-K, 10-Q, 8-K)"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":50,"minimum":1,"description":"Maximum number of results","default":20,"title":"Limit"},"description":"Maximum number of results"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/FilingResponse"},"title":"Response Get Company Filings Public Api V1 Public Companies  Ticker  Filings Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/companies/{ticker}/raw-facts":{"get":{"tags":["companies","companies"],"summary":"Get raw XBRL facts for a specific filing","description":"Returns raw XBRL facts from sec_xbrl_facts for a given filing. Use concept_search to filter by concept label (e.g., 'Goodwill,Debt' returns all facts whose concept label contains 'goodwill' or 'debt'). Used by enterprise partners and MCP tools to link facts to source documents.","operationId":"get_raw_facts_api_v1_companies__ticker__raw_facts_get","security":[{"HTTPBearer":[]},{"APIKeyHeader":[]}],"parameters":[{"name":"ticker","in":"path","required":true,"schema":{"type":"string","description":"Company ticker symbol","title":"Ticker"},"description":"Company ticker symbol"},{"name":"accession_number","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"SEC filing accession number. If omitted, resolves from form_type + fiscal_year.","title":"Accession Number"},"description":"SEC filing accession number. If omitted, resolves from form_type + fiscal_year."},{"name":"form_type","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Form type for auto-resolving (e.g., '10-K', '10-Q'). Used when accession_number is omitted.","title":"Form Type"},"description":"Form type for auto-resolving (e.g., '10-K', '10-Q'). Used when accession_number is omitted."},{"name":"fiscal_year","in":"query","required":false,"schema":{"anyOf":[{"type":"integer","maximum":2100,"minimum":2000},{"type":"null"}],"description":"Fiscal year for auto-resolving. Used when accession_number is omitted.","title":"Fiscal Year"},"description":"Fiscal year for auto-resolving. Used when accession_number is omitted."},{"name":"fiscal_period","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Pin the exact period when auto-resolving (Q1/Q2/Q3/Q4/FY). Without it, fiscal_year resolves to the LATEST filing of that year — wrong for 'as of <quarter>' questions. Q4 maps to the annual filing (FY); a quarter defaults form_type to 10-Q, FY to 10-K. Ignored if accession_number or period_history is given.","title":"Fiscal Period"},"description":"Pin the exact period when auto-resolving (Q1/Q2/Q3/Q4/FY). Without it, fiscal_year resolves to the LATEST filing of that year — wrong for 'as of <quarter>' questions. Q4 maps to the annual filing (FY); a quarter defaults form_type to 10-Q, FY to 10-K. Ignored if accession_number or period_history is given."},{"name":"concept_search","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Comma-separated concept label search terms. Filters facts whose concept label or account name contains any of the terms (case-insensitive). Example: 'Goodwill,Impairment' returns Goodwill, GoodwillAcquiredDuringPeriod, GoodwillImpairmentLoss, etc.","title":"Concept Search"},"description":"Comma-separated concept label search terms. Filters facts whose concept label or account name contains any of the terms (case-insensitive). Example: 'Goodwill,Impairment' returns Goodwill, GoodwillAcquiredDuringPeriod, GoodwillImpairmentLoss, etc."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":2000,"minimum":1,"description":"Maximum facts to return","default":500,"title":"Limit"},"description":"Maximum facts to return"},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Offset for pagination","default":0,"title":"Offset"},"description":"Offset for pagination"},{"name":"period_history","in":"query","required":false,"schema":{"type":"boolean","description":"Cross-filing concept series. When true, ignore the single-filing scope and return the matched concept(s)' full as-filed period series across ALL the company's filings (deduped to one row per period, original filing's value), each labeled by period span + duration. Lets agents de-cumulate YTD cash-flow lines themselves (Q2 = 6-month YTD - Q1 3-month). Requires concept_search.","default":false,"title":"Period History"},"description":"Cross-filing concept series. When true, ignore the single-filing scope and return the matched concept(s)' full as-filed period series across ALL the company's filings (deduped to one row per period, original filing's value), each labeled by period span + duration. Lets agents de-cumulate YTD cash-flow lines themselves (Q2 = 6-month YTD - Q1 3-month). Requires concept_search."},{"name":"api_key","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Api Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RawFactsResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/companies/{ticker}/fact-history":{"get":{"tags":["companies","companies"],"summary":"Get amendment comparison for a filing","description":"Returns original vs amended values for facts that changed in an amendment filing. Enables equity researchers to track restatements and value corrections.","operationId":"get_fact_history_api_v1_companies__ticker__fact_history_get","security":[{"HTTPBearer":[]},{"APIKeyHeader":[]}],"parameters":[{"name":"ticker","in":"path","required":true,"schema":{"type":"string","description":"Company ticker symbol","title":"Ticker"},"description":"Company ticker symbol"},{"name":"accession_number","in":"query","required":true,"schema":{"type":"string","description":"Amendment accession number (10-Q/A or 10-K/A)","title":"Accession Number"},"description":"Amendment accession number (10-Q/A or 10-K/A)"},{"name":"show_all","in":"query","required":false,"schema":{"type":"boolean","description":"Include unchanged facts (default: only show changes)","default":false,"title":"Show All"},"description":"Include unchanged facts (default: only show changes)"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":2000,"minimum":1,"description":"Maximum facts to return","default":500,"title":"Limit"},"description":"Maximum facts to return"},{"name":"api_key","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Api Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FactHistoryResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/public/companies/{ticker}/facts-by-period":{"get":{"tags":["companies","companies"],"summary":"Get consolidated facts across multiple filing periods","description":"Returns consolidated (dimension_count=0) XBRL facts across multiple filings for multi-period comparison. Used by enterprise demo pivot table.","operationId":"get_facts_by_period_api_v1_public_companies__ticker__facts_by_period_get","parameters":[{"name":"ticker","in":"path","required":true,"schema":{"type":"string","description":"Company ticker symbol","title":"Ticker"},"description":"Company ticker symbol"},{"name":"periods","in":"query","required":false,"schema":{"type":"integer","maximum":8,"minimum":1,"description":"Number of recent filings to include","default":4,"title":"Periods"},"description":"Number of recent filings to include"},{"name":"form_types","in":"query","required":false,"schema":{"type":"string","description":"Comma-separated form types","default":"10-K,10-Q","title":"Form Types"},"description":"Comma-separated form types"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FactsByPeriodResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/companies/{ticker}/metrics/history":{"get":{"tags":["companies","companies"],"summary":"Historical time series for one or more metrics","description":"Returns the last N periods of a company's metric time series, raw (no upstream reductions). Multi-metric in one call. Use this when computing distributions, trends, or windowed statistics downstream.","operationId":"get_metrics_history_api_v1_companies__ticker__metrics_history_get","parameters":[{"name":"ticker","in":"path","required":true,"schema":{"type":"string","description":"Company ticker symbol","title":"Ticker"},"description":"Company ticker symbol"},{"name":"metric","in":"query","required":true,"schema":{"type":"array","items":{"type":"string"},"description":"Metric id from filing_metrics.metric_id. Repeat param to request multiple in one call. No wildcards.","title":"Metric"},"description":"Metric id from filing_metrics.metric_id. Repeat param to request multiple in one call. No wildcards."},{"name":"window","in":"query","required":false,"schema":{"type":"integer","maximum":40,"minimum":1,"description":"Max observations per metric (20 default, 40 max)","default":20,"title":"Window"},"description":"Max observations per metric (20 default, 40 max)"},{"name":"period_type","in":"query","required":false,"schema":{"$ref":"#/components/schemas/PeriodType","description":"Q = quarterly, FY = fiscal year, TTM = trailing 12M","default":"Q"},"description":"Q = quarterly, FY = fiscal year, TTM = trailing 12M"},{"name":"vantage_date","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"description":"As-of vantage (YYYY-MM-DD): keep only periods whose original filing was published on or before this date, and cite the filing current then. It does NOT reconstruct values: they are the latest filed, so a later restatement or recast (including a later 10-K's comparative columns) is served. revised_after_vantage flags only a later amendment of the period's own filing. Omit for the latest.","title":"Vantage Date"},"description":"As-of vantage (YYYY-MM-DD): keep only periods whose original filing was published on or before this date, and cite the filing current then. It does NOT reconstruct values: they are the latest filed, so a later restatement or recast (including a later 10-K's comparative columns) is served. revised_after_vantage flags only a later amendment of the period's own filing. Omit for the latest."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MetricsHistoryResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/companies/{ticker}/metrics/lineage":{"get":{"tags":["companies","companies"],"summary":"Computed-figure lineage (on-demand derivation node)","description":"The derivation of ONE computed metric at one period: its human formula + immediate inputs, each with a value and a source handle. On-demand audit/verification affordance; drillable one level (derived inputs → call again; base inputs → get_xbrl_facts / the filing).","operationId":"get_metric_lineage_api_v1_companies__ticker__metrics_lineage_get","parameters":[{"name":"ticker","in":"path","required":true,"schema":{"type":"string","description":"Company ticker symbol (e.g., 'AAPL'). Must be exact.","title":"Ticker"},"description":"Company ticker symbol (e.g., 'AAPL'). Must be exact."},{"name":"metric","in":"query","required":true,"schema":{"type":"string","description":"Metric id (e.g. 'net_margin'). Computed metrics only.","title":"Metric"},"description":"Metric id (e.g. 'net_margin'). Computed metrics only."},{"name":"period_type","in":"query","required":false,"schema":{"$ref":"#/components/schemas/PeriodType","description":"Q = quarterly, FY = fiscal year, TTM = trailing 12M","default":"Q"},"description":"Q = quarterly, FY = fiscal year, TTM = trailing 12M"},{"name":"fiscal_year","in":"query","required":false,"schema":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"Pin the fiscal year (e.g. 2025). Omit for the latest period.","title":"Fiscal Year"},"description":"Pin the fiscal year (e.g. 2025). Omit for the latest period."},{"name":"fiscal_period","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Pin the fiscal period (Q1/Q2/Q3/Q4/FY). Omit for the latest.","title":"Fiscal Period"},"description":"Pin the fiscal period (Q1/Q2/Q3/Q4/FY). Omit for the latest."},{"name":"segment","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Reporting segment id. Omit for the consolidated figure.","title":"Segment"},"description":"Reporting segment id. Omit for the consolidated figure."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MetricLineageResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/companies/{ticker}/guidance-vs-actual":{"get":{"tags":["companies","companies"],"summary":"Join transcript forward guidance to 10-Q/K + 8-K actuals for a given fiscal period","operationId":"get_guidance_vs_actual_api_v1_companies__ticker__guidance_vs_actual_get","parameters":[{"name":"ticker","in":"path","required":true,"schema":{"type":"string","description":"Company ticker symbol","title":"Ticker"},"description":"Company ticker symbol"},{"name":"fiscal_period","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Target fiscal period, e.g. \"Q2 FY2026\". If omitted, uses the most recent period with SEC actuals, or a newer quarter whose 8-K earnings release is out when guidance targets it.","title":"Fiscal Period"},"description":"Target fiscal period, e.g. \"Q2 FY2026\". If omitted, uses the most recent period with SEC actuals, or a newer quarter whose 8-K earnings release is out when guidance targets it."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GuidanceVsActualResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/companies/universe":{"get":{"tags":["companies","companies"],"summary":"Get Company Universe","description":"Get company universe for screener building.\n\nReturns companies ordered by market cap (rank).\nClients can filter by sector using the SIC code in the response.\n\nArgs:\n    tickers: Optional comma-separated list of ticker symbols to filter\n    limit: Maximum number of results (default 500, max 5000)\n\nReturns:\n    List of companies with ticker, name, cik, exchange, sic, filer_type","operationId":"get_company_universe_api_v1_companies_universe_get","parameters":[{"name":"tickers","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Comma-separated tickers (e.g., AAPL,MSFT,GOOGL)","title":"Tickers"},"description":"Comma-separated tickers (e.g., AAPL,MSFT,GOOGL)"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":5000,"minimum":1,"description":"Max results","default":500,"title":"Limit"},"description":"Max results"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UniverseResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/companies/{ticker}/data-availability":{"get":{"tags":["companies","companies"],"summary":"Get data availability for a company","description":"Returns lightweight metadata about what filing data, XBRL facts, and analysis is available for a company. Designed for MCP tools and AI agents to discover navigable data before making targeted requests.","operationId":"get_data_availability_api_v1_companies__ticker__data_availability_get","security":[{"HTTPBearer":[]},{"APIKeyHeader":[]}],"parameters":[{"name":"ticker","in":"path","required":true,"schema":{"type":"string","description":"Company ticker symbol","title":"Ticker"},"description":"Company ticker symbol"},{"name":"years","in":"query","required":false,"schema":{"type":"integer","maximum":30,"minimum":1,"description":"Years of history to check. Cap is 30 (generous headroom over the ~2013 corpus floor) so the mcp-worker coverage-envelope consumer (coverage-envelope.ts, sends years=20 to surface the true indexed floor) validates instead of 422-ing (#1776). Real cost guard is maximum_bytes_billed + the cik partition-prune, not this bound.","default":5,"title":"Years"},"description":"Years of history to check. Cap is 30 (generous headroom over the ~2013 corpus floor) so the mcp-worker coverage-envelope consumer (coverage-envelope.ts, sends years=20 to surface the true indexed floor) validates instead of 422-ing (#1776). Real cost guard is maximum_bytes_billed + the cik partition-prune, not this bound."},{"name":"api_key","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Api Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DataAvailabilityResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/companies/{ticker}/events":{"get":{"tags":["companies","companies"],"summary":"IR event calendar — upcoming + past IR events (earnings calls, annual meetings, conferences, investor days) with their material chips (deck / webcast / release / transcript)","operationId":"get_company_events_api_v1_companies__ticker__events_get","parameters":[{"name":"ticker","in":"path","required":true,"schema":{"type":"string","description":"Company ticker symbol (e.g. 'AAPL').","title":"Ticker"},"description":"Company ticker symbol (e.g. 'AAPL')."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompanyEventsResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/companies/{ticker}/earnings-reports":{"get":{"tags":["companies","companies"],"summary":"Per-period Earnings Reports — reporting date + transcript + press release + 10-Q/10-K, one row per fiscal period (honest tri-state cells).","operationId":"get_earnings_reports_api_v1_companies__ticker__earnings_reports_get","parameters":[{"name":"ticker","in":"path","required":true,"schema":{"type":"string","description":"Company ticker symbol (e.g. 'PEP').","title":"Ticker"},"description":"Company ticker symbol (e.g. 'PEP')."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":40,"minimum":1,"description":"Most-recent periods to return.","default":12,"title":"Limit"},"description":"Most-recent periods to return."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EarningsReportsResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/companies/{ticker}/filing-index-bundle":{"get":{"tags":["companies","companies","companies"],"summary":"Aggregate filing-index data — single roundtrip for MCP get_filing_index","description":"Bundle for mcp-worker's get_filing_index. Fans out sub-queries in two\nphases (form-agnostic, then form-gated heavy scans) — see module docstring.","operationId":"get_filing_index_bundle_api_v1_companies__ticker__filing_index_bundle_get","parameters":[{"name":"ticker","in":"path","required":true,"schema":{"type":"string","title":"Ticker"}},{"name":"vantage_date","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"description":"As-of vantage (YYYY-MM-DD): serve the signal map for the latest filing filed ON OR BEFORE this date (point-in-time / 'as of <date>'). Omit for the latest filing.","title":"Vantage Date"},"description":"As-of vantage (YYYY-MM-DD): serve the signal map for the latest filing filed ON OR BEFORE this date (point-in-time / 'as of <date>'). Omit for the latest filing."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FilingIndexBundleResponse"}}}},"404":{"description":"Ticker not found"},"500":{"description":"Required filing_intelligence sub-call failed"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/companies/{ticker}/signal-summary":{"get":{"tags":["companies","companies"],"summary":"Get per-signal availability counts for a company","description":"Returns aggregated signal counts (one row per (signal_id, source_event_type)) for a single company. Designed for MCP `browse_company` to surface signal availability inline — prevents the agent from having to fetch a filing to discover what signals it carries.","operationId":"get_signal_summary_api_v1_companies__ticker__signal_summary_get","security":[{"HTTPBearer":[]},{"APIKeyHeader":[]}],"parameters":[{"name":"ticker","in":"path","required":true,"schema":{"type":"string","description":"Company ticker symbol","title":"Ticker"},"description":"Company ticker symbol"},{"name":"years","in":"query","required":false,"schema":{"type":"integer","maximum":10,"minimum":1,"description":"Years of signal history to aggregate","default":5,"title":"Years"},"description":"Years of signal history to aggregate"},{"name":"api_key","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Api Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SignalSummaryResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/companies/{ticker}/income-statement":{"get":{"tags":["financial-statements","Financial Statements"],"summary":"Get income statement data","description":"Returns quarterly, annual, or TTM income statement line items for a company.\n\n    Includes revenue, costs, gross profit, operating income, net income, and EPS data.\n    Optional segment-level breakdown available for companies with multiple business segments.\n\n    **Data Source:** SEC EDGAR (10-K, 10-Q filings)\n    **Data Freshness:** Updated within 24 hours of SEC filing\n    **Caching:** Responses cached 1 hour","operationId":"get_income_statement_api_v1_companies__ticker__income_statement_get","security":[{"HTTPBearer":[]},{"APIKeyHeader":[]}],"parameters":[{"name":"ticker","in":"path","required":true,"schema":{"type":"string","description":"Company ticker symbol (e.g., 'AAPL', 'MSFT')","title":"Ticker"},"description":"Company ticker symbol (e.g., 'AAPL', 'MSFT')"},{"name":"period","in":"query","required":false,"schema":{"type":"string","pattern":"^(quarterly|annual|ttm)$","description":"Aggregation level: 'quarterly', 'annual', or 'ttm' (trailing twelve months)","default":"quarterly","title":"Period"},"description":"Aggregation level: 'quarterly', 'annual', or 'ttm' (trailing twelve months)"},{"name":"years","in":"query","required":false,"schema":{"type":"integer","maximum":10,"minimum":1,"description":"Number of years of historical data to return (1-10)","default":5,"title":"Years"},"description":"Number of years of historical data to return (1-10)"},{"name":"include_segment_hierarchy","in":"query","required":false,"schema":{"type":"boolean","description":"Include hierarchical business segment breakdown (if available)","default":false,"title":"Include Segment Hierarchy"},"description":"Include hierarchical business segment breakdown (if available)"},{"name":"vantage_date","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"description":"As-of vantage (YYYY-MM-DD): bounds which periods are visible (filed on or before this date) and which filing is cited. It does NOT reconstruct values: they are the latest filed, so a later restatement or recast (including a later 10-K's comparative columns) is served under the vantage-era citation. revised_after_vantage flags only a later amendment of the period's own filing. For values as known at the vantage, query XBRL facts pinned to the latest filing on or before it that reports the period; XBRL facts with period_history give values as originally filed. Omit for the latest.","title":"Vantage Date"},"description":"As-of vantage (YYYY-MM-DD): bounds which periods are visible (filed on or before this date) and which filing is cited. It does NOT reconstruct values: they are the latest filed, so a later restatement or recast (including a later 10-K's comparative columns) is served under the vantage-era citation. revised_after_vantage flags only a later amendment of the period's own filing. For values as known at the vantage, query XBRL facts pinned to the latest filing on or before it that reports the period; XBRL facts with period_history give values as originally filed. Omit for the latest."},{"name":"signed","in":"query","required":false,"schema":{"type":"boolean","description":"Apply statement-faithful presentation signs (default false → positive magnitudes). When true, income-statement deductions (interest_expense, gain_loss_invests) are returned negative as they appear on the filed statement.","default":false,"title":"Signed"},"description":"Apply statement-faithful presentation signs (default false → positive magnitudes). When true, income-statement deductions (interest_expense, gain_loss_invests) are returned negative as they appear on the filed statement."},{"name":"api_key","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Api Key"}}],"responses":{"200":{"description":"Success - Returns list of income statement periods","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/IncomeStatementItem"},"title":"Response 200 Get Income Statement Api V1 Companies  Ticker  Income Statement Get"}}}},"400":{"description":"Bad Request - Invalid parameters (check ticker format, period, or years)"},"404":{"description":"Not Found - Ticker not found or no data available for requested period"},"429":{"description":"Too Many Requests - Rate limit exceeded (see Retry-After header)"},"500":{"description":"Internal Server Error - Database or service error"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/companies/{ticker}/balance-sheet":{"get":{"tags":["financial-statements","Financial Statements"],"summary":"Get balance sheet data","description":"Returns quarterly, annual, or TTM balance sheet line items for a company.\n\n    Includes assets, liabilities, equity, debt metrics, and working capital data.\n    Point-in-time snapshot metrics showing financial position as of period end.\n\n    **Data Source:** SEC EDGAR (10-K, 10-Q filings)\n    **Data Freshness:** Updated within 24 hours of SEC filing\n    **Caching:** Responses cached 1 hour","operationId":"get_balance_sheet_api_v1_companies__ticker__balance_sheet_get","security":[{"HTTPBearer":[]},{"APIKeyHeader":[]}],"parameters":[{"name":"ticker","in":"path","required":true,"schema":{"type":"string","description":"Company ticker symbol (e.g., 'AAPL', 'MSFT')","title":"Ticker"},"description":"Company ticker symbol (e.g., 'AAPL', 'MSFT')"},{"name":"period","in":"query","required":false,"schema":{"type":"string","pattern":"^(quarterly|annual|ttm)$","description":"Aggregation level: 'quarterly', 'annual', or 'ttm' (trailing twelve months)","default":"quarterly","title":"Period"},"description":"Aggregation level: 'quarterly', 'annual', or 'ttm' (trailing twelve months)"},{"name":"years","in":"query","required":false,"schema":{"type":"integer","maximum":10,"minimum":1,"description":"Number of years of historical data to return (1-10)","default":5,"title":"Years"},"description":"Number of years of historical data to return (1-10)"},{"name":"vantage_date","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"description":"As-of vantage (YYYY-MM-DD): bounds which periods are visible (filed on or before this date) and which filing is cited. It does NOT reconstruct values: they are the latest filed, so a later restatement or recast (including a later 10-K's comparative columns) is served under the vantage-era citation. revised_after_vantage flags only a later amendment of the period's own filing. For values as known at the vantage, query XBRL facts pinned to the latest filing on or before it that reports the period; XBRL facts with period_history give values as originally filed. Omit for the latest.","title":"Vantage Date"},"description":"As-of vantage (YYYY-MM-DD): bounds which periods are visible (filed on or before this date) and which filing is cited. It does NOT reconstruct values: they are the latest filed, so a later restatement or recast (including a later 10-K's comparative columns) is served under the vantage-era citation. revised_after_vantage flags only a later amendment of the period's own filing. For values as known at the vantage, query XBRL facts pinned to the latest filing on or before it that reports the period; XBRL facts with period_history give values as originally filed. Omit for the latest."},{"name":"api_key","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Api Key"}}],"responses":{"200":{"description":"Success - Returns list of balance sheet periods","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/BalanceSheetItem"},"title":"Response 200 Get Balance Sheet Api V1 Companies  Ticker  Balance Sheet Get"}}}},"400":{"description":"Bad Request - Invalid parameters (check ticker format, period, or years)"},"404":{"description":"Not Found - Ticker not found or no data available for requested period"},"429":{"description":"Too Many Requests - Rate limit exceeded (see Retry-After header)"},"500":{"description":"Internal Server Error - Database or service error"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/companies/{ticker}/cash-flow":{"get":{"tags":["financial-statements","Financial Statements"],"summary":"Get cash flow statement data","description":"Returns quarterly, annual, or TTM cash flow statement line items for a company.\n\n    Includes operating, investing, and financing cash flows, plus free cash flow calculations.\n    Period-based cumulative metrics showing cash generation and allocation.\n\n    **Data Source:** SEC EDGAR (10-K, 10-Q filings)\n    **Data Freshness:** Updated within 24 hours of SEC filing\n    **Caching:** Responses cached 1 hour","operationId":"get_cash_flow_statement_api_v1_companies__ticker__cash_flow_get","security":[{"HTTPBearer":[]},{"APIKeyHeader":[]}],"parameters":[{"name":"ticker","in":"path","required":true,"schema":{"type":"string","description":"Company ticker symbol (e.g., 'AAPL', 'MSFT')","title":"Ticker"},"description":"Company ticker symbol (e.g., 'AAPL', 'MSFT')"},{"name":"period","in":"query","required":false,"schema":{"type":"string","pattern":"^(quarterly|annual|ttm)$","description":"Aggregation level: 'quarterly', 'annual', or 'ttm' (trailing twelve months)","default":"quarterly","title":"Period"},"description":"Aggregation level: 'quarterly', 'annual', or 'ttm' (trailing twelve months)"},{"name":"years","in":"query","required":false,"schema":{"type":"integer","maximum":10,"minimum":1,"description":"Number of years of historical data to return (1-10)","default":5,"title":"Years"},"description":"Number of years of historical data to return (1-10)"},{"name":"vantage_date","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"description":"As-of vantage (YYYY-MM-DD): bounds which periods are visible (filed on or before this date) and which filing is cited. It does NOT reconstruct values: they are the latest filed, so a later restatement or recast (including a later 10-K's comparative columns) is served under the vantage-era citation. revised_after_vantage flags only a later amendment of the period's own filing. For values as known at the vantage, query XBRL facts pinned to the latest filing on or before it that reports the period; XBRL facts with period_history give values as originally filed. Omit for the latest.","title":"Vantage Date"},"description":"As-of vantage (YYYY-MM-DD): bounds which periods are visible (filed on or before this date) and which filing is cited. It does NOT reconstruct values: they are the latest filed, so a later restatement or recast (including a later 10-K's comparative columns) is served under the vantage-era citation. revised_after_vantage flags only a later amendment of the period's own filing. For values as known at the vantage, query XBRL facts pinned to the latest filing on or before it that reports the period; XBRL facts with period_history give values as originally filed. Omit for the latest."},{"name":"signed","in":"query","required":false,"schema":{"type":"boolean","description":"Apply statement-faithful presentation signs (default false → positive magnitudes). When true, cash outflows (capex, dividends_paid, stock_repurch) and operating asset-increases (chg_accs_recvb, chg_inventory, oper_other_cf) are returned negative as on the filed statement; already-signed nets (net_cf_inv/fin, chg_working_cap, defer_inc_taxes_cf) pass through unchanged. Use this for cash-flow reconstruction / DCF.","default":false,"title":"Signed"},"description":"Apply statement-faithful presentation signs (default false → positive magnitudes). When true, cash outflows (capex, dividends_paid, stock_repurch) and operating asset-increases (chg_accs_recvb, chg_inventory, oper_other_cf) are returned negative as on the filed statement; already-signed nets (net_cf_inv/fin, chg_working_cap, defer_inc_taxes_cf) pass through unchanged. Use this for cash-flow reconstruction / DCF."},{"name":"api_key","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Api Key"}}],"responses":{"200":{"description":"Success - Returns list of cash flow periods","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/CashFlowItem"},"title":"Response 200 Get Cash Flow Statement Api V1 Companies  Ticker  Cash Flow Get"}}}},"400":{"description":"Bad Request - Invalid parameters (check ticker format, period, or years)"},"404":{"description":"Not Found - Ticker not found or no data available for requested period"},"429":{"description":"Too Many Requests - Rate limit exceeded (see Retry-After header)"},"500":{"description":"Internal Server Error - Database or service error"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/metrics":{"get":{"tags":["metrics"],"summary":"Get Available Metrics","description":"Get list of available financial metrics and their descriptions.\n\nUses in-memory startup cache for instant response (0ms vs 20-30ms BigQuery).\nFalls back to BigQuery if cache not loaded.\nCached automatically by cache_middleware (24 hours in prod, 2 min in dev).\nPublic endpoint with optional auth for tracking.","operationId":"get_available_metrics_api_v1_metrics_get","security":[{"HTTPBearer":[]},{"APIKeyHeader":[]}],"parameters":[{"name":"api_key","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Api Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/MetricsListResponse"},"title":"Response Get Available Metrics Api V1 Metrics Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/metrics/catalog":{"get":{"tags":["metrics"],"summary":"Get Metrics Catalog","description":"Get enhanced metrics catalog for metric picker UI.\n\nIncludes all metadata needed for metric picker:\n- Search tags and aliases for discoverability\n- Formatting configuration for UI display\n- Relationships (depends_on, related_metrics)\n- Plain-English formula explanations\n\nCached automatically by cache_middleware (24 hours in prod, 2 min in dev).\nPublic endpoint with optional auth for tracking.","operationId":"get_metrics_catalog_api_v1_metrics_catalog_get","security":[{"HTTPBearer":[]},{"APIKeyHeader":[]}],"parameters":[{"name":"category","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Filter by category","title":"Category"},"description":"Filter by category"},{"name":"search","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Search by keyword in name, description, or tags","title":"Search"},"description":"Search by keyword in name, description, or tags"},{"name":"api_key","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Api Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MetricCatalogResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/metrics/{metric_id}/seo":{"get":{"tags":["metrics"],"summary":"Get Metric Seo","description":"Get SEO-optimized metric metadata for blog and glossary pages.\n\nIncludes:\n- SEO slug and keywords\n- Plain-English formula explanation\n- Use cases and interpretation guidance\n- Typical ranges and examples\n- Related metrics for cross-linking\n\nCached automatically by cache_middleware (24 hours in prod, 2 min in dev).\nPublic endpoint with optional auth for tracking.","operationId":"get_metric_seo_api_v1_metrics__metric_id__seo_get","security":[{"HTTPBearer":[]},{"APIKeyHeader":[]}],"parameters":[{"name":"metric_id","in":"path","required":true,"schema":{"type":"string","description":"Metric identifier","title":"Metric Id"},"description":"Metric identifier"},{"name":"api_key","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Api Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MetricSEOResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/companies/{ticker}/ratios":{"get":{"tags":["metrics"],"summary":"Get Ratios","description":"Get financial ratios and operational metrics for a specific company","operationId":"get_ratios_api_v1_companies__ticker__ratios_get","security":[{"HTTPBearer":[]},{"APIKeyHeader":[]}],"parameters":[{"name":"ticker","in":"path","required":true,"schema":{"type":"string","description":"Company ticker symbol","title":"Ticker"},"description":"Company ticker symbol"},{"name":"period","in":"query","required":false,"schema":{"type":"string","description":"Period type: quarterly, annual, or ttm","default":"quarterly","title":"Period"},"description":"Period type: quarterly, annual, or ttm"},{"name":"years","in":"query","required":false,"schema":{"type":"integer","maximum":10,"minimum":1,"description":"Number of years of data","default":5,"title":"Years"},"description":"Number of years of data"},{"name":"api_key","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Api Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/RatiosItem"},"title":"Response Get Ratios Api V1 Companies  Ticker  Ratios Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/earnings/{identifier}/latest":{"get":{"tags":["earnings"],"summary":"Get latest earnings insights (experimental)","description":"Get the latest LLM-extracted earnings insights for a company.\n\n    This endpoint returns insights from 8-K earnings releases processed by our\n    experimental LLM pipeline. Data is auto-expired after 180 days.\n\n    **Identifier can be:**\n    - Ticker symbol (e.g., 'COST', 'AAPL')\n    - CIK (10-digit, e.g., '0000909832')\n\n    **Data Source:** earnings_insights_experimental dataset (top 2000 companies only)\n\n    **Note:** This is an experimental feature. Coverage is limited and insights\n    are generated by AI (Gemini 1.5 Flash). Always verify critical information.","operationId":"get_latest_earnings_insights_api_v1_earnings__identifier__latest_get","security":[{"HTTPBearer":[]},{"APIKeyHeader":[]}],"parameters":[{"name":"identifier","in":"path","required":true,"schema":{"type":"string","description":"Ticker symbol or CIK","title":"Identifier"},"description":"Ticker symbol or CIK"},{"name":"api_key","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Api Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EarningsInsight"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/earnings/{identifier}/history":{"get":{"tags":["earnings"],"summary":"Get earnings history (N quarters)","description":"Get historical earnings insights for a company (up to 8 most recent quarters).\n\n    Returns a list of earnings insights ordered by filing_date DESC (latest first).\n    This endpoint is optimized for building quarterly timeline views.\n\n    **Identifier can be:**\n    - Ticker symbol (e.g., 'COST', 'AAPL')\n    - CIK (10-digit, e.g., '0000909832')\n\n    **Data Source:** earnings_insights_experimental dataset (top 2000 companies only)\n    **Retention:** 500 days (~5 quarters)\n\n    **Note:** This is an experimental feature. Coverage is limited and insights\n    are generated by AI (Gemini 1.5 Flash). Always verify critical information.","operationId":"get_earnings_history_api_v1_earnings__identifier__history_get","security":[{"HTTPBearer":[]},{"APIKeyHeader":[]}],"parameters":[{"name":"identifier","in":"path","required":true,"schema":{"type":"string","description":"Ticker symbol or CIK","title":"Identifier"},"description":"Ticker symbol or CIK"},{"name":"quarters","in":"query","required":false,"schema":{"type":"integer","maximum":8,"minimum":1,"description":"Number of quarters to return","default":8,"title":"Quarters"},"description":"Number of quarters to return"},{"name":"vantage_date","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"description":"#2077 as-of: serve releases KNOWN on/before this date (walks back from the vantage instead of today; omit for latest)","title":"Vantage Date"},"description":"#2077 as-of: serve releases KNOWN on/before this date (walks back from the vantage instead of today; omit for latest)"},{"name":"api_key","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Api Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/EarningsInsight"},"title":"Response Get Earnings History Api V1 Earnings  Identifier  History Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/earnings-calendar/next-filings":{"get":{"tags":["earnings-calendar"],"summary":"Get Next Filings","description":"Get next predicted filings for companies.\n\n**Use Cases**:\n- Alert table batch lookup: `?cik=0000320193,0000789019&form_type=8-K-2.02`\n- Single company check: `?cik=0000320193&days=30`\n- Browse upcoming filings: `?days=30&limit=20&offset=0`\n- Filter by form type: `?form_type=10-Q,10-K&days=60`\n\n**Response**: Companies with next_filing dict keyed by form_type","operationId":"get_next_filings_api_v1_earnings_calendar_next_filings_get","security":[{"HTTPBearer":[]},{"APIKeyHeader":[]}],"parameters":[{"name":"cik","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Single CIK or comma-separated list of CIKs for batch lookup","title":"Cik"},"description":"Single CIK or comma-separated list of CIKs for batch lookup"},{"name":"form_type","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Filter by form type(s): 10-Q, 10-K, 8-K-2.02 (comma-separated)","title":"Form Type"},"description":"Filter by form type(s): 10-Q, 10-K, 8-K-2.02 (comma-separated)"},{"name":"days","in":"query","required":false,"schema":{"type":"integer","maximum":365,"minimum":1,"description":"Look ahead N days for upcoming filings","default":90,"title":"Days"},"description":"Look ahead N days for upcoming filings"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":1000,"minimum":1,"description":"Maximum number of companies to return","default":100,"title":"Limit"},"description":"Maximum number of companies to return"},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Pagination offset","default":0,"title":"Offset"},"description":"Pagination offset"},{"name":"min_rank","in":"query","required":false,"schema":{"anyOf":[{"type":"integer","minimum":1},{"type":"null"}],"description":"Filter to top N companies by market cap rank","title":"Min Rank"},"description":"Filter to top N companies by market cap rank"},{"name":"api_key","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Api Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NextFilingsResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/market/daily/{ticker}":{"get":{"tags":["market"],"summary":"Get Daily Market Data","description":"Get daily market data for a specific ticker\n\nReturns OHLCV + VWAP data for the specified ticker and date range: the vendor feed, or\nunder PRICE_SOURCE=iex IEX's daily close with split-adjusted adj_close (OHLV/VWAP absent).\n`metadata.data_source` names which (core/price_source.py).","operationId":"get_daily_market_data_api_v1_market_daily__ticker__get","security":[{"HTTPBearer":[]},{"APIKeyHeader":[]}],"parameters":[{"name":"ticker","in":"path","required":true,"schema":{"type":"string","pattern":"^[A-Z]{1,5}([.-][A-Z]{1,3})?$","description":"Stock ticker symbol (share classes allowed, e.g. BRK-B)","title":"Ticker"},"description":"Stock ticker symbol (share classes allowed, e.g. BRK-B)"},{"name":"start_date","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"description":"Start date (YYYY-MM-DD)","title":"Start Date"},"description":"Start date (YYYY-MM-DD)"},{"name":"end_date","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"description":"End date (YYYY-MM-DD)","title":"End Date"},"description":"End date (YYYY-MM-DD)"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":2000,"minimum":1,"description":"Maximum records to return","default":365,"title":"Limit"},"description":"Maximum records to return"},{"name":"api_key","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Api Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketDataResponse"}}}},"404":{"description":"Ticker not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"400":{"description":"Invalid request parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/market/summary/{ticker}":{"get":{"tags":["market"],"summary":"Get Market Data Summary","description":"Get summary statistics for market data\n\nReturns aggregated statistics like min/max prices, average volume, etc.\nfor the specified ticker over the given number of days.","operationId":"get_market_data_summary_api_v1_market_summary__ticker__get","security":[{"HTTPBearer":[]},{"APIKeyHeader":[]}],"parameters":[{"name":"ticker","in":"path","required":true,"schema":{"type":"string","pattern":"^[A-Z]{1,5}([.-][A-Z]{1,3})?$","description":"Stock ticker symbol (share classes allowed, e.g. BRK-B)","title":"Ticker"},"description":"Stock ticker symbol (share classes allowed, e.g. BRK-B)"},{"name":"days","in":"query","required":false,"schema":{"type":"integer","maximum":3650,"minimum":1,"description":"Number of days to analyze","default":365,"title":"Days"},"description":"Number of days to analyze"},{"name":"api_key","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Api Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketDataSummary"}}}},"404":{"description":"Ticker not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/market/health":{"get":{"tags":["market"],"summary":"Market Health Check","description":"Health check endpoint for market data service","operationId":"market_health_check_api_v1_market_health_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/api/v1/billing/create-checkout-session":{"post":{"tags":["billing"],"summary":"Create Checkout Session","description":"Create a Stripe Checkout session for subscription\n\nArgs:\n    request: Checkout session parameters\n    current_user: Authenticated user\n\nReturns:\n    Checkout URL and session ID","operationId":"create_checkout_session_api_v1_billing_create_checkout_session_post","security":[{"HTTPBearer":[]},{"APIKeyHeader":[]}],"parameters":[{"name":"api_key","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Api Key"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CheckoutSessionRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Create Checkout Session Api V1 Billing Create Checkout Session Post"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/billing/billing-portal":{"post":{"tags":["billing"],"summary":"Create Billing Portal Session","description":"Create a Stripe Customer Portal session for subscription management\n\nArgs:\n    request: Portal session parameters\n    current_user: Authenticated user\n\nReturns:\n    Portal URL","operationId":"create_billing_portal_session_api_v1_billing_billing_portal_post","security":[{"HTTPBearer":[]},{"APIKeyHeader":[]}],"parameters":[{"name":"api_key","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Api Key"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BillingPortalRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":{"type":"string"},"title":"Response Create Billing Portal Session Api V1 Billing Billing Portal Post"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/billing/stripe-webhook":{"post":{"tags":["billing"],"summary":"Stripe Webhook","description":"Handle Stripe webhook events\n\nAn event id is recorded only AFTER it is processed. A processing error returns 500 so\nStripe retries the event; a recorded id is acknowledged without reprocessing.","operationId":"stripe_webhook_api_v1_billing_stripe_webhook_post","parameters":[{"name":"stripe-signature","in":"header","required":false,"schema":{"type":"string","title":"Stripe-Signature"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/billing/subscription-status":{"get":{"tags":["billing"],"summary":"Get Subscription Status","description":"Get current user's subscription status\n\nFetches fresh from database to avoid stale cache after webhook updates.\n\nFor a paying (or canceling) subscriber, the price and the period end are read live\nfrom Stripe (nothing stores them). That read fails soft: on any error or after\nSTRIPE_CALL_TIMEOUT_SECONDS the Stripe fields are null and the response is still\n200, so the billing page always renders.\n\nReturns:\n    tier, status, subscription_end_date (from the users row); plan_name and\n    allowance_label (from PRICING_TIERS); amount (minor units, null unless it is\n    exactly what is charged), currency, interval, current_period_end and cancel_at\n    (ISO UTC) and cancel_at_period_end (from Stripe, else null); manage_billing (the\n    Stripe read succeeded, so the billing portal can open).","operationId":"get_subscription_status_api_v1_billing_subscription_status_get","security":[{"HTTPBearer":[]},{"APIKeyHeader":[]}],"parameters":[{"name":"api_key","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Api Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Get Subscription Status Api V1 Billing Subscription Status Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/billing/verify-checkout-session":{"get":{"tags":["billing"],"summary":"Verify Checkout Session","description":"Verify a completed checkout session and return updated subscription info.\n\nCalled by frontend after Stripe redirects back with session_id.","operationId":"verify_checkout_session_api_v1_billing_verify_checkout_session_get","security":[{"HTTPBearer":[]},{"APIKeyHeader":[]}],"parameters":[{"name":"session_id","in":"query","required":true,"schema":{"type":"string","title":"Session Id"}},{"name":"api_key","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Api Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Verify Checkout Session Api V1 Billing Verify Checkout Session Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/billing/pricing-tiers":{"get":{"tags":["billing"],"summary":"Get Pricing Tiers","description":"Get all available pricing tiers and their configurations.\n\nReturns:\n    Dictionary of all tiers with their features, prices, and Stripe Price IDs","operationId":"get_pricing_tiers_api_v1_billing_pricing_tiers_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","title":"Response Get Pricing Tiers Api V1 Billing Pricing Tiers Get"}}}}}}},"/api/v1/screener/metrics":{"get":{"tags":["screener","screener"],"summary":"Get Metrics","description":"Get all filterable metrics with metadata and hierarchical organization.\n\nReturns:\n- Hierarchical structure: Category → Subcategory → Metrics\n- Metric metadata: display_name, description, unit, data_type\n- 253 metrics across 5 categories (measured 2026-09-16; was documented as 131/4)\n\nResults are cached for 60 minutes (metrics rarely change).","operationId":"get_metrics_api_v1_screener_metrics_get","security":[{"HTTPBearer":[]},{"APIKeyHeader":[]}],"parameters":[{"name":"api_key","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Api Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/screener/curated-metrics":{"get":{"tags":["screener","screener"],"summary":"Get Curated Metrics","description":"Get curated 24 metrics for simplified screener with presets and metadata.\n\nReturns:\n- 24 carefully selected metrics across 5 categories\n- 6 growth metrics with explicit period_type (ttm.yoy, ttm.cagr3, ss.yoy)\n- 5 curated presets (Growth, Value, Quality, Dividend, Small Cap)\n- Filter suggestions and typical ranges per metric\n- Formatting rules (decimals, suffix, color coding)\n\nResults cached for 60 minutes (rarely changes).","operationId":"get_curated_metrics_api_v1_screener_curated_metrics_get","security":[{"HTTPBearer":[]},{"APIKeyHeader":[]}],"parameters":[{"name":"api_key","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Api Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/screener/filter-templates":{"get":{"tags":["screener","screener"],"summary":"Get Filter Templates","description":"Get filter templates for each data type.\nProvides suggested filter ranges based on metric data_type.\n\nReturns:\n- currency: Market cap ranges (micro, small, mid, large, mega)\n- percentage: Common percentage ranges (negative, low, moderate, high)\n- ratio: Common ratio ranges (valuation multiples, etc.)\n- days: Day ranges (DSO, DIO, etc.)\n- shares: Share count ranges","operationId":"get_filter_templates_api_v1_screener_filter_templates_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/api/v1/screener/screen":{"post":{"tags":["screener","screener"],"summary":"Screen Companies","description":"Screen companies using dynamic metric filters.\n\nServes the latest-snapshot values (rebuilt every ~12h — the same freshness\ncontract as the overview/factsheet surfaces). Supports dynamic filter\narrays, custom operators (lt, lte, gt, gte, eq, between), dynamic column\nselection, and flexible sorting.","operationId":"screen_companies_api_v1_screener_screen_post","security":[{"HTTPBearer":[]},{"APIKeyHeader":[]}],"parameters":[{"name":"api_key","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Api Key"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScreenRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/screener/health":{"get":{"tags":["screener","screener"],"summary":"Screener Health","description":"Health check endpoint for screener","operationId":"screener_health_api_v1_screener_health_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/api/v1/screener/benchmarks/software":{"get":{"tags":["screener","screener"],"summary":"Get Software Benchmarks","description":"Get financial benchmarks for software companies (SIC 7370-7379).\n\n**Metrics Included:**\n- **Rule of 40**: Revenue Growth + EBITDA Margin (industry standard)\n- **Gross Margin**: Software scalability indicator (70%+ expected)\n- **FCF Margin**: Cash generation efficiency\n- **EBITDA Margin**: Operating profitability\n- **Net Margin**: Bottom-line profitability\n- **ROIC**: Included with caveat (misleading for asset-light businesses)\n\n**Why Rule of 40 over ROIC:**\nPractitioners (VCs, PE, public equity analysts) primarily use Rule of 40\nfor software companies because:\n1. Software has near-zero invested capital → ROIC denominator problems\n2. Rule of 40 balances growth vs profitability trade-off\n3. Correlates strongly with valuations (McKinsey, BCG research)\n\n**Benchmark Statistics:**\n- P25 (25th percentile): Bottom quartile\n- Median (50th percentile): Typical for software\n- P75 (75th percentile): Top quartile\n\n**Cache:** Results cached for 6 hours.","operationId":"get_software_benchmarks_api_v1_screener_benchmarks_software_get","security":[{"HTTPBearer":[]},{"APIKeyHeader":[]}],"parameters":[{"name":"api_key","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Api Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SoftwareBenchmarks"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/screener/benchmarks/{metric_id}/sectors":{"get":{"tags":["screener","screener"],"summary":"Get Metric Sector Benchmarks","description":"Get sector benchmarks for any metric.\n\nReturns percentile-based benchmarks (P25, Median, P75) by sector,\ncomputed from the latest filing data for each company.\n\n**Supported Metrics:**\nAny metric_id from filing_metrics table (250+ metrics available).\nCommon examples: gross_margin, oper_margin, net_margin, roe, roa,\ndebt_to_equity, current_ratio, asset_turnover, etc.\n\n**Sectors Included:**\n- Retail & Consumer Goods (SIC 5200-5999)\n- Manufacturing & Industrials (SIC 2000-3999)\n- Healthcare & Pharmaceuticals (SIC 8000-8099)\n- Utilities & Infrastructure (SIC 4900-4999)\n- Transportation & Logistics (SIC 4000-4799)\n- Energy & Resources (SIC 1000-1499)\n- Technology (SIC 7000-7999)\n- Financial Services (SIC 6000-6499)\n- Real Estate (SIC 6500-6799)\n\n**Cache:** Results cached for 6 hours.","operationId":"get_metric_sector_benchmarks_api_v1_screener_benchmarks__metric_id__sectors_get","security":[{"HTTPBearer":[]},{"APIKeyHeader":[]}],"parameters":[{"name":"metric_id","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-z][a-z0-9_]*$","description":"Metric ID (e.g., 'gross_margin', 'roe', 'debt_to_equity')","title":"Metric Id"},"description":"Metric ID (e.g., 'gross_margin', 'roe', 'debt_to_equity')"},{"name":"period","in":"query","required":false,"schema":{"type":"string","pattern":"^(ttm|annual|quarterly)$","description":"Period type: 'ttm', 'annual', or 'quarterly'","default":"ttm","title":"Period"},"description":"Period type: 'ttm', 'annual', or 'quarterly'"},{"name":"api_key","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Api Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MetricBenchmarkList"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/screener/benchmarks/{metric_id}/sectors/{sector}":{"get":{"tags":["screener","screener"],"summary":"Get Metric Sector Benchmark","description":"Get benchmark for a specific metric and sector.\n\nReturns percentile statistics for a single sector.","operationId":"get_metric_sector_benchmark_api_v1_screener_benchmarks__metric_id__sectors__sector__get","security":[{"HTTPBearer":[]},{"APIKeyHeader":[]}],"parameters":[{"name":"metric_id","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-z][a-z0-9_]*$","description":"Metric ID","title":"Metric Id"},"description":"Metric ID"},{"name":"sector","in":"path","required":true,"schema":{"type":"string","pattern":"^[A-Z_]+$","description":"Sector code (e.g., 'TECHNOLOGY', 'HEALTHCARE')","title":"Sector"},"description":"Sector code (e.g., 'TECHNOLOGY', 'HEALTHCARE')"},{"name":"period","in":"query","required":false,"schema":{"type":"string","pattern":"^(ttm|annual|quarterly)$","description":"Period type: 'ttm', 'annual', or 'quarterly'","default":"ttm","title":"Period"},"description":"Period type: 'ttm', 'annual', or 'quarterly'"},{"name":"api_key","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Api Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/src__models__benchmarks__MetricBenchmark"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/screener/benchmarks/available":{"get":{"tags":["screener","screener"],"summary":"List Available Benchmark Metrics","description":"List metrics available for benchmarking.\n\nReturns metrics that have sufficient data coverage across sectors.\nUseful for discovering which metrics can be used for research pages.","operationId":"list_available_benchmark_metrics_api_v1_screener_benchmarks_available_get","parameters":[{"name":"period","in":"query","required":false,"schema":{"type":"string","pattern":"^(ttm|annual|quarterly)$","description":"Period type to check availability","default":"ttm","title":"Period"},"description":"Period type to check availability"},{"name":"min_companies","in":"query","required":false,"schema":{"type":"integer","minimum":10,"description":"Minimum companies required across all sectors","default":100,"title":"Min Companies"},"description":"Minimum companies required across all sectors"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/screener/taxonomy":{"get":{"tags":["screener","screener"],"summary":"Get Sector Taxonomy","description":"Get sector taxonomy for ROIC screener.\n\nReturns:\n- **sectors**: List of benchmark sectors with their unified code mappings\n- **default_sectors**: Sector codes selected by default (excludes warning sectors)\n- **warning_sectors**: Sectors with unreliable benchmarks (TECHNOLOGY, FINANCIAL, REAL_ESTATE)\n- **unified_to_benchmark**: Map from unified sector code to benchmark sector code\n- **benchmark_to_unified**: Map from benchmark sector code to list of unified codes\n\n**Use Case:**\nFrontend fetches this once on page load to build sector filter UI\nwithout hardcoding sector mappings.\n\n**Cache:** Response is immutable configuration - cache aggressively (24h+).","operationId":"get_sector_taxonomy_api_v1_screener_taxonomy_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SectorTaxonomyResponse"}}}}}}},"/api/v1/research/facts/{account}/sectors":{"get":{"tags":["research","research"],"summary":"Get Fact Sector Benchmarks","description":"Get sector benchmarks for a raw XBRL fact (account).\n\nReturns percentile-based benchmarks (P25, Median, P75) by sector,\ncomputed from the latest consolidated fact for each company.\n\n**Key Features:**\n- Uses consolidated facts only (is_consolidated=TRUE)\n- Gets most recent fact per company (latest as_of_date)\n- Aggregates by sector using SIC code mapping\n\n**Common XBRL Accounts:**\n- Revenue: RevenueFromContractWithCustomerExcludingAssessedTax, Revenues\n- Assets: Assets, CurrentAssets, NoncurrentAssets\n- Liabilities: Liabilities, CurrentLiabilities\n- Cash: CashAndCashEquivalentsAtCarryingValue\n- Income: NetIncomeLoss, OperatingIncomeLoss\n\n**Cache:** Results cached for 6 hours.","operationId":"get_fact_sector_benchmarks_api_v1_research_facts__account__sectors_get","security":[{"HTTPBearer":[]},{"APIKeyHeader":[]}],"parameters":[{"name":"account","in":"path","required":true,"schema":{"type":"string","description":"XBRL account name (e.g., 'RevenueFromContractWithCustomerExcludingAssessedTax', 'Assets')","title":"Account"},"description":"XBRL account name (e.g., 'RevenueFromContractWithCustomerExcludingAssessedTax', 'Assets')"},{"name":"api_key","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Api Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FactBenchmarkList"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/research/facts/available":{"get":{"tags":["research","research"],"summary":"List Available Xbrl Accounts","description":"List XBRL accounts available for benchmarking.\n\nReturns accounts that have sufficient data coverage across companies.\nUseful for discovering which XBRL facts can be used for research pages.\n\n**Note:** Only returns measurement facts (not metadata) from\nconsolidated statements (not dimensional breakdowns).","operationId":"list_available_xbrl_accounts_api_v1_research_facts_available_get","parameters":[{"name":"min_companies","in":"query","required":false,"schema":{"type":"integer","minimum":10,"description":"Minimum companies required with this fact","default":50,"title":"Min Companies"},"description":"Minimum companies required with this fact"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":1000,"minimum":1,"description":"Maximum number of accounts to return","default":200,"title":"Limit"},"description":"Maximum number of accounts to return"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/taxonomy":{"get":{"tags":["sectors"],"summary":"Get Taxonomy","description":"Get complete sector → industry taxonomy hierarchy.\n\nReturns the authoritative sector/industry classification structure.\nFrontend should cache this response (24 hours recommended).\n\nThis is the single source of truth for sector/industry data.\nUse this instead of hardcoded frontend configs.\n\nReturns:\n    Hierarchical taxonomy with sectors containing their industries","operationId":"get_taxonomy_api_v1_taxonomy_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaxonomyResponse"}}}}}}},"/api/v1/sectors":{"get":{"tags":["sectors"],"summary":"Get Sectors","description":"Get all available sectors.\n\nReturns list of 11 major sectors for screener filtering.\n\nReturns:\n    List of sectors with code and name","operationId":"get_sectors_api_v1_sectors_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"items":{"$ref":"#/components/schemas/SectorResponse"},"type":"array","title":"Response Get Sectors Api V1 Sectors Get"}}}}}}},"/api/v1/industries":{"get":{"tags":["sectors"],"summary":"Get Industries","description":"Get all industries, optionally filtered by sector.\n\nArgs:\n    sector_code: Optional sector code to filter industries (e.g., \"TECH\")\n\nReturns:\n    List of industries with code, name, and parent sector","operationId":"get_industries_api_v1_industries_get","parameters":[{"name":"sector_code","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Filter by sector code","title":"Sector Code"},"description":"Filter by sector code"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/IndustryResponse"},"title":"Response Get Industries Api V1 Industries Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/company/{cik}/sector":{"get":{"tags":["sectors"],"summary":"Get Company Sector","description":"Get sector classification for a specific company.\n\nArgs:\n    cik: Company CIK (10-digit identifier)\n\nReturns:\n    Company sector/industry classification with confidence score\n\nRaises:\n    HTTPException: 404 if company not found or classification unavailable","operationId":"get_company_sector_api_v1_company__cik__sector_get","parameters":[{"name":"cik","in":"path","required":true,"schema":{"type":"string","title":"Cik"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompanySectorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/sectors/counts":{"get":{"tags":["sectors"],"summary":"Get Sectors With Counts","description":"Get all available sectors with company counts.\n\nQueries companies to count how many companies exist in each sector.\nUseful for UX to show/hide empty sectors and display availability.\n\nPerformance optimized: Uses single GROUP BY query instead of N separate queries.\n\nReturns:\n    List of sectors with code, name, and company count","operationId":"get_sectors_with_counts_api_v1_sectors_counts_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"items":{"$ref":"#/components/schemas/SectorWithCountResponse"},"type":"array","title":"Response Get Sectors With Counts Api V1 Sectors Counts Get"}}}}}}},"/api/v1/industries/counts":{"get":{"tags":["sectors"],"summary":"Get Industries With Counts","description":"Get all industries with company counts, optionally filtered by sector.\n\nQueries companies to count how many companies exist in each industry.\nUseful for UX to show/hide empty industries and display availability.\n\nArgs:\n    sector_code: Optional sector code to filter industries (e.g., \"TECH\")\n\nReturns:\n    List of industries with code, name, sector, and company count","operationId":"get_industries_with_counts_api_v1_industries_counts_get","parameters":[{"name":"sector_code","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Filter by sector code","title":"Sector Code"},"description":"Filter by sector code"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/IndustryWithCountResponse"},"title":"Response Get Industries With Counts Api V1 Industries Counts Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/feeds/sources/{ticker}":{"get":{"tags":["first-party-feeds","first-party-feeds"],"summary":"Get Feed Sources","description":"Retired (#1534): always 410 Gone.","operationId":"get_feed_sources_api_v1_feeds_sources__ticker__get","deprecated":true,"parameters":[{"name":"ticker","in":"path","required":true,"schema":{"type":"string","title":"Ticker"}}],"responses":{"410":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/feeds/items/{ticker}":{"get":{"tags":["first-party-feeds","first-party-feeds"],"summary":"Get Feed Items","description":"Retired (#1534): always 410 Gone.","operationId":"get_feed_items_api_v1_feeds_items__ticker__get","deprecated":true,"parameters":[{"name":"ticker","in":"path","required":true,"schema":{"type":"string","title":"Ticker"}}],"responses":{"410":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/feeds/recent":{"get":{"tags":["first-party-feeds","first-party-feeds"],"summary":"Get Recent Items","description":"Retired (#1534): always 410 Gone.","operationId":"get_recent_items_api_v1_feeds_recent_get","responses":{"410":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}},"deprecated":true}},"/api/v1/feeds/ir-events/{ticker}":{"get":{"tags":["first-party-feeds","first-party-feeds"],"summary":"Get Ir Events","description":"Classified IR events for a company from signals.signals.\n\nEvents grouped by (signal_id, week) to collapse duplicates.\nMateriality tiers: 1=guidance/M&A/executive/dividend, 2=partnership/deliveries, 3=product/other.","operationId":"get_ir_events_api_v1_feeds_ir_events__ticker__get","parameters":[{"name":"ticker","in":"path","required":true,"schema":{"type":"string","title":"Ticker"}},{"name":"days","in":"query","required":false,"schema":{"type":"integer","maximum":365,"minimum":1,"description":"Days to look back","default":90,"title":"Days"},"description":"Days to look back"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Max events to return","default":20,"title":"Limit"},"description":"Max events to return"},{"name":"max_materiality","in":"query","required":false,"schema":{"type":"integer","maximum":3,"minimum":1,"description":"Max materiality tier (1=critical only, 2=include partnerships, 3=all)","default":2,"title":"Max Materiality"},"description":"Max materiality tier (1=critical only, 2=include partnerships, 3=all)"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IREventsResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/signals/wall":{"get":{"tags":["signals","Signals"],"summary":"Get prioritized signal batch for the signal wall","description":"Returns a batch of ~120 prioritized signals from SEC filings, earnings releases,\n    transcripts, IR press releases, and proxy statements. Designed for the\n    showcase /signals page with 1-per-minute drip-feed display.\n\n    Cached for 15 minutes. No authentication required.","operationId":"get_signal_wall_api_v1_signals_wall_get","security":[{"HTTPBearer":[]},{"APIKeyHeader":[]}],"parameters":[{"name":"api_key","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Api Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SignalWallResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/filings/text":{"get":{"tags":["filing-text","filing-text"],"summary":"Get Filing Text","description":"Retrieve processed filing text chunks from BigQuery.\n\n**Row Types:**\n- `chunk`: 512-1024 token chunks with context prefixes (default, ~50-200 per filing)\n- `section`: Full narrative sections (~10-15 per filing)\n- `table`: Structured tables as JSON (~5-30 per filing)\n\n**Filters:**\n- Company: `ticker` or `cik`\n- Filing: `accession_number` (returns all chunks from one filing)\n- Section: `section_id` (e.g., \"footnote_revenue\")\n- Date: `from_date` and `to_date` (defaults to last 2 years if not specified)\n- Form: `form_type` (10-K, 10-Q, amendments)\n\n**Cost Optimization:**\n- Always specify `ticker` or narrow date range to reduce BigQuery scan costs\n- Default query scans ~50-500 MB (~$0.0001-0.001 per request)\n\n**Example:**\n```\nGET /api/v1/filings/text?ticker=AAPL&section_id=footnote_revenue&from_date=2024-01-01&limit=50\n```\n\nReturns: All revenue footnote chunks from Apple's filings since 2024-01-01","operationId":"get_filing_text_api_v1_filings_text_get","security":[{"HTTPBearer":[]},{"APIKeyHeader":[]}],"parameters":[{"name":"ticker","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":10},{"type":"null"}],"description":"Company ticker (e.g., AAPL)","title":"Ticker"},"description":"Company ticker (e.g., AAPL)"},{"name":"cik","in":"query","required":false,"schema":{"anyOf":[{"type":"string","pattern":"^\\d{10}$"},{"type":"null"}],"description":"10-digit CIK","title":"Cik"},"description":"10-digit CIK"},{"name":"accession_number","in":"query","required":false,"schema":{"anyOf":[{"type":"string","pattern":"^\\d{10}-\\d{2}-\\d{6}$"},{"type":"null"}],"description":"SEC accession number","title":"Accession Number"},"description":"SEC accession number"},{"name":"form_type","in":"query","required":false,"schema":{"anyOf":[{"enum":["10-K","10-Q","10-K/A","10-Q/A","8-K","DEF 14A","20-F","20-F/A","40-F","40-F/A","6-K","6-K/A"],"type":"string"},{"type":"null"}],"description":"SEC form type","title":"Form Type"},"description":"SEC form type"},{"name":"from_date","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"description":"Start date (YYYY-MM-DD)","title":"From Date"},"description":"Start date (YYYY-MM-DD)"},{"name":"to_date","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"description":"End date (YYYY-MM-DD)","title":"To Date"},"description":"End date (YYYY-MM-DD)"},{"name":"vantage_date","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"description":"As-of vantage (YYYY-MM-DD): resolve the latest filing filed ON OR BEFORE this date (point-in-time). Omit for the newest filing.","title":"Vantage Date"},"description":"As-of vantage (YYYY-MM-DD): resolve the latest filing filed ON OR BEFORE this date (point-in-time). Omit for the newest filing."},{"name":"section_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":128,"pattern":"^[a-z0-9_]+$"},{"type":"null"}],"description":"Section filter (canonical IDs + header-derived sub-section IDs from list_filings)","title":"Section Id"},"description":"Section filter (canonical IDs + header-derived sub-section IDs from list_filings)"},{"name":"fiscal_year","in":"query","required":false,"schema":{"anyOf":[{"type":"integer","maximum":2100,"minimum":2000},{"type":"null"}],"description":"Fiscal year","title":"Fiscal Year"},"description":"Fiscal year"},{"name":"fiscal_period","in":"query","required":false,"schema":{"anyOf":[{"enum":["Q1","Q2","Q3","FY"],"type":"string"},{"type":"null"}],"description":"Fiscal period","title":"Fiscal Period"},"description":"Fiscal period"},{"name":"row_type","in":"query","required":false,"schema":{"enum":["chunk","section","table"],"type":"string","description":"Content type: chunk, section, or table","default":"chunk","title":"Row Type"},"description":"Content type: chunk, section, or table"},{"name":"since","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Filter by extracted_at >= timestamp (ISO 8601) for incremental sync","title":"Since"},"description":"Filter by extracted_at >= timestamp (ISO 8601) for incremental sync"},{"name":"keyword","in":"query","required":false,"schema":{"anyOf":[{"type":"string","minLength":2,"maxLength":200},{"type":"null"}],"description":"Keyword filter — returns only chunks containing this text (case-insensitive)","title":"Keyword"},"description":"Keyword filter — returns only chunks containing this text (case-insensitive)"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":1000,"minimum":1,"description":"Max results (1-1000)","default":100,"title":"Limit"},"description":"Max results (1-1000)"},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Result offset for pagination","default":0,"title":"Offset"},"description":"Result offset for pagination"},{"name":"include_delisted","in":"query","required":false,"schema":{"type":"boolean","description":"Include delisted/acquired companies. Default False returns 410 Gone for delisted tickers.","default":false,"title":"Include Delisted"},"description":"Include delisted/acquired companies. Default False returns 410 Gone for delisted tickers."},{"name":"api_key","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Api Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FilingTextResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/companies/{ticker}/filings/text/latest":{"get":{"tags":["filing-text","filing-text"],"summary":"Get Latest Filing Text","description":"Get text from the most recent filing for a company.\n\n**Example:**\n```\nGET /api/v1/companies/AAPL/filings/text/latest?form_type=10-K\n```\n\nReturns: All chunks from Apple's latest 10-K","operationId":"get_latest_filing_text_api_v1_companies__ticker__filings_text_latest_get","security":[{"HTTPBearer":[]},{"APIKeyHeader":[]}],"parameters":[{"name":"ticker","in":"path","required":true,"schema":{"type":"string","title":"Ticker"}},{"name":"form_type","in":"query","required":false,"schema":{"anyOf":[{"enum":["10-K","10-Q","10-K/A","10-Q/A","8-K","DEF 14A","20-F","20-F/A","40-F","40-F/A","6-K","6-K/A"],"type":"string"},{"type":"null"}],"description":"SEC form type filter","title":"Form Type"},"description":"SEC form type filter"},{"name":"row_type","in":"query","required":false,"schema":{"enum":["chunk","section","table"],"type":"string","description":"Content type","default":"chunk","title":"Row Type"},"description":"Content type"},{"name":"api_key","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Api Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FilingTextResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/filings/sections/summary":{"get":{"tags":["filing-text","filing-text"],"summary":"Get Filing Sections Summary","description":"Get section-level metadata for a company's filings WITHOUT full content.\n\nReturns a filing tree with per-section metadata (word count, table count, preview).\nDesigned for MCP tools and AI agents that need to discover available data\nbefore loading full content.\n\n**Example:**\n```\nGET /api/v1/filings/sections/summary?ticker=NVDA&years=2\n```\n\nReturns: List of filings with section TOC (word counts, table counts, previews).\n\n**Delisted companies:** returns HTTP 410 Gone when `ticker` resolves to a\ndelisted company and `include_delisted=false` (default). Response body\nnames the delisting date and suggests either `include_delisted=true` or\ndirect CIK lookup. Mirrors the /filings/text pattern.","operationId":"get_filing_sections_summary_api_v1_filings_sections_summary_get","security":[{"HTTPBearer":[]},{"APIKeyHeader":[]}],"parameters":[{"name":"ticker","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":10},{"type":"null"}],"description":"Company ticker (e.g., AAPL). Either ticker or cik required.","title":"Ticker"},"description":"Company ticker (e.g., AAPL). Either ticker or cik required."},{"name":"cik","in":"query","required":false,"schema":{"anyOf":[{"type":"string","pattern":"^\\d{10}$"},{"type":"null"}],"description":"10-digit SEC CIK as alternative to ticker. Use for delisted/acquired companies where the ticker is no longer active. Either ticker or cik required.","title":"Cik"},"description":"10-digit SEC CIK as alternative to ticker. Use for delisted/acquired companies where the ticker is no longer active. Either ticker or cik required."},{"name":"form_type","in":"query","required":false,"schema":{"anyOf":[{"enum":["10-K","10-Q","10-K/A","10-Q/A","8-K","DEF 14A","20-F","20-F/A","40-F","40-F/A","6-K","6-K/A"],"type":"string"},{"type":"null"}],"description":"Filter by form type","title":"Form Type"},"description":"Filter by form type"},{"name":"form_subtype","in":"query","required":false,"schema":{"anyOf":[{"enum":["8-K-earnings","8-K-event","8-K-transcript","8-K-other"],"type":"string"},{"type":"null"}],"description":"Filter by 8-K sub-type (derived from section inventory). When set, implicitly narrows to form_type='8-K' regardless of the form_type param. B1 Sub-3 (2026-04-23): added to let MCP C1 router replace section-inventory inference with a direct filter.","title":"Form Subtype"},"description":"Filter by 8-K sub-type (derived from section inventory). When set, implicitly narrows to form_type='8-K' regardless of the form_type param. B1 Sub-3 (2026-04-23): added to let MCP C1 router replace section-inventory inference with a direct filter."},{"name":"fiscal_year","in":"query","required":false,"schema":{"anyOf":[{"type":"integer","maximum":2100,"minimum":2000},{"type":"null"}],"description":"Filter by fiscal year","title":"Fiscal Year"},"description":"Filter by fiscal year"},{"name":"fiscal_period","in":"query","required":false,"schema":{"anyOf":[{"enum":["Q1","Q2","Q3","FY"],"type":"string"},{"type":"null"}],"description":"Filter by fiscal period","title":"Fiscal Period"},"description":"Filter by fiscal period"},{"name":"vantage_date","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"description":"As-of vantage (YYYY-MM-DD): only list filings filed ON OR BEFORE this date (point-in-time). Omit to list the most recent filings. For vantages older than the `years` window, pass a larger `years`.","title":"Vantage Date"},"description":"As-of vantage (YYYY-MM-DD): only list filings filed ON OR BEFORE this date (point-in-time). Omit to list the most recent filings. For vantages older than the `years` window, pass a larger `years`."},{"name":"years","in":"query","required":false,"schema":{"type":"integer","maximum":10,"minimum":1,"description":"Years of history to include","default":3,"title":"Years"},"description":"Years of history to include"},{"name":"accession_number","in":"query","required":false,"schema":{"anyOf":[{"type":"string","pattern":"^\\d{10}-\\d{2}-\\d{6}$"},{"type":"null"}],"description":"Narrow to a single filing's section TOC. Required when preview_chars > 0 (content_raw scan cost gate). Phase AD outline-mode use case.","title":"Accession Number"},"description":"Narrow to a single filing's section TOC. Required when preview_chars > 0 (content_raw scan cost gate). Phase AD outline-mode use case."},{"name":"preview_chars","in":"query","required":false,"schema":{"type":"integer","maximum":200,"minimum":0,"description":"When > 0, populate `sections[].preview` with the first N chars of the section's first chunk (content_raw). Default 0 omits previews (keeps scan cheap — content_raw read is the dominant cost driver). Requires accession_number to bound scan to one filing. Phase AD outline-mode.","default":0,"title":"Preview Chars"},"description":"When > 0, populate `sections[].preview` with the first N chars of the section's first chunk (content_raw). Default 0 omits previews (keeps scan cheap — content_raw read is the dominant cost driver). Requires accession_number to bound scan to one filing. Phase AD outline-mode."},{"name":"include_delisted","in":"query","required":false,"schema":{"type":"boolean","description":"Include delisted/acquired companies. Default False returns 410 Gone for delisted tickers with an include_delisted=true hint.","default":false,"title":"Include Delisted"},"description":"Include delisted/acquired companies. Default False returns 410 Gone for delisted tickers with an include_delisted=true hint."},{"name":"include_unextracted","in":"query","required":false,"schema":{"type":"boolean","description":"False skips the sec_filings registry reads that build `unextracted_filings` (the covered-but-unextracted probe and the window cross-check, about 250 MiB of BigQuery per call for a multi-year window) and returns that list empty. For callers that read only `filings`: the MCP worker's sibling-summary lookups discard it (#3074 r87). `filings` is identical either way.","default":true,"title":"Include Unextracted"},"description":"False skips the sec_filings registry reads that build `unextracted_filings` (the covered-but-unextracted probe and the window cross-check, about 250 MiB of BigQuery per call for a multi-year window) and returns that list empty. For callers that read only `filings`: the MCP worker's sibling-summary lookups discard it (#3074 r87). `filings` is identical either way."},{"name":"api_key","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Api Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FilingListResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/filings/sections/keyword-presence":{"get":{"tags":["filing-text","filing-text"],"summary":"Which of one filing's sections contain a keyword (cross-section check)","description":"#582: thin cross-section existence probe over a SINGLE filing. Returns the servable sections whose text contains the keyword (same stemming as the per-section keyword filter) plus the filing's full servable-section list, so a caller can render a decisive 'in sibling X' / 'in NONE of these sections' verdict.","operationId":"get_keyword_presence_api_v1_filings_sections_keyword_presence_get","security":[{"HTTPBearer":[]},{"APIKeyHeader":[]}],"parameters":[{"name":"accession","in":"query","required":true,"schema":{"type":"string","pattern":"^\\d{10}-\\d{2}-\\d{6}$","description":"SEC accession number of the filing to scan.","title":"Accession"},"description":"SEC accession number of the filing to scan."},{"name":"keyword","in":"query","required":true,"schema":{"type":"string","minLength":1,"maxLength":200,"description":"Term to check for (stemmed).","title":"Keyword"},"description":"Term to check for (stemmed)."},{"name":"ticker","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":10},{"type":"null"}],"description":"Company ticker (either ticker or cik required).","title":"Ticker"},"description":"Company ticker (either ticker or cik required)."},{"name":"cik","in":"query","required":false,"schema":{"anyOf":[{"type":"string","pattern":"^\\d{10}$"},{"type":"null"}],"description":"10-digit CIK (either ticker or cik required).","title":"Cik"},"description":"10-digit CIK (either ticker or cik required)."},{"name":"api_key","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Api Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/KeywordPresenceResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/filings/{accession_number}/keyword-search":{"get":{"tags":["filing-text","filing-text"],"summary":"Search for a keyword within a filing's sections","description":"Find which sections and chunks of a filing contain a specific term. Returns section IDs and chunk offsets for seamless drill-in via get_filing_section.","operationId":"keyword_search_single_api_v1_filings__accession_number__keyword_search_get","deprecated":true,"security":[{"HTTPBearer":[]},{"APIKeyHeader":[]}],"parameters":[{"name":"accession_number","in":"path","required":true,"schema":{"type":"string","title":"Accession Number"}},{"name":"keyword","in":"query","required":true,"schema":{"type":"string","minLength":1,"maxLength":200,"description":"Search term (case-insensitive)","title":"Keyword"},"description":"Search term (case-insensitive)"},{"name":"row_type","in":"query","required":false,"schema":{"enum":["chunk","section","table"],"type":"string","description":"Content type to search","default":"chunk","title":"Row Type"},"description":"Content type to search"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Max matching chunks","default":50,"title":"Limit"},"description":"Max matching chunks"},{"name":"api_key","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Api Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/KeywordSearchResult"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/filings/keyword-search":{"post":{"tags":["filing-text","filing-text"],"summary":"Search for a keyword across multiple filings","description":"Batch keyword search across up to 10 filings. Returns matching sections and chunk offsets for each filing. Used by MCP tools to enrich EFTS filing-level results with section-level pointers.","operationId":"keyword_search_batch_api_v1_filings_keyword_search_post","security":[{"HTTPBearer":[]},{"APIKeyHeader":[]}],"parameters":[{"name":"api_key","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Api Key"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BatchKeywordSearchRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BatchKeywordSearchResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/filings/fulltext-search":{"post":{"tags":["filing-text","filing-text"],"summary":"Company-scoped full-text search over extracted filing sections","description":"MD-native fallback for search_sec_filings when EDGAR EFTS is unavailable: searches MetricDuck's own extracted text (cik-pruned keyword search; a compound term such as 5.750% or R&D must appear as written) for a phrase and returns matching filings with section-level drill-in pointers.","operationId":"company_fulltext_search_api_v1_filings_fulltext_search_post","security":[{"HTTPBearer":[]},{"APIKeyHeader":[]}],"parameters":[{"name":"api_key","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Api Key"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompanyFullTextSearchRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompanyFullTextSearchResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/companies/{ticker}/transcript-signals":{"get":{"tags":["filing-text","filing-text","transcript"],"summary":"Get latest earnings call transcript signals for a company","description":"Most-recent earnings-call's signals + coverage state, accession-aligned.\n\nCoverage (`transcript_processing`) drives the canonical `accession_number`;\nsignals (`transcript_signals`) are looked up for that specific accession. No\nsilent fall-back to an older call when the latest one lacks a signals row —\nreturns 200 with `signals: {}` (plus Q&A aggregates from `transcript_qa_exchanges`\nwhen available) so consumers render the empty state with correct attribution.\n\nQ&A aggregates (`qa_analyst_concern_retained_count`, `qa_forward_commit_count`)\nare merged into `signals` from query-time aggregation. Returns 404 if\nticker is unknown.","operationId":"get_transcript_signals_api_v1_companies__ticker__transcript_signals_get","security":[{"HTTPBearer":[]},{"APIKeyHeader":[]}],"parameters":[{"name":"ticker","in":"path","required":true,"schema":{"type":"string","title":"Ticker"}},{"name":"api_key","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Api Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/companies/{ticker}/transcript-trajectory":{"get":{"tags":["filing-text","filing-text","transcript"],"summary":"Per-quarter earnings-call transcript signal trajectory","description":"Route wrapper — see `_get_transcript_trajectory_impl` for the query logic.\n\nThin FastAPI surface (framework-injected params). The free-standing impl is\nalso called by the overview-page BFF (`overview_page_service.fetch_coverage`)\nvia asyncio.to_thread — mirrors the get_transcript_signals → _impl split so\nbundle callers don't pass through the FastAPI Depends surface.","operationId":"get_transcript_trajectory_api_v1_companies__ticker__transcript_trajectory_get","security":[{"HTTPBearer":[]},{"APIKeyHeader":[]}],"parameters":[{"name":"ticker","in":"path","required":true,"schema":{"type":"string","title":"Ticker"}},{"name":"n","in":"query","required":false,"schema":{"type":"integer","maximum":8,"minimum":1,"description":"Most-recent quarters to return","default":4,"title":"N"},"description":"Most-recent quarters to return"},{"name":"dimensions","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"CSV subset of {capital_allocation, competitive, customer_cohort, forward_commits, guidance, hedges, kpi, macro, priorities, qa, revdecomp, scale_claims, scenarios}. Omit for all dimensions.","title":"Dimensions"},"description":"CSV subset of {capital_allocation, competitive, customer_cohort, forward_commits, guidance, hedges, kpi, macro, priorities, qa, revdecomp, scale_claims, scenarios}. Omit for all dimensions."},{"name":"include_empty","in":"query","required":false,"schema":{"type":"boolean","description":"Include earnings events with no completed transcript as coverage_status=NO_TRANSCRIPT rows with null signals.","default":true,"title":"Include Empty"},"description":"Include earnings events with no completed transcript as coverage_status=NO_TRANSCRIPT rows with null signals."},{"name":"vantage_date","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"description":"As-of vantage (YYYY-MM-DD): only include earnings events filed ON OR BEFORE this date, with the N-quarter window anchored to this date (not today) — for point-in-time / 'as of <date>' / historical questions. Omit for the most recent quarters.","title":"Vantage Date"},"description":"As-of vantage (YYYY-MM-DD): only include earnings events filed ON OR BEFORE this date, with the N-quarter window anchored to this date (not today) — for point-in-time / 'as of <date>' / historical questions. Omit for the most recent quarters."},{"name":"api_key","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Api Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/ir-documents":{"get":{"tags":["ir-documents","ir-documents"],"summary":"Retrieve IR earnings-presentation-deck text (forward guidance / KPIs not in SEC filings)","description":"Serve the IR earnings PRESENTATION DECK (slide-deck) text that lives ONLY in the company's investor-relations deck — forward guidance, operational KPIs, segment outlook — and is NOT in the SEC 8-K/10-Q release text or XBRL. Resolve by ticker or cik; narrow with fiscal_year/fiscal_period; pass `query` to return only the slide pages whose text matches (page-cited).","operationId":"get_ir_documents_api_v1_ir_documents_get","security":[{"HTTPBearer":[]},{"APIKeyHeader":[]}],"parameters":[{"name":"ticker","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":10},{"type":"null"}],"description":"Company ticker (e.g., OXY). Either ticker or cik required.","title":"Ticker"},"description":"Company ticker (e.g., OXY). Either ticker or cik required."},{"name":"cik","in":"query","required":false,"schema":{"anyOf":[{"type":"string","pattern":"^\\d{10}$"},{"type":"null"}],"description":"10-digit CIK as an alternative to ticker.","title":"Cik"},"description":"10-digit CIK as an alternative to ticker."},{"name":"fiscal_year","in":"query","required":false,"schema":{"anyOf":[{"type":"integer","maximum":2100,"minimum":2000},{"type":"null"}],"description":"Fiscal year of the deck (e.g., 2024).","title":"Fiscal Year"},"description":"Fiscal year of the deck (e.g., 2024)."},{"name":"fiscal_period","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":8},{"type":"null"}],"description":"Fiscal period: 'Q3' (with fiscal_year) or combined '2024Q3'. Optional.","title":"Fiscal Period"},"description":"Fiscal period: 'Q3' (with fiscal_year) or combined '2024Q3'. Optional."},{"name":"query","in":"query","required":false,"schema":{"anyOf":[{"type":"string","minLength":2,"maxLength":200},{"type":"null"}],"description":"Keyword filter over slide text — returns only matching pages (whole-word AND, case-insensitive).","title":"Query"},"description":"Keyword filter over slide text — returns only matching pages (whole-word AND, case-insensitive)."},{"name":"coverage_only","in":"query","required":false,"schema":{"type":"boolean","description":"Return only the deck COUNT (total_decks), skipping the slide-text read. For a 'has decks?' coverage check — scans the small ir_documents catalog (~35 MB) instead of the ir_document_text corpus. Used by the web factsheet's coverage line.","default":false,"title":"Coverage Only"},"description":"Return only the deck COUNT (total_decks), skipping the slide-text read. For a 'has decks?' coverage check — scans the small ir_documents catalog (~35 MB) instead of the ir_document_text corpus. Used by the web factsheet's coverage line."},{"name":"list_only","in":"query","required":false,"schema":{"type":"boolean","description":"Return the metadata-only deck INDEX (title/date/url/gcs_uri per deck, NO slide text) for a browsable archive — up to 500 decks + the true total. Scans the ir_documents catalog only (~35 MB), not the text corpus. Mutually exclusive with coverage_only and query.","default":false,"title":"List Only"},"description":"Return the metadata-only deck INDEX (title/date/url/gcs_uri per deck, NO slide text) for a browsable archive — up to 500 decks + the true total. Scans the ir_documents catalog only (~35 MB), not the text corpus. Mutually exclusive with coverage_only and query."},{"name":"api_key","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Api Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IrDocumentsResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/newsletter/unsubscribe":{"get":{"tags":["newsletter"],"summary":"Unsubscribe from newsletter","description":"One-click unsubscribe endpoint (CAN-SPAM compliance)","operationId":"unsubscribe_from_newsletter_api_v1_newsletter_unsubscribe_get","parameters":[{"name":"token","in":"query","required":true,"schema":{"type":"string","title":"Token"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NewsletterUnsubscribeResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/email/unsubscribe":{"get":{"tags":["email"],"summary":"Unsubscribe Page","operationId":"unsubscribe_page_api_v1_email_unsubscribe_get","parameters":[{"name":"e","in":"query","required":false,"schema":{"type":"string","default":"","title":"E"}},{"name":"t","in":"query","required":false,"schema":{"type":"string","default":"","title":"T"}}],"responses":{"200":{"description":"Successful Response","content":{"text/html":{"schema":{"type":"string"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"post":{"tags":["email"],"summary":"Unsubscribe","operationId":"unsubscribe_api_v1_email_unsubscribe_post","parameters":[{"name":"e","in":"query","required":false,"schema":{"type":"string","default":"","title":"E"}},{"name":"t","in":"query","required":false,"schema":{"type":"string","default":"","title":"T"}}],"responses":{"200":{"description":"Successful Response","content":{"text/html":{"schema":{"type":"string"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/email/resend-webhook":{"post":{"tags":["email"],"summary":"Resend Webhook","operationId":"resend_webhook_api_v1_email_resend_webhook_post","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/api/v1/companies/{ticker}/cash-flow-quality":{"get":{"tags":["cash-flow-quality","Cash Flow Quality"],"summary":"Get factual cash-flow-quality metrics","description":"Returns computed cash-flow-quality metrics per period: FCF history, capex\n    normalization, 8Q volatility, OCF/FCF reconciliation, growth, balance-sheet\n    adjustments. Factual data only — no WACC, no intrinsic-value estimates.\n\n    **Sister endpoint:** `/companies/{ticker}/cash-flow` returns raw statement\n    line items. This endpoint returns the computed metrics derived from them.\n\n    **Data Source:** SEC EDGAR (10-K, 10-Q filings) via `filing_metrics` BQ table","operationId":"get_cash_flow_quality_api_v1_companies__ticker__cash_flow_quality_get","deprecated":true,"security":[{"HTTPBearer":[]},{"APIKeyHeader":[]}],"parameters":[{"name":"ticker","in":"path","required":true,"schema":{"type":"string","description":"Company ticker (e.g., 'AAPL')","title":"Ticker"},"description":"Company ticker (e.g., 'AAPL')"},{"name":"period","in":"query","required":false,"schema":{"type":"string","pattern":"^(quarterly|annual|ttm)$","description":"'quarterly', 'annual', or 'ttm'","default":"quarterly","title":"Period"},"description":"'quarterly', 'annual', or 'ttm'"},{"name":"years","in":"query","required":false,"schema":{"type":"integer","maximum":10,"minimum":1,"description":"Years of history (1-10)","default":5,"title":"Years"},"description":"Years of history (1-10)"},{"name":"api_key","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Api Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/CashFlowQualityItem"},"title":"Response 200 Get Cash Flow Quality Api V1 Companies  Ticker  Cash Flow Quality Get"}}}},"400":{"description":"Bad Request — invalid ticker / period / years"},"404":{"description":"Ticker not found or no data for requested period"},"429":{"description":"Rate limit exceeded"},"500":{"description":"Server error"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/companies/{ticker}/overview/comprehensive":{"get":{"tags":["comprehensive-overview"],"summary":"Get Comprehensive Overview","description":"Get comprehensive company overview with rich quantitative structure.\n\n`executive_officers` is always null here: the web never renders it, and the read\ncosts ~86 MiB of BigQuery per miss. The overview-page BFF (the MCP\nget_company_overview path) reads it beside this call and fills it in.\n\nDesigned for both UI and AI/MCP consumption with:\n- Multi-period trends (8Q analysis with volatility, medians)\n- Peer comparison (sector medians, percentiles)\n- Qualitative context (business description, industry classification)\n- Objective flags (no subjective labels)\n- Data freshness transparency\n\nPerfect for:\n- AI research workflows (contextual reasoning about company quality)\n- UI overview dashboards (inline peer comparisons)\n- Investment analysis (comprehensive fundamentals snapshot)","operationId":"get_comprehensive_overview_api_v1_companies__ticker__overview_comprehensive_get","security":[{"HTTPBearer":[]},{"APIKeyHeader":[]}],"parameters":[{"name":"ticker","in":"path","required":true,"schema":{"type":"string","description":"Company ticker symbol","title":"Ticker"},"description":"Company ticker symbol"},{"name":"api_key","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Api Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ComprehensiveOverviewResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/filing-intelligence/recent":{"get":{"tags":["filing-intelligence","Filing Intelligence"],"summary":"Get recent filing intelligence across all companies","description":"Retrieve recent filing intelligence for dashboard feeds.\n\n    Returns simplified summaries of the most recent 10-Q/10-K filings\n    across all tracked companies, ranked by company importance.\n\n    This endpoint is designed for dashboard cards showing latest quarterly filings.","operationId":"get_recent_filing_intelligence_api_v1_filing_intelligence_recent_get","security":[{"HTTPBearer":[]},{"APIKeyHeader":[]}],"parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":50,"minimum":1,"description":"Maximum number of filings to return","default":10,"title":"Limit"},"description":"Maximum number of filings to return"},{"name":"days_lookback","in":"query","required":false,"schema":{"type":"integer","maximum":90,"minimum":1,"description":"Number of days to look back for filings","default":14,"title":"Days Lookback"},"description":"Number of days to look back for filings"},{"name":"api_key","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Api Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FilingIntelligenceSummaryListResponse"}}}},"500":{"description":"Database error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FilingIntelligenceError"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/filing-intelligence/screen":{"post":{"tags":["filing-intelligence","Filing Intelligence"],"summary":"Screen companies by filing intelligence signals","description":"Cross-company screening by qualitative signals extracted from SEC filings.\n\n    Filters by signals a model extracted from each filing (management tone, material\n    weakness, SBC levels, risks it read as new) — NOT by LLM-generated scores.\n\n    Available signals:\n    - tone_cautious: management tone is cautious or defensive\n    - tone_shifted: tone shifted more cautious vs prior filing\n    - material_weakness: material weakness in internal controls detected\n    - has_new_risks: a model read ≥1 risk as new in this filing (not a text diff vs the prior filing)","operationId":"screen_filing_signals_api_v1_filing_intelligence_screen_post","security":[{"HTTPBearer":[]},{"APIKeyHeader":[]}],"parameters":[{"name":"api_key","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Api Key"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SignalScreenRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SignalScreenResponse"}}}},"400":{"description":"Invalid signal name","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FilingIntelligenceError"}}}},"500":{"description":"Database error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FilingIntelligenceError"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/filings/recent":{"get":{"tags":["filings","Filings"],"summary":"Recent filings across all tracked companies","description":"Single-call discovery for filings landed since a timestamp, optionally filtered by form type, 8-K sub-type, or portfolio tickers. Newest filing date first. A page holds at most `limit` rows: the `X-Has-More` response header is `1` when more filings match, and `X-Next-Offset` then gives the `offset` of the next page (absent past offset 1000: narrow the query instead). Backs the mcp-worker `list_recent_filings` tool — used by Routines and any agent doing event-driven portfolio monitoring.","operationId":"list_recent_filings_api_v1_filings_recent_get","parameters":[{"name":"since","in":"query","required":true,"schema":{"type":"string","format":"date","description":"Filing date floor (inclusive). YYYY-MM-DD.","title":"Since"},"description":"Filing date floor (inclusive). YYYY-MM-DD."},{"name":"form_types","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}],"description":"Filter by SEC form type. Repeat the param for multiple values, e.g., ?form_types=8-K&form_types=10-Q.","title":"Form Types"},"description":"Filter by SEC form type. Repeat the param for multiple values, e.g., ?form_types=8-K&form_types=10-Q."},{"name":"form_subtypes","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}],"description":"Filter by 8-K sub-type. Allowed: '8-K-earnings', '8-K-transcript', '8-K-event', '8-K-other'. Other values are silently ignored.","title":"Form Subtypes"},"description":"Filter by 8-K sub-type. Allowed: '8-K-earnings', '8-K-transcript', '8-K-event', '8-K-other'. Other values are silently ignored."},{"name":"tickers","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}],"description":"Optional portfolio filter; max 50 tickers.","title":"Tickers"},"description":"Optional portfolio filter; max 50 tickers."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Max rows (default 50, max 100).","default":50,"title":"Limit"},"description":"Max rows (default 50, max 100)."},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","maximum":1000,"minimum":0,"description":"Rows to skip, for the next page (max 1000). Use the previous page's `X-Next-Offset` header. Pages share one deterministic order, but each page is read (and cached for up to 30 minutes) on its own, so a filing that lands between calls can shift rows across pages: dedupe by accession, and for a complete sweep narrow the query until `X-Has-More` is 0.","default":0,"title":"Offset"},"description":"Rows to skip, for the next page (max 1000). Use the previous page's `X-Next-Offset` header. Pages share one deterministic order, but each page is read (and cached for up to 30 minutes) on its own, so a filing that lands between calls can shift rows across pages: dedupe by accession, and for a complete sweep narrow the query until `X-Has-More` is 0."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/RecentFilingItem"},"title":"Response List Recent Filings Api V1 Filings Recent Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/companies/{ticker}/overview-page":{"get":{"tags":["bff","BFF (Backend for Frontend)"],"summary":"Get aggregated overview page data (BFF endpoint)","description":"**Backend for Frontend (BFF) endpoint for company overview page.**\n\n    Aggregates company overview + earnings insights into a single response.\n    Caching is handled by HTTP cache middleware (48h TTL).","operationId":"get_overview_page_api_v1_companies__ticker__overview_page_get","security":[{"HTTPBearer":[]},{"APIKeyHeader":[]}],"parameters":[{"name":"ticker","in":"path","required":true,"schema":{"type":"string","description":"Company ticker symbol (e.g., AAPL, MSFT)","title":"Ticker"},"description":"Company ticker symbol (e.g., AAPL, MSFT)"},{"name":"api_key","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Api Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OverviewPageResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/data/metrics":{"get":{"tags":["data-api","Data API"],"summary":"Query financial metrics","description":"Flexible endpoint for querying financial metrics across multiple companies.\n\n    **Features:**\n    - Query up to 200 tickers, 70+ curated metrics\n    - Historical data up to 10 years\n    - Support for TTM, quarterly, and annual periods\n    - Optional dimensions for trend/statistical analysis (Q.TREND8, Q.MED8, TTM.YOY, etc.)\n    - Price basis: `price=current` recomputes valuation metrics at the latest end-of-day close\n    - Credit-based billing: `dry_run=true` to preview cost before querying\n\n    **Credit Formula:** `tickers × metrics × periods_factor`\n    - TTM/Annual: periods_factor = years\n    - Quarterly: periods_factor = years × 4\n    - Each dimension adds 1 to periods_factor\n\n    **Example:**\n    ```\n    GET /api/v1/data/metrics?tickers=AAPL,MSFT,GOOGL&metrics=revenues,roic,roe&period=ttm&years=2\n    GET /api/v1/data/metrics?tickers=AAPL&metrics=roic&period=quarterly&dimensions=Q.TREND8,Q.MED8\n    GET /api/v1/data/metrics?tickers=AAPL&metrics=pe_ratio,ev_ebitda&period=ttm&price=current&dry_run=true\n    ```","operationId":"get_metrics_api_v1_data_metrics_get","security":[{"HTTPBearer":[]},{"APIKeyHeader":[]}],"parameters":[{"name":"tickers","in":"query","required":true,"schema":{"type":"string","description":"Comma-separated stock tickers (e.g., AAPL,MSFT,GOOGL)","title":"Tickers"},"description":"Comma-separated stock tickers (e.g., AAPL,MSFT,GOOGL)","example":"AAPL,MSFT,GOOGL"},{"name":"metrics","in":"query","required":true,"schema":{"type":"string","description":"Comma-separated metric IDs (e.g., revenues,roic,roe)","title":"Metrics"},"description":"Comma-separated metric IDs (e.g., revenues,roic,roe)","example":"revenues,roic,roe,gross_margin"},{"name":"period","in":"query","required":false,"schema":{"type":"string","pattern":"^(ttm|quarterly|annual)$","description":"Period type: ttm (trailing twelve months), quarterly, or annual","default":"ttm","title":"Period"},"description":"Period type: ttm (trailing twelve months), quarterly, or annual"},{"name":"years","in":"query","required":false,"schema":{"type":"integer","maximum":10,"minimum":1,"description":"Years of historical data (1-10)","default":2,"title":"Years"},"description":"Years of historical data (1-10)"},{"name":"dimensions","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Comma-separated compound period types for trend/statistical analysis (e.g., Q.TREND8,Q.MED8,TTM.YOY)","title":"Dimensions"},"description":"Comma-separated compound period types for trend/statistical analysis (e.g., Q.TREND8,Q.MED8,TTM.YOY)","example":"Q.TREND8,Q.MED8"},{"name":"price","in":"query","required":false,"schema":{"type":"string","pattern":"^(historical|current)$","description":"Price basis for valuation metrics: historical (period-end) or current (latest end-of-day close)","default":"historical","title":"Price"},"description":"Price basis for valuation metrics: historical (period-end) or current (latest end-of-day close)"},{"name":"dry_run","in":"query","required":false,"schema":{"type":"boolean","description":"If true, return credit cost estimate without querying data","default":false,"title":"Dry Run"},"description":"If true, return credit cost estimate without querying data"},{"name":"api_key","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Api Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DataAPIResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/data/metrics/catalog":{"get":{"tags":["data-api","Data API"],"summary":"List available metrics and dimensions","description":"Returns the list of all available metrics organized by category, plus allowed dimensions for trend/statistical analysis.","operationId":"get_metrics_catalog_api_v1_data_metrics_catalog_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","title":"Response Get Metrics Catalog Api V1 Data Metrics Catalog Get"}}}}}}},"/api/v1/internal/cache/invalidate":{"post":{"tags":["internal"],"summary":"Invalidate a company's cached api responses (bump its cache generation)","description":"Bumps the per-company cache generation so freshly-written data is served immediately. Auth via the shared revalidate secret.","operationId":"invalidate_cache_api_v1_internal_cache_invalidate_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CacheInvalidateRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CacheInvalidateResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/feedback":{"post":{"tags":["feedback"],"summary":"Send Feedback","operationId":"send_feedback_api_v1_feedback_post","security":[{"HTTPBearer":[]},{"APIKeyHeader":[]}],"parameters":[{"name":"api_key","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Api Key"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FeedbackRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":{"type":"string"},"title":"Response Send Feedback Api V1 Feedback Post"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/":{"get":{"summary":"Root","description":"Root endpoint with API information","operationId":"root__get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}}},"components":{"schemas":{"ActualItem":{"properties":{"reported_on":{"type":"string","title":"Reported On"},"fiscal_period":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Fiscal Period"},"source_event_type":{"type":"string","title":"Source Event Type"},"signal_id":{"type":"string","title":"Signal Id"},"value":{"title":"Value"},"short_quote":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Short Quote"},"source_id":{"type":"string","title":"Source Id"},"locator":{"additionalProperties":true,"type":"object","title":"Locator"}},"type":"object","required":["reported_on","source_event_type","signal_id","value","source_id"],"title":"ActualItem"},"ApiKeyCreate":{"properties":{"name":{"type":"string","maxLength":50,"minLength":1,"pattern":"^[a-zA-Z0-9\\s\\-_]+$","title":"Name","description":"API key name (alphanumeric, spaces, hyphens, underscores only)"}},"type":"object","required":["name"],"title":"ApiKeyCreate","description":"API key creation request"},"ApiKeyListItem":{"properties":{"id":{"type":"string","title":"Id"},"name":{"type":"string","title":"Name"},"key_prefix":{"type":"string","title":"Key Prefix"},"status":{"type":"string","title":"Status"},"last_used_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Last Used At"},"usage_count":{"type":"integer","title":"Usage Count"},"created_at":{"type":"string","title":"Created At"}},"type":"object","required":["id","name","key_prefix","status","last_used_at","usage_count","created_at"],"title":"ApiKeyListItem","description":"API key list item - without the actual key"},"ApiKeyResponse":{"properties":{"id":{"type":"string","title":"Id"},"key":{"type":"string","title":"Key"},"name":{"type":"string","title":"Name"},"key_prefix":{"type":"string","title":"Key Prefix"},"created_at":{"type":"string","title":"Created At"}},"type":"object","required":["id","key","name","key_prefix","created_at"],"title":"ApiKeyResponse","description":"API key response - only shown once during creation"},"ApiUsageLogResponse":{"properties":{"id":{"type":"string","title":"Id"},"endpoint":{"type":"string","title":"Endpoint"},"method":{"type":"string","title":"Method"},"status_code":{"type":"integer","title":"Status Code"},"response_time_ms":{"type":"integer","title":"Response Time Ms"},"ip_address":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Ip Address"},"created_at":{"type":"string","title":"Created At"}},"type":"object","required":["id","endpoint","method","status_code","response_time_ms","ip_address","created_at"],"title":"ApiUsageLogResponse","description":"API usage log entry"},"AxisPriority":{"properties":{"axis":{"type":"string","title":"Axis","description":"Axis QName"},"axis_label":{"type":"string","title":"Axis Label","description":"Human-readable axis label"},"priority":{"type":"integer","title":"Priority","description":"1=primary, lower=more important"},"role":{"type":"string","title":"Role","description":"primary|secondary|alternate_primary|filter"},"member_count":{"type":"integer","title":"Member Count","description":"Number of members in this axis"}},"type":"object","required":["axis","axis_label","priority","role","member_count"],"title":"AxisPriority","description":"Axis priority for hierarchy reconstruction."},"AxisTree":{"properties":{"domain":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Domain","description":"Root domain"},"members":{"items":{"$ref":"#/components/schemas/MemberNode"},"type":"array","title":"Members","description":"All members sorted by order","default":[]}},"type":"object","title":"AxisTree","description":"Complete member tree for an axis."},"BalanceSheetAnalysis":{"properties":{"total_debt_mrq":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Total Debt Mrq"},"cash_and_investments_mrq":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Cash And Investments Mrq"},"unmapped_debt_mrq":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Unmapped Debt Mrq"},"total_equity_mrq":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Total Equity Mrq"},"total_equity_ttm":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Total Equity Ttm"},"net_cash":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Net Cash"},"is_net_cash_positive":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Is Net Cash Positive"},"debt_to_equity_mrq":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Debt To Equity Mrq"},"debt_to_assets_mrq":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Debt To Assets Mrq"},"interest_coverage_ttm":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Interest Coverage Ttm"},"net_debt_to_ebitda_ttm":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Net Debt To Ebitda Ttm"}},"type":"object","title":"BalanceSheetAnalysis","description":"Balance sheet strength with leverage analysis"},"BalanceSheetItem":{"properties":{"primary_document":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Primary Document"},"cik":{"type":"string","title":"Cik"},"accession_number":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Accession Number"},"date":{"type":"string","title":"Date"},"symbol":{"type":"string","title":"Symbol"},"filing_date":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Filing Date"},"fiscal_year":{"type":"integer","title":"Fiscal Year"},"period":{"type":"string","title":"Period"},"industry":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Industry"},"original_accession_number":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Original Accession Number"},"revised_after_vantage":{"type":"boolean","title":"Revised After Vantage","default":false},"source_attribution":{"anyOf":[{"additionalProperties":{"items":{"type":"string"},"type":"array"},"type":"object"},{"type":"null"}],"title":"Source Attribution"},"metric_basis":{"anyOf":[{"additionalProperties":{"type":"string"},"type":"object"},{"type":"null"}],"title":"Metric Basis"},"reporting_currency":{"type":"string","title":"Reporting Currency","default":"USD"},"metrics":{"additionalProperties":{"anyOf":[{"type":"number"},{"type":"null"}]},"type":"object","title":"Metrics","default":{}},"sec_document_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Sec Document Url","readOnly":true},"sec_filing_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Sec Filing Url","description":"Generate SEC EDGAR filing index URL.\n\nReturns:\n    URL string if accession_number exists, None otherwise","readOnly":true}},"type":"object","required":["cik","date","symbol","fiscal_year","period","sec_document_url","sec_filing_url"],"title":"BalanceSheetItem","description":"Individual balance sheet period data"},"BatchKeywordSearchRequest":{"properties":{"keyword":{"type":"string","maxLength":200,"minLength":1,"title":"Keyword","description":"Search term"},"accessions":{"items":{"type":"string"},"type":"array","maxItems":10,"minItems":1,"title":"Accessions","description":"Accession numbers (max 10)"},"row_type":{"type":"string","title":"Row Type","description":"Row type: chunk or section","default":"chunk"},"limit_per_filing":{"type":"integer","maximum":50.0,"minimum":1.0,"title":"Limit Per Filing","description":"Max matches per filing","default":20}},"type":"object","required":["keyword","accessions"],"title":"BatchKeywordSearchRequest","description":"Request body for batch keyword search across multiple filings."},"BatchKeywordSearchResponse":{"properties":{"keyword":{"type":"string","title":"Keyword"},"results":{"items":{"$ref":"#/components/schemas/KeywordSearchResult"},"type":"array","title":"Results"}},"type":"object","required":["keyword","results"],"title":"BatchKeywordSearchResponse","description":"Response for batch keyword search."},"BeatMissAssessment":{"properties":{"revenue_characterization":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Revenue Characterization"},"eps_characterization":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Eps Characterization"}},"type":"object","title":"BeatMissAssessment","description":"Beat/miss assessment vs analyst expectations (v3.4+)"},"BenchmarkSector":{"properties":{"code":{"type":"string","title":"Code"},"name":{"type":"string","title":"Name"},"unified_codes":{"items":{"type":"string"},"type":"array","title":"Unified Codes"},"default_selected":{"type":"boolean","title":"Default Selected"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description"},"warning":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Warning"}},"type":"object","required":["code","name","unified_codes","default_selected"],"title":"BenchmarkSector","description":"A benchmark sector with its unified code mappings."},"BillingPortalRequest":{"properties":{"return_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Return Url"}},"type":"object","title":"BillingPortalRequest","description":"Request model for creating billing portal session"},"CacheInvalidateRequest":{"properties":{"secret":{"type":"string","title":"Secret","description":"Shared revalidate secret"},"ticker":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Ticker","description":"Ticker to invalidate"},"cik":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cik","description":"CIK — also invalidates all of its tickers (incl. share-class aliases)"}},"type":"object","required":["secret"],"title":"CacheInvalidateRequest"},"CacheInvalidateResponse":{"properties":{"invalidated":{"items":{"type":"string"},"type":"array","title":"Invalidated","description":"Tickers whose generation was bumped"},"generations":{"additionalProperties":{"type":"integer"},"type":"object","title":"Generations","description":"New generation per ticker"}},"type":"object","required":["invalidated","generations"],"title":"CacheInvalidateResponse"},"CacheStatsResponse":{"properties":{"cache_type":{"type":"string","title":"Cache Type"},"stats":{"additionalProperties":true,"type":"object","title":"Stats"}},"type":"object","required":["cache_type","stats"],"title":"CacheStatsResponse","description":"Cache statistics response"},"CapitalAllocationAnalysis":{"properties":{"stock_repurch_ttm":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Stock Repurch Ttm"},"stock_repurch_fy":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Stock Repurch Fy"},"buyback_yield_ttm":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Buyback Yield Ttm"},"buyback_yield_fy":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Buyback Yield Fy"},"total_capital_returned_ttm":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Total Capital Returned Ttm"},"total_shareholder_yield_ttm":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Total Shareholder Yield Ttm"},"total_shareholder_yield_fy":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Total Shareholder Yield Fy"},"capital_return_ratio_ttm":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Capital Return Ratio Ttm"},"buyback_payout_ratio_ttm":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Buyback Payout Ratio Ttm"},"dividends_paid_ttm":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Dividends Paid Ttm"},"dividend_payout_ratio_ttm":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Dividend Payout Ratio Ttm"},"shares_outstanding_ttm":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Shares Outstanding Ttm"},"shares_outstanding_yoy_change":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Shares Outstanding Yoy Change"}},"type":"object","title":"CapitalAllocationAnalysis","description":"Capital allocation and shareholder returns analysis"},"CashFlowAnalysis":{"properties":{"operating_cash_flow_ttm":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Operating Cash Flow Ttm"},"free_cash_flow_ttm":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Free Cash Flow Ttm"},"capex_ttm":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Capex Ttm"},"fcf_to_revenue_ttm":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Fcf To Revenue Ttm"},"ocf_to_ni_ttm":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Ocf To Ni Ttm"},"ocf_margin_ttm":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Ocf Margin Ttm"},"capex_coverage_ttm":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Capex Coverage Ttm"},"fcf_yield_ttm":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Fcf Yield Ttm"},"ccc_ttm":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Ccc Ttm"},"dso_ttm":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Dso Ttm"},"dio_ttm":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Dio Ttm"},"dpo_ttm":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Dpo Ttm"},"fcf_2y_cagr":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Fcf 2Y Cagr"},"fcf_5y_cagr":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Fcf 5Y Cagr"},"ocf_margin_fy":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Ocf Margin Fy"},"capex_coverage_fy":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Capex Coverage Fy"}},"type":"object","title":"CashFlowAnalysis","description":"Cash generation quality and consistency"},"CashFlowInsight":{"properties":{"operating_cash_flow":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Operating Cash Flow","description":"Operating cash flow (current period)"},"ocf_prior_year":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Ocf Prior Year","description":"Operating cash flow (prior year period)"},"ocf_growth_pct":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Ocf Growth Pct","description":"OCF year-over-year growth percentage"},"free_cash_flow":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Free Cash Flow","description":"Free cash flow (current period)"},"fcf_prior_year":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Fcf Prior Year","description":"Free cash flow (prior year period)"},"fcf_growth_pct":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Fcf Growth Pct","description":"FCF year-over-year growth percentage"},"capex":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Capex","description":"Capital expenditures"},"capex_prior_year":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Capex Prior Year","description":"Capital expenditures (prior year period)"},"capex_growth_pct":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Capex Growth Pct","description":"CapEx year-over-year growth percentage"},"capex_quarterly_series":{"anyOf":[{"items":{"type":"number"},"type":"array"},{"type":"null"}],"title":"Capex Quarterly Series","description":"Recent quarterly CapEx series (oldest-to-newest, absolute positive values, excluding TTM). Sourced from the FCF reconciliation table when present."},"ocf_to_net_income_ratio":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Ocf To Net Income Ratio","description":"OCF / Net Income ratio (cash conversion)"},"fcf_to_net_income_ratio":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Fcf To Net Income Ratio","description":"FCF / Net Income ratio"},"accrual_quality":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Accrual Quality","description":"Accrual quality assessment: high, moderate, low, concern"},"accrual_quality_note":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Accrual Quality Note","description":"Explanation of accrual quality assessment"},"period":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Period","description":"Reporting basis of the monetary cash-flow fields: 'q_current' (the quarter alone), 'fy_current' (fiscal year to date / full year), or 'not_assessed'. Absent on rows produced before #1358."},"scale":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Scale","description":"Unit scale of the monetary fields. The service normalizes all cash-flow values to raw dollars, so this is 'absolute'. Consumers MUST NOT re-scale when scale=='absolute' (a missing/absent scale on older API responses means the values are in millions).","default":"absolute"},"provenance":{"anyOf":[{"items":{"$ref":"#/components/schemas/Receipt"},"type":"array"},{"type":"null"}],"title":"Provenance","description":"Source receipt(s) for the as-released cash-flow block: verbatim quote + deep-link into the 8-K cash-flow statement. `covers` names the printed figures attested (operating_cash_flow, capex); free_cash_flow is derived."}},"type":"object","title":"CashFlowInsight","description":"Cash flow metrics from earnings release (v5+)."},"CashFlowItem":{"properties":{"primary_document":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Primary Document"},"cik":{"type":"string","title":"Cik"},"accession_number":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Accession Number"},"date":{"type":"string","title":"Date"},"symbol":{"type":"string","title":"Symbol"},"filing_date":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Filing Date"},"fiscal_year":{"type":"integer","title":"Fiscal Year"},"period":{"type":"string","title":"Period"},"industry":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Industry"},"original_accession_number":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Original Accession Number"},"revised_after_vantage":{"type":"boolean","title":"Revised After Vantage","default":false},"source_attribution":{"anyOf":[{"additionalProperties":{"items":{"type":"string"},"type":"array"},"type":"object"},{"type":"null"}],"title":"Source Attribution"},"metric_basis":{"anyOf":[{"additionalProperties":{"type":"string"},"type":"object"},{"type":"null"}],"title":"Metric Basis"},"reporting_currency":{"type":"string","title":"Reporting Currency","default":"USD"},"metrics":{"additionalProperties":{"anyOf":[{"type":"number"},{"type":"null"}]},"type":"object","title":"Metrics","default":{}},"sec_document_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Sec Document Url","readOnly":true},"sec_filing_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Sec Filing Url","description":"Generate SEC EDGAR filing index URL.\n\nReturns:\n    URL string if accession_number exists, None otherwise","readOnly":true}},"type":"object","required":["cik","date","symbol","fiscal_year","period","sec_document_url","sec_filing_url"],"title":"CashFlowItem","description":"Individual cash flow statement period data"},"CashFlowQualityItem":{"properties":{"price_attribution":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Price Attribution","description":"The price source's required attribution, present only when the prices in this response come from a source that requires one (IEX HIST)."},"cik":{"type":"string","title":"Cik"},"accession_number":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Accession Number"},"date":{"type":"string","title":"Date"},"symbol":{"type":"string","title":"Symbol"},"filing_date":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Filing Date"},"fiscal_year":{"type":"integer","title":"Fiscal Year"},"period":{"type":"string","title":"Period"},"market_price":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Market Price"},"market_price_date":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Market Price Date"},"industry":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Industry"},"sector":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Sector"},"sic_code":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Sic Code"},"net_cf_ops":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Net Cf Ops"},"net_cf_ops_margin":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Net Cf Ops Margin"},"net_cf_ops_yoy":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Net Cf Ops Yoy"},"ocf_volatility_8q":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Ocf Volatility 8Q"},"ocf_consistency_score":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Ocf Consistency Score"},"ocf_to_net_income_ratio":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Ocf To Net Income Ratio"},"revenues":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Revenues"},"net_income":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Net Income"},"chg_working_cap":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Chg Working Cap"},"capex":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Capex"},"capex_intensity":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Capex Intensity"},"capex_yoy":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Capex Yoy"},"capex_to_depreciation_ratio":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Capex To Depreciation Ratio"},"capex_volatility_8q":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Capex Volatility 8Q"},"avg_capex_3y":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Avg Capex 3Y"},"deprec_amort":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Deprec Amort"},"ppe":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Ppe"},"ppe_turnover":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Ppe Turnover"},"fcf":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Fcf"},"ufcf":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Ufcf"},"fcf_equity":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Fcf Equity"},"fcf_margin":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Fcf Margin"},"fcf_yield":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Fcf Yield"},"fcf_conversion_rate":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Fcf Conversion Rate"},"fcf_yoy":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Fcf Yoy"},"fcf_cagr_3y":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Fcf Cagr 3Y"},"fcf_growth_stability":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Fcf Growth Stability"},"fcf_volatility_8q":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Fcf Volatility 8Q"},"fcf_positive_periods":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Fcf Positive Periods"},"fcf_min_max_range_8q":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Fcf Min Max Range 8Q"},"fcf_consistency_score":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Fcf Consistency Score"},"revenue_growth_yoy":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Revenue Growth Yoy"},"revenue_cagr_3y":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Revenue Cagr 3Y"},"fcf_to_revenue_growth_correlation":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Fcf To Revenue Growth Correlation"},"reinvestment_rate":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Reinvestment Rate"},"incremental_roic":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Incremental Roic"},"growth_efficiency_score":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Growth Efficiency Score"},"sustainable_growth_rate":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Sustainable Growth Rate"},"implied_fcf_growth":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Implied Fcf Growth"},"st_debt":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"St Debt"},"lt_debt":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Lt Debt"},"debt_yoy_change":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Debt Yoy Change"},"cash_st_invs":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Cash St Invs"},"excess_cash":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Excess Cash"},"net_debt":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Net Debt"},"shares_outstanding_basic":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Shares Outstanding Basic"},"shares_outstanding_diluted":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Shares Outstanding Diluted"},"share_count_trend_3y":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Share Count Trend 3Y"},"current_market_cap":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Current Market Cap"},"implied_fcf_yield_current":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Implied Fcf Yield Current"},"historical_fcf_yield_avg_5y":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Historical Fcf Yield Avg 5Y"},"sec_filing_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Sec Filing Url","description":"Generate SEC EDGAR filing index URL.\n\nReturns:\n    URL string if accession_number exists, None otherwise","readOnly":true}},"type":"object","required":["cik","date","symbol","fiscal_year","period","sec_filing_url"],"title":"CashFlowQualityItem","description":"Factual cash-flow-quality metrics for a single period.\n\nFive logical sections:\n1. Cash Generation Performance\n2. Capital Investment Requirements\n3. Free Cash Flow (Core)\n4. Growth & Reinvestment Analysis\n5. Balance Sheet Adjustments"},"ChangeType":{"type":"string","enum":["changed","added","removed","unchanged"],"title":"ChangeType","description":"Type of change between original and amended values"},"CheckoutSessionRequest":{"properties":{"tier":{"type":"string","title":"Tier"},"billing_interval":{"type":"string","title":"Billing Interval","default":"monthly"},"success_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Success Url"},"cancel_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cancel Url"},"utm_source":{"anyOf":[{"type":"string","maxLength":255},{"type":"null"}],"title":"Utm Source"},"utm_medium":{"anyOf":[{"type":"string","maxLength":255},{"type":"null"}],"title":"Utm Medium"},"utm_campaign":{"anyOf":[{"type":"string","maxLength":255},{"type":"null"}],"title":"Utm Campaign"}},"type":"object","required":["tier"],"title":"CheckoutSessionRequest","description":"Request model for creating checkout session"},"ClaimedIds":{"properties":{"deck_doc_ids":{"items":{"type":"string"},"type":"array","title":"Deck Doc Ids"},"event_keys":{"items":{"type":"string"},"type":"array","title":"Event Keys"}},"type":"object","title":"ClaimedIds","description":"The deck doc_ids + event_keys the RETURNED rows actually surface — the IR card\nsubtracts EXACTLY these so a document is never double-listed. Invariant: claim = render\n(never ids from rows beyond `limit`, never event material_ids — subtracting an unrendered\nid would hide the document on BOTH surfaces, #1614/fable)."},"CompanyData":{"properties":{"company_name":{"type":"string","title":"Company Name","description":"Company name"},"cik":{"type":"string","title":"Cik","description":"SEC CIK identifier"},"metrics":{"additionalProperties":{"$ref":"#/components/schemas/MetricData"},"type":"object","title":"Metrics","description":"Metrics by metric_id"}},"type":"object","required":["company_name","cik"],"title":"CompanyData","description":"Company data with all requested metrics"},"CompanyEventsResponse":{"properties":{"ticker":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Ticker"},"cik":{"type":"string","title":"Cik"},"company_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Company Name"},"upcoming":{"items":{"$ref":"#/components/schemas/IrCompanyEvent"},"type":"array","title":"Upcoming","description":"Future/today events, SOONEST-FIRST (uncapped)."},"past":{"items":{"$ref":"#/components/schemas/IrCompanyEvent"},"type":"array","title":"Past","description":"Historical events, NEWEST-FIRST (capped)."},"total_upcoming":{"type":"integer","title":"Total Upcoming","default":0},"total_past":{"type":"integer","title":"Total Past","description":"Total past events in the lookback window (may exceed the returned cap).","default":0},"coverage":{"$ref":"#/components/schemas/EventsCoverage"},"sec_earnings_releases":{"items":{"$ref":"#/components/schemas/SecEarningsRelease"},"type":"array","title":"Sec Earnings Releases","description":"r84: filled ONLY when the IR calendar has no events for this company (never harvested, or harvested with none): its results announcements filed with the SEC (8-K Item 2.02 — usually the quarterly earnings release; some filers also file preliminary results under it between releases; amendments excluded), NEWEST-FIRST, last 24 months, at most 8. Past filing dates, not a calendar: an upcoming date is not known from them."}},"type":"object","required":["cik","coverage"],"title":"CompanyEventsResponse"},"CompanyFullTextSearchRequest":{"properties":{"cik":{"type":"string","title":"Cik","description":"10-digit CIK (zero-padding tolerated)"},"keyword":{"type":"string","maxLength":200,"minLength":1,"title":"Keyword","description":"Search term"},"date_from":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Date From","description":"Earliest filing_date (YYYY-MM-DD)"},"date_to":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Date To","description":"Latest filing_date (YYYY-MM-DD)"},"form_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Form Type","description":"Form-type filter, comma-separated (e.g. '10-K,10-Q,8-K')"},"limit":{"type":"integer","maximum":50.0,"minimum":1.0,"title":"Limit","description":"Max matching filings","default":10},"limit_per_filing":{"type":"integer","maximum":50.0,"minimum":1.0,"title":"Limit Per Filing","description":"Max matching chunks per filing","default":10}},"type":"object","required":["cik","keyword"],"title":"CompanyFullTextSearchRequest","description":"Request body for a company-scoped full-text search over extracted sections.\n\nUsed as the MD-native fallback for ``search_sec_filings`` when EDGAR EFTS is\nunavailable: EFTS discovers filings by phrase across ALL of EDGAR, but it is an\nexternal dependency that flakes. When the agent already knows the company, this\nsearches MetricDuck's OWN extracted ``filing_text_sections`` (cik-pruned keyword\nsearch, see ``_search_match``) so a phrase query still lands on the right filing + section."},"CompanyFullTextSearchResponse":{"properties":{"keyword":{"type":"string","title":"Keyword"},"cik":{"type":"string","title":"Cik"},"results":{"items":{"$ref":"#/components/schemas/FullTextFilingMatch"},"type":"array","title":"Results"}},"type":"object","required":["keyword","cik","results"],"title":"CompanyFullTextSearchResponse","description":"Response for company-scoped full-text search."},"CompanyInfo":{"properties":{"ticker":{"type":"string","title":"Ticker"},"company_name":{"type":"string","title":"Company Name"},"cik":{"type":"string","title":"Cik"},"exchange":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Exchange"},"sic":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Sic"},"filer_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Filer Type"},"rank":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Rank"}},"type":"object","required":["ticker","company_name","cik"],"title":"CompanyInfo","description":"Company information for universe listing."},"CompanyNextFilings":{"properties":{"cik":{"type":"string","title":"Cik","description":"SEC CIK identifier"},"ticker":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Ticker","description":"Stock ticker symbol"},"company_name":{"type":"string","title":"Company Name","description":"Company legal name"},"rank":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Rank","description":"Company rank by market cap"},"market_cap":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Market Cap","description":"Market capitalization in USD"},"next_filing":{"additionalProperties":{"$ref":"#/components/schemas/NextFiling"},"type":"object","title":"Next Filing","description":"Next predicted filing by form type (10-Q, 10-K, 8-K-2.02)"}},"type":"object","required":["cik","company_name"],"title":"CompanyNextFilings","description":"Company metadata with next predicted filings"},"CompanySearchResponse":{"properties":{"ticker":{"type":"string","title":"Ticker"},"company_name":{"type":"string","title":"Company Name"},"cik":{"type":"string","title":"Cik"},"sic_code":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Sic Code"},"business_description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Business Description"},"requested_ticker":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Requested Ticker"},"is_alias":{"type":"boolean","title":"Is Alias","default":false},"is_delisted":{"type":"boolean","title":"Is Delisted","default":false},"delisted_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Delisted At"},"fiscal_year_end":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Fiscal Year End"},"former_names":{"items":{"type":"string"},"type":"array","title":"Former Names","default":[]},"filer_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Filer Type"},"match_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Match Type"}},"type":"object","required":["ticker","company_name","cik","sic_code","business_description"],"title":"CompanySearchResponse","description":"Company search result"},"CompanySectorResponse":{"properties":{"cik":{"type":"string","title":"Cik"},"sector":{"type":"string","title":"Sector"},"sector_code":{"type":"string","title":"Sector Code"},"industry":{"type":"string","title":"Industry"},"industry_code":{"type":"string","title":"Industry Code"},"confidence":{"type":"number","title":"Confidence"},"source":{"type":"string","title":"Source"}},"type":"object","required":["cik","sector","sector_code","industry","industry_code","confidence","source"],"title":"CompanySectorResponse","description":"Company sector classification"},"Comparison":{"properties":{"metric":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Metric"},"target_period":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Target Period"},"given_on":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Given On","description":"Earnings event date the guidance was issued (ISO)"},"reported_on":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Reported On","description":"Earnings event date the actual was reported (ISO)"},"guided_low":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Guided Low"},"guided_high":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Guided High"},"guided_unit":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Guided Unit"},"guidance_basis":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Guidance Basis","description":"gaap | non_gaap | unspecified — classified from the verbatim"},"guidance_verbatim":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Guidance Verbatim","description":"The guidance quote — the receipt for the basis tag + the range"},"actual":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Actual","description":"As-reported actual (as_reported only). Null unless status=compared."},"actual_derivation":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Actual Derivation","description":"as_reported (joins never use md_computed ratios in P0)"},"actual_source_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Actual Source Id","description":"Accession of the 8-K earnings release the actual was read from, when it came from the release (the 10-Q/10-K not in yet). Absent otherwise."},"actual_source_label":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Actual Source Label","description":"The release's printed row label for that actual ('Revenue', 'Net sales'). Set with actual_source_id."},"delta":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Delta","description":"Signed: actual − nearest guided bound (0 within band). Null unless compared."},"range_position":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Range Position","description":"above | within | below — pure arithmetic, NO valence. Null unless compared."},"status":{"type":"string","title":"Status","description":"compared | not_yet_settled | no_actual_on_basis | value_unparsed | period_unresolved | value_incongruent | multiple_values","default":"no_guidance"},"status_detail":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Status Detail","description":"Factual, receipt-pointing reason. Never valence."}},"type":"object","title":"Comparison","description":"A delivered-vs-guided ARITHMETIC comparison for ONE (metric, target period),\nperiod-matched on the OFFICIAL fiscal period. Per the #1478 Receipt Rule (P0):\nMD serves only what a third party recomputes from the receipts — the guided range\n(+ its verbatim), the as-reported actual, and pure arithmetic (`delta` +\n`range_position`). There is **no beat/miss verdict** — that imports \"higher = good\"\n(the caller's valence), so it is structurally absent from the schema. When the join\ncan't be made on the guidance's OWN basis, `status` names why (a typed, fail-closed\npipeline state), never a guess. `actual`/`delta`/`range_position` are populated ONLY\nwhen status == 'compared'."},"ComprehensiveOverviewResponse":{"properties":{"price_attribution":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Price Attribution","description":"The price source's required attribution, present only when the prices in this response come from a source that requires one (IEX HIST)."},"ticker":{"type":"string","title":"Ticker"},"company_name":{"type":"string","title":"Company Name"},"cik":{"type":"string","title":"Cik"},"business_description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Business Description"},"sector":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Sector"},"sector_code":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Sector Code"},"industry":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Industry"},"exchange":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Exchange"},"reporting_currency":{"type":"string","title":"Reporting Currency","default":"USD"},"ir_source":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Ir Source"},"executive_officers":{"anyOf":[{"$ref":"#/components/schemas/ExecutiveOfficersInfo"},{"type":"null"}]},"coverage":{"anyOf":[{"$ref":"#/components/schemas/CoverageStatus"},{"type":"null"}]},"data_freshness":{"$ref":"#/components/schemas/DataFreshnessInfo"},"profitability":{"$ref":"#/components/schemas/ProfitabilityAnalysis"},"balance_sheet":{"$ref":"#/components/schemas/BalanceSheetAnalysis"},"cash_flow":{"$ref":"#/components/schemas/CashFlowAnalysis"},"valuation":{"$ref":"#/components/schemas/ValuationAnalysis"},"current_price_valuation":{"anyOf":[{"$ref":"#/components/schemas/CurrentPriceValuation"},{"type":"null"}]},"capital_allocation":{"anyOf":[{"$ref":"#/components/schemas/CapitalAllocationAnalysis"},{"type":"null"}]},"operational_efficiency":{"anyOf":[{"$ref":"#/components/schemas/OperationalEfficiencyAnalysis"},{"type":"null"}]},"quarterly_trends":{"anyOf":[{},{"type":"null"}],"title":"Quarterly Trends"},"flags":{"$ref":"#/components/schemas/ObjectiveFlags"}},"type":"object","required":["ticker","company_name","cik","data_freshness","profitability","balance_sheet","cash_flow","valuation","flags"],"title":"ComprehensiveOverviewResponse","description":"Rich quantitative overview for UI and AI consumption"},"CoverageBlock":{"properties":{"earnings_calls":{"anyOf":[{"$ref":"#/components/schemas/EarningsCallCoverage"},{"type":"null"}],"description":"Earnings-call transcript coverage; null if none"},"ir_decks":{"anyOf":[{"$ref":"#/components/schemas/IrDeckCoverage"},{"type":"null"}],"description":"IR presentation-deck coverage; null if none"}},"type":"object","title":"CoverageBlock","description":"Compact 'what your agent reads' coverage for the overview page.\n\nCoverage-only (counts + latest + provenance tier) — NO signal atoms; the rich\nper-signal viz lives on /earnings. Either sub-block is null when absent so the\nfrontend card self-hides. Placement-agnostic: consumed as props by whichever\noverview card renders it (dedicated card or the Filings-navigator card)."},"CoverageStatus":{"properties":{"filer_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Filer Type","description":"SEC filer classification from companies.filer_type: 'domestic_operating', 'foreign_private_issuer', 'investment_company', or 'other'."},"has_ttm_metrics":{"type":"boolean","title":"Has Ttm Metrics","description":"True when the metrics pipeline has computed TTM (trailing-twelve-month) values for this company. False for FPIs with 20-F-only filings, newly listed companies, or pipeline gaps.","default":false},"gaps":{"items":{"type":"string"},"type":"array","title":"Gaps","description":"Human-readable reasons this company's data may be incomplete. Empty for healthy coverage (domestic filer, TTM populated). Consumers should surface any non-empty list prominently."},"status":{"anyOf":[{"type":"string","enum":["covered","partial","none"]},{"type":"null"}],"title":"Status","description":"Coverage discriminant for this RESOLVED company (#1428): 'covered' = full metrics snapshot present; 'partial' = row present but TTM missing or gaps non-empty; 'none' = the ticker resolves to a real SEC entity but MetricDuck has no financial snapshot yet (newly public, no XBRL, or files none). None on legacy responses. When 'none', every financial section is empty BY CONSTRUCTION — never read that absence as a zero."},"expected":{"items":{"type":"string"},"type":"array","title":"Expected","description":"For 'none' (and optionally 'partial') coverage: the filing events that would populate the absent surfaces, e.g. 'Fundamentals populate after the first 10-K/10-Q with XBRL'. Empty for full coverage. Lets web copy and agents derive the same promise from one struct — without over-stating imminence."}},"type":"object","title":"CoverageStatus","description":"Honest coverage signal about what's and isn't populated for this company.\n\nThe agent-facing question this answers: \"is a zero/missing metric here a\nreal data point, a pipeline gap, or a filer-type limitation?\"\n\nPopulated by the overview comprehensive endpoint using fields already\navailable on the metrics snapshot + a small JOIN to the companies table.\nRendered by MCP only when `gaps` is non-empty (quiet by default for\nhealthy domestic filers with full TTM coverage)."},"CreditInfo":{"properties":{"used":{"type":"integer","title":"Used","description":"Credits used for this request"},"total_used_this_month":{"type":"integer","title":"Total Used This Month","description":"Total credits used in current billing month"},"monthly_limit":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Monthly Limit","description":"Monthly credit limit (null if unlimited)"},"remaining":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Remaining","description":"Credits remaining this month (null if unlimited)"}},"type":"object","required":["used","total_used_this_month"],"title":"CreditInfo","description":"Credit usage information for flexible budget metering."},"CurrentPriceValuation":{"properties":{"current_price":{"type":"number","title":"Current Price"},"price_date":{"type":"string","title":"Price Date"},"market_cap":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Market Cap"},"ev":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Ev"},"pe_ratio":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Pe Ratio"},"pb_ratio":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Pb Ratio"},"ps_ratio":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Ps Ratio"},"ev_ebitda":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Ev Ebitda"},"ev_ebit":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Ev Ebit"},"ev_sales":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Ev Sales"},"ev_fcf":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Ev Fcf"},"fcf_yield":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Fcf Yield"},"dividend_yield":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Dividend Yield"},"earnings_yield":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Earnings Yield"},"buyback_yield":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Buyback Yield"},"total_shareholder_yield":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Total Shareholder Yield"}},"type":"object","required":["current_price","price_date"],"title":"CurrentPriceValuation","description":"Valuation metrics computed at current market price"},"DailyUsageResponse":{"properties":{"subscription_tier":{"type":"string","title":"Subscription Tier"},"has_daily_cap":{"type":"boolean","title":"Has Daily Cap"},"used_today":{"type":"integer","title":"Used Today"},"daily_limit":{"type":"integer","title":"Daily Limit"},"remaining":{"type":"integer","title":"Remaining"},"usage_percentage":{"type":"number","title":"Usage Percentage"},"resets_at":{"type":"string","title":"Resets At"},"counts_scope":{"type":"string","title":"Counts Scope","default":"data_api_credits"}},"type":"object","required":["subscription_tier","has_daily_cap","used_today","daily_limit","remaining","usage_percentage","resets_at"],"title":"DailyUsageResponse","description":"Free-tier daily DATA-API CREDIT usage (credit_ledger). The web no longer reads it: the\nquota-wall meter shows /users/usage `tool_calls_today`, the free daily cap's own counter.\n\n⚠ #2357 — this is NOT \"tool-call usage\", which is what it used to claim. The only\nthing it can count is `credit_ledger`, and the only writer of that ledger is\n`GET /api/v1/data/metrics` (credit_service.py:185 ← data_api.py:373). MCP connector\ntraffic never touches that route, so for an MCP user this ledger reads 0 no matter\nhow much they use the product.\n\nhas_daily_cap=False means \"no daily figure can be asserted\" — either a paid tier\n(no daily cap) or a free user with no metered consumption to report: see\n`counts_scope`."},"DataAPIResponse":{"properties":{"data":{"additionalProperties":{"$ref":"#/components/schemas/CompanyData"},"type":"object","title":"Data","description":"Company data keyed by ticker"},"metadata":{"$ref":"#/components/schemas/ResponseMetadata"}},"type":"object","required":["data","metadata"],"title":"DataAPIResponse","description":"Response for GET /api/v1/data/metrics\n\nNested JSON structure with companies as top-level keys,\neach containing their metrics and values."},"DataAvailabilityResponse":{"properties":{"ticker":{"type":"string","title":"Ticker"},"cik":{"type":"string","title":"Cik"},"company_name":{"type":"string","title":"Company Name"},"filing_count":{"type":"integer","title":"Filing Count","description":"Number of filings with processed text","default":0},"latest_filing_date":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Latest Filing Date","description":"Most recent filing date"},"form_types_available":{"items":{"type":"string"},"type":"array","title":"Form Types Available","description":"Available form types (e.g., ['10-K', '10-Q'])","default":[]},"total_sections":{"type":"integer","title":"Total Sections","description":"Total section types across all filings","default":0},"total_tables":{"type":"integer","title":"Total Tables","description":"Total tables across all filings","default":0},"xbrl_facts_available":{"type":"boolean","title":"Xbrl Facts Available","description":"Whether XBRL facts are available","default":false},"xbrl_fact_count":{"type":"integer","title":"Xbrl Fact Count","description":"Approximate XBRL fact count","default":0},"filings":{"items":{"$ref":"#/components/schemas/FilingAvailability"},"type":"array","title":"Filings","description":"Per-filing data summary","default":[]}},"type":"object","required":["ticker","cik","company_name"],"title":"DataAvailabilityResponse","description":"What filing data is available for a company."},"DataFreshnessInfo":{"properties":{"ttm_as_of_date":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Ttm As Of Date"},"ttm_filing_date":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Ttm Filing Date"},"ttm_age_days":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Ttm Age Days"},"ttm_source_form":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Ttm Source Form"},"mrq_as_of_date":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Mrq As Of Date"},"fy_as_of_date":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Fy As Of Date"},"fy_fiscal_year":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Fy Fiscal Year"},"fy_age_days":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Fy Age Days"},"mrq_filing_date":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Mrq Filing Date"},"mrq_age_days":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Mrq Age Days"},"mrq_source_form":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Mrq Source Form"},"staleness_warning":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Staleness Warning"}},"type":"object","title":"DataFreshnessInfo","description":"Data provenance and staleness indicators"},"DeckRef":{"properties":{"doc_id":{"type":"string","title":"Doc Id","description":"Stable ir_documents identity ('{cik10}:u:{sha1(url)}') — the claim/subtract key the IR card removes from its own list. NOT an event key."},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Title","description":"Verbatim catalog title (may be null / uninformative)."},"url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Url","description":"Original IR-hosted source URL."},"gcs_uri":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Gcs Uri","description":"Stable MetricDuck-mirrored copy (gs:// URI), when mirrored."},"source_table":{"type":"string","title":"Source Table","default":"ir_documents"},"key_used":{"type":"string","title":"Key Used","default":"(fiscal_year, fiscal_period) identity (Q4→FY)"}},"type":"object","required":["doc_id"],"title":"DeckRef","description":"One served IR presentation deck attached to a period by EXACT canonical\n(fiscal_year, fiscal_period) tuple identity (Q4→FY canonicalized) — never a date.\nA period can carry SEVERAL earnings-adjacent decks (earnings + supplemental + investor\npresentation); the row LISTS them, it never picks 'the' one (#1614/fable)."},"DetailedHealthResponse":{"properties":{"status":{"type":"string","title":"Status"},"timestamp":{"type":"number","title":"Timestamp"},"version":{"type":"string","title":"Version"},"environment":{"type":"string","title":"Environment"},"uptime_seconds":{"type":"number","title":"Uptime Seconds"},"services":{"additionalProperties":{"additionalProperties":true,"type":"object"},"type":"object","title":"Services"},"commit_sha":{"type":"string","title":"Commit Sha"}},"type":"object","required":["status","timestamp","version","environment","uptime_seconds","services","commit_sha"],"title":"DetailedHealthResponse","description":"Detailed health check response"},"DocRef":{"properties":{"accession_number":{"type":"string","title":"Accession Number"},"kind":{"type":"string","title":"Kind","description":"Human label: 'Press Release' | 'Related 8-K' | 'Quarterly Report' | 'Annual Report'."},"section_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Section Id","description":"get_filing_section section id (e.g. 'earnings_press_release')."},"period_end":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Period End","description":"Authoritative fiscal period end (10-Q/10-K DEI); null for the 8-K cell."},"filing_date":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Filing Date","description":"The 8-K's filing date (8-K cells only)."},"source_table":{"type":"string","title":"Source Table","description":"BQ table the cell was resolved from (provenance echo)."},"key_used":{"type":"string","title":"Key Used","description":"The join key used to attach this cell (provenance echo)."}},"type":"object","required":["accession_number","kind","source_table","key_used"],"title":"DocRef","description":"A pointer to a document cell — enough for the frontend to build the read link,\nplus a provenance echo so the join is auditable."},"EarningsCallCoverage":{"properties":{"covered":{"type":"integer","title":"Covered","description":"Calls whose transcript TEXT is servable within the window (COMPLETED ∪ TEXT_STORED) — matches what the surface can actually LINK (#1874/#1364)"},"analyzed":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Analyzed","description":"Narrower count: calls with a COMPLETED transcript (L2 signals present). Subset of `covered`."},"window":{"type":"integer","title":"Window","description":"Earnings events examined — the last N (N<=8), incl. gaps"},"latest":{"anyOf":[{"$ref":"#/components/schemas/LatestCallCoverage"},{"type":"null"}],"description":"Most-recent call with a rendered transcript page; null if none servable"},"unavailable":{"type":"boolean","title":"Unavailable","description":"True when the coverage LOOKUP failed (timeout/quota/byte-cap) — a distinct state from a genuine zero (#1264). Consumers MUST render 'coverage unavailable', never conflate it with 'none covered' (a failed check is not a real zero).","default":false}},"type":"object","required":["covered","window"],"title":"EarningsCallCoverage","description":"Earnings-call transcript coverage — a windowed ratio plus the latest call."},"EarningsEventCell":{"properties":{"matched":{"type":"boolean","title":"Matched","description":"True when exactly one earnings event fell in the ±1d window."},"event_key":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Event Key","description":"Stable ir_events identity — the claim/subtract key. NOT a doc_id."},"occurred_at":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Occurred At","description":"Event DATE (authoritative). Clock-time is NOT surfaced (#1383)."},"webcast_link":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Webcast Link","description":"Live/recorded webcast URL, if the harvest captured one."},"detail_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Detail Url","description":"IR event-detail page URL (present even when webcast_link is null)."},"source_table":{"type":"string","title":"Source Table","default":"ir_events"},"key_used":{"type":"string","title":"Key Used","default":"date_window(±1d)"}},"type":"object","required":["matched"],"title":"EarningsEventCell","description":"The IR-calendar earnings EVENT for this period — an event POINTER (webcast link),\nNOT the event's material chips (decks live in `decks`; the press release is the 8-K).\nJoined by a bounded ±1d date-window on the 8-K reporting date, single-candidate ONLY\n(an ambiguous window is NO join + a flag, never a guess). The event's own\n`fiscal_period` is DISPLAY-only and is never a join key (#1383 / IR_SURFACES.md)."},"EarningsInsight":{"properties":{"cik":{"type":"string","title":"Cik"},"company_name":{"type":"string","title":"Company Name"},"ticker":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Ticker"},"accession_number":{"type":"string","title":"Accession Number"},"filing_date":{"type":"string","format":"date","title":"Filing Date"},"fiscal_period":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Fiscal Period"},"fiscal_year":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Fiscal Year"},"executive_summary":{"type":"string","title":"Executive Summary"},"positive_highlights":{"items":{"$ref":"#/components/schemas/HighlightItem"},"type":"array","title":"Positive Highlights"},"concerns":{"items":{"$ref":"#/components/schemas/HighlightItem"},"type":"array","title":"Concerns"},"key_highlights":{"items":{"type":"string"},"type":"array","title":"Key Highlights"},"management_commentary":{"items":{"type":"string"},"type":"array","title":"Management Commentary"},"revenue":{"anyOf":[{"$ref":"#/components/schemas/EarningsMetric"},{"type":"null"}]},"net_income":{"anyOf":[{"$ref":"#/components/schemas/EarningsMetric"},{"type":"null"}]},"operating_income":{"anyOf":[{"$ref":"#/components/schemas/EarningsMetric"},{"type":"null"}]},"eps_diluted":{"anyOf":[{"$ref":"#/components/schemas/EarningsMetric"},{"type":"null"}]},"eps_basic":{"anyOf":[{"$ref":"#/components/schemas/EarningsMetric"},{"type":"null"}]},"withheld":{"items":{"$ref":"#/components/schemas/WithheldField"},"type":"array","title":"Withheld","description":"Metrics withheld by the serve-cap or the currency gate (served null + a 'check the filing' note); empty when nothing was withheld."},"advisories":{"items":{"$ref":"#/components/schemas/FieldAdvisory"},"type":"array","title":"Advisories","description":"Groups of figures that cannot all be right, served in full with the disagreement named; empty when nothing was flagged."},"beat_miss":{"anyOf":[{"$ref":"#/components/schemas/BeatMissAssessment"},{"type":"null"}]},"cash_flow":{"anyOf":[{"$ref":"#/components/schemas/CashFlowInsight"},{"type":"null"}],"description":"Cash flow metrics with accrual quality (v5+)"},"guidance_revisions":{"items":{"$ref":"#/components/schemas/GuidanceRevision"},"type":"array","title":"Guidance Revisions","description":"Guidance revisions (raised/lowered)"},"management_assessment":{"anyOf":[{"$ref":"#/components/schemas/ManagementAssessment"},{"type":"null"}],"description":"Management tone and disclosure quality (v5+)"},"material_events":{"items":{"$ref":"#/components/schemas/MaterialEvent"},"type":"array","title":"Material Events","description":"Material events (M&A, regulatory)"},"gross_margin":{"anyOf":[{"$ref":"#/components/schemas/MarginMetric"},{"type":"null"}]},"operating_margin":{"anyOf":[{"$ref":"#/components/schemas/MarginMetric"},{"type":"null"}]},"net_margin":{"anyOf":[{"$ref":"#/components/schemas/MarginMetric"},{"type":"null"}]},"special_items":{"items":{"$ref":"#/components/schemas/SpecialItem"},"type":"array","title":"Special Items"},"guidance":{"items":{"$ref":"#/components/schemas/src__models__earnings_insights__GuidanceItem"},"type":"array","title":"Guidance"},"segments":{"items":{"$ref":"#/components/schemas/SegmentData"},"type":"array","title":"Segments"},"operational_metrics":{"additionalProperties":{"$ref":"#/components/schemas/OperationalMetric"},"type":"object","title":"Operational Metrics"},"filing_metadata":{"anyOf":[{"$ref":"#/components/schemas/FilingMetadata"},{"type":"null"}]},"form_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Form Type"},"source_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source Url"},"items":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Items"},"acceptance_datetime":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Acceptance Datetime"},"extraction_confidence":{"type":"number","maximum":1.0,"minimum":0.0,"title":"Extraction Confidence","description":"Confidence score 0.0-1.0"},"llm_model":{"type":"string","title":"Llm Model"},"processing_cost_usd":{"type":"number","title":"Processing Cost Usd"},"processed_at":{"type":"string","format":"date-time","title":"Processed At"}},"type":"object","required":["cik","company_name","accession_number","filing_date","executive_summary","extraction_confidence","llm_model","processing_cost_usd","processed_at"],"title":"EarningsInsight","description":"Complete earnings insights from LLM-extracted 8-K release.\n\nThis model represents the full structured output from the earnings processor,\nincluding financial metrics, margins, segments, guidance, and commentary."},"EarningsMetric":{"properties":{"q_current":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Q Current"},"q_prior_year":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Q Prior Year"},"annual_current":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Annual Current"},"annual_prior_year":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Annual Prior Year"},"yoy_growth":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Yoy Growth"},"currency":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Currency","description":"ISO currency of every figure on this metric, when the release's own table names it (r111). Set only for a non-USD reporter's figure read from a table printed in the company's reporting currency; None otherwise (a USD reporter's figures are dollars)."},"provenance":{"anyOf":[{"items":{"$ref":"#/components/schemas/Receipt"},"type":"array"},{"type":"null"}],"title":"Provenance","description":"Per-figure receipts, each attesting only the period(s) in its own `covers` list (see Receipt) — a receipt is never emitted for a field it doesn't explicitly cover, even when other fields on this same metric are attested. Null when the value is legacy-filled, v3-absent, or the source quote is unvalidated: absence of a receipt is not evidence the value is wrong, only that no attested quote is available for it (fail-closed)."}},"type":"object","title":"EarningsMetric","description":"Metric with quarterly and annual values"},"EarningsReportRow":{"properties":{"fiscal_year":{"type":"integer","title":"Fiscal Year"},"fiscal_period":{"type":"string","title":"Fiscal Period","description":"'Q1' | 'Q2' | 'Q3' | 'FY'."},"label":{"type":"string","title":"Label","description":"Display label, e.g. 'Q2-2026' / 'FY-2025'."},"reporting_date":{"type":"string","format":"date","title":"Reporting Date","description":"The earnings 8-K filing date (or the report filing date if no 8-K)."},"acceptance_datetime":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Acceptance Datetime","description":"The 8-K's SEC acceptance timestamp (UTC, approximate). Null on report-only (no-earnings-8K) rows and when unresolved. The consumer converts to ET and guards a fabricated '00:00:00Z' / null → date-only."},"press_release":{"anyOf":[{"$ref":"#/components/schemas/DocRef"},{"type":"null"}]},"related_8ks":{"items":{"$ref":"#/components/schemas/DocRef"},"type":"array","title":"Related 8Ks","description":"The period's other earnings 8-Ks of the SAME release cycle (filed within 7 days of its newest), folded into this row: prepared remarks, a deck, a pre-release, an 8-K/A. The press release is the cycle's 8-K carrying the earnings statements."},"transcript":{"$ref":"#/components/schemas/TranscriptCell"},"report":{"anyOf":[{"$ref":"#/components/schemas/DocRef"},{"type":"null"}]},"decks":{"items":{"$ref":"#/components/schemas/DeckRef"},"type":"array","title":"Decks","description":"Served IR presentation decks for THIS period (exact canonical tuple; may be several — earnings + supplemental + investor deck)."},"decks_total":{"type":"integer","title":"Decks Total","description":"Total decks matched (>= len(decks) when the list is capped).","default":0},"earnings_event":{"anyOf":[{"$ref":"#/components/schemas/EarningsEventCell"},{"type":"null"}],"description":"The IR-calendar earnings event (webcast pointer) for this period, or null when no single event fell in the ±1d window / the calendar isn't harvested."},"flags":{"items":{"type":"string"},"type":"array","title":"Flags","description":"By-construction honesty flags, e.g. 'no_matching_report', 'webcast_window_ambiguous'."}},"type":"object","required":["fiscal_year","fiscal_period","label","reporting_date","transcript"],"title":"EarningsReportRow"},"EarningsReportsCoverage":{"properties":{"periods":{"type":"integer","title":"Periods","description":"Number of reporting periods returned."},"with_press_release":{"type":"integer","title":"With Press Release"},"with_transcript":{"type":"integer","title":"With Transcript","description":"Periods whose transcript state is 'present'."},"transcript_pending":{"type":"integer","title":"Transcript Pending"},"with_report":{"type":"integer","title":"With Report"},"note":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Note"}},"type":"object","required":["periods","with_press_release","with_transcript","transcript_pending","with_report"],"title":"EarningsReportsCoverage"},"EarningsReportsResponse":{"properties":{"ticker":{"type":"string","title":"Ticker"},"cik":{"type":"string","title":"Cik"},"company_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Company Name"},"reports":{"items":{"$ref":"#/components/schemas/EarningsReportRow"},"type":"array","title":"Reports"},"coverage":{"$ref":"#/components/schemas/EarningsReportsCoverage"},"claimed":{"$ref":"#/components/schemas/ClaimedIds","description":"Deck/event ids the earnings surface OWNS — the IR card subtracts these."},"events_coverage":{"anyOf":[{"$ref":"#/components/schemas/EventsCoverage"},{"type":"null"}],"description":"Honesty stamp for the IR event calendar (harvested / outcome / note) so a null earnings_event reads 'calendar not harvested' vs 'no earnings event', without a second /events fetch."},"sub_call_errors":{"items":{"type":"string"},"type":"array","title":"Sub Call Errors"}},"type":"object","required":["ticker","cik","reports","coverage"],"title":"EarningsReportsResponse"},"ErrorResponse":{"properties":{"error":{"type":"string","title":"Error","description":"Error message"},"details":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Details","description":"Additional error details"},"error_code":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error Code","description":"Error code for client handling"}},"type":"object","required":["error"],"title":"ErrorResponse","description":"Standard error response","example":{"details":"No market data available for ticker INVALID","error":"Ticker not found","error_code":"TICKER_NOT_FOUND"}},"EventMaterial":{"properties":{"material_id":{"type":"string","title":"Material Id","description":"Stable material id — this IS the `get_ir_documents` doc_id. A POINTER: fetch the document's content via get_ir_documents, not here."},"kind":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Kind","description":"File ROLE (open vocab): presentation | webcast | press_release | transcript | document | data_xlsx | …. A different axis from the event's type."},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Title","description":"Verbatim material title from the source."},"url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Url","description":"Direct source URL for this material."}},"type":"object","required":["material_id"],"title":"EventMaterial"},"EventsCoverage":{"properties":{"harvested":{"type":"boolean","title":"Harvested","description":"Whether this company's IR calendar has been harvested at all. False ⇒ absence of events below does NOT mean the company has none."},"outcome":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Outcome","description":"Latest harvest outcome: jsonp_ok | apikey_ok | empty | blocked | error."},"last_checked_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Last Checked At","description":"When the IR calendar was last fetched. Events ANNOUNCED SINCE are not shown — treat the upcoming list as complete only as of this timestamp."},"note":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Note","description":"Honest coverage note."}},"type":"object","required":["harvested"],"title":"EventsCoverage"},"ExecutiveOfficersInfo":{"properties":{"ceo_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Ceo Name"},"ceo_title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Ceo Title"},"cfo_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cfo Name"},"cfo_title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cfo Title"},"as_of_accession":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"As Of Accession"},"as_of_filing_date":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"As Of Filing Date"}},"type":"object","title":"ExecutiveOfficersInfo","description":"Current principal executive (CEO) and financial (CFO) officers.\n\nParsed from the signature block of the company's most recent 10-K/10-Q\n(every periodic report is signed by the principal executive + financial\nofficers, annotated \"(Principal Executive Officer)\" / \"(Principal Financial\nOfficer)\"). Always current (refreshed each 10-Q). `as_of_*` give provenance.\nA single person can hold both roles (then ceo_name == cfo_name)."},"FactBenchmark":{"properties":{"sector_code":{"type":"string","title":"Sector Code","description":"Sector code"},"sector_name":{"type":"string","title":"Sector Name","description":"Human-readable sector name"},"median":{"type":"number","title":"Median","description":"Median value across companies in sector"},"p25":{"type":"number","title":"P25","description":"25th percentile"},"p75":{"type":"number","title":"P75","description":"75th percentile"},"min_value":{"type":"number","title":"Min Value","description":"Minimum value"},"max_value":{"type":"number","title":"Max Value","description":"Maximum value"},"company_count":{"type":"integer","title":"Company Count","description":"Number of companies with this fact in sector"},"unit":{"type":"string","title":"Unit","description":"XBRL unit (USD, shares, pure)"},"as_of_date":{"type":"string","title":"As Of Date","description":"Data freshness date"}},"type":"object","required":["sector_code","sector_name","median","p25","p75","min_value","max_value","company_count","unit","as_of_date"],"title":"FactBenchmark","description":"Sector benchmark statistics for raw XBRL facts.\n\nProvides percentile-based benchmarks for XBRL account values."},"FactBenchmarkList":{"properties":{"account":{"type":"string","title":"Account","description":"XBRL account name (concept)"},"concept_label":{"type":"string","title":"Concept Label","description":"Human-readable concept label"},"benchmarks":{"items":{"$ref":"#/components/schemas/FactBenchmark"},"type":"array","title":"Benchmarks","description":"List of sector benchmarks"},"total_sectors":{"type":"integer","title":"Total Sectors","description":"Number of sectors with data"},"total_companies":{"type":"integer","title":"Total Companies","description":"Total companies across all sectors"},"generated_at":{"type":"string","title":"Generated At","description":"Timestamp when generated"}},"type":"object","required":["account","concept_label","benchmarks","total_sectors","total_companies","generated_at"],"title":"FactBenchmarkList","description":"Response model for XBRL fact sector benchmark endpoint."},"FactByPeriod":{"properties":{"concept":{"type":"string","title":"Concept","description":"XBRL concept name"},"concept_label":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Concept Label","description":"Human-readable standard label"},"concept_label_terse":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Concept Label Terse","description":"Human-readable terse/short label for compact UIs"},"unit":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Unit","description":"Unit (USD, shares, etc.)"},"is_consolidated":{"type":"boolean","title":"Is Consolidated","description":"True if no dimensional breakdown","default":true},"dimension_count":{"type":"integer","title":"Dimension Count","description":"Number of dimensions (0=consolidated, 1=subtotal, 2+=detail)","default":0},"dimensions":{"items":{"$ref":"#/components/schemas/src__routes__companies__facts_by_period__DimensionInfo"},"type":"array","title":"Dimensions","description":"Dimensional axes and members","default":[]},"values":{"additionalProperties":{"$ref":"#/components/schemas/PeriodValue"},"type":"object","title":"Values","description":"Values keyed by period_end date (YYYY-MM-DD) with native_id for deep linking"},"fact_key":{"type":"string","title":"Fact Key","description":"Unique key: concept|member1|member2","default":""},"parent_fact_key":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Parent Fact Key","description":"Parent fact key in hierarchy"},"hierarchy_level":{"type":"string","title":"Hierarchy Level","description":"consolidated|subtotal|detail","default":"consolidated"},"primary_axis":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Primary Axis","description":"Primary breakdown axis for this fact"},"display_indent":{"type":"integer","title":"Display Indent","description":"Suggested indent level (0-4)","default":0}},"type":"object","required":["concept","values"],"title":"FactByPeriod","description":"Single concept with values across periods"},"FactComparison":{"properties":{"fact_key":{"type":"string","title":"Fact Key","description":"Unique fact identifier for cross-filing matching"},"concept":{"type":"string","title":"Concept","description":"XBRL concept/account name"},"concept_label":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Concept Label","description":"Human-readable concept label"},"end_date":{"type":"string","format":"date","title":"End Date","description":"Period end date"},"unit":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Unit","description":"Unit of measure (USD, shares, etc.)"},"is_consolidated":{"type":"boolean","title":"Is Consolidated","description":"True if no dimensional breakdown","default":true},"dimensions":{"items":{"$ref":"#/components/schemas/src__models__xbrl__DimensionInfo"},"type":"array","title":"Dimensions","description":"Dimensional axes and members","default":[]},"original_value":{"anyOf":[{"type":"number"},{"type":"integer"},{"type":"null"}],"title":"Original Value","description":"Value from original filing"},"amended_value":{"anyOf":[{"type":"number"},{"type":"integer"},{"type":"null"}],"title":"Amended Value","description":"Value from amendment filing"},"change_type":{"$ref":"#/components/schemas/ChangeType","description":"Type of change: changed, added, removed, unchanged"},"pct_change":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Pct Change","description":"Percentage change from original"},"value_delta":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Value Delta","description":"Absolute change from original"},"original_native_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Original Native Id","description":"Native ID in original filing for deep linking"},"amended_native_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Amended Native Id","description":"Native ID in amendment for deep linking"}},"type":"object","required":["fact_key","concept","end_date","change_type"],"title":"FactComparison","description":"Single fact with original vs amended comparison"},"FactHistoryResponse":{"properties":{"ticker":{"type":"string","title":"Ticker"},"cik":{"type":"string","title":"Cik"},"company_name":{"type":"string","title":"Company Name"},"original_accn":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Original Accn","description":"Original filing accession number"},"original_date":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Original Date","description":"Original filing date"},"amendment_accn":{"type":"string","title":"Amendment Accn","description":"Amendment filing accession number"},"amendment_date":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Amendment Date","description":"Amendment filing date"},"fiscal_year":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Fiscal Year","description":"Fiscal year"},"fiscal_period":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Fiscal Period","description":"Fiscal period (Q1, Q2, Q3, FY)"},"original_viewer_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Original Viewer Url","description":"URL to view original filing"},"amendment_viewer_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Amendment Viewer Url","description":"URL to view amendment filing"},"total_changed":{"type":"integer","title":"Total Changed","description":"Number of facts with changed values","default":0},"total_added":{"type":"integer","title":"Total Added","description":"Number of new facts in amendment","default":0},"total_removed":{"type":"integer","title":"Total Removed","description":"Number of facts removed in amendment","default":0},"total_unchanged":{"type":"integer","title":"Total Unchanged","description":"Number of unchanged facts","default":0},"facts":{"items":{"$ref":"#/components/schemas/FactComparison"},"type":"array","title":"Facts"}},"type":"object","required":["ticker","cik","company_name","amendment_accn","facts"],"title":"FactHistoryResponse","description":"Response containing amendment comparison for a filing"},"FactsByPeriodResponse":{"properties":{"ticker":{"type":"string","title":"Ticker"},"cik":{"type":"string","title":"Cik"},"company_name":{"type":"string","title":"Company Name"},"periods":{"items":{"$ref":"#/components/schemas/PeriodInfo"},"type":"array","title":"Periods"},"facts":{"items":{"$ref":"#/components/schemas/FactByPeriod"},"type":"array","title":"Facts"},"total_concepts":{"type":"integer","title":"Total Concepts"},"hierarchy_metadata":{"anyOf":[{"$ref":"#/components/schemas/HierarchyMetadata"},{"type":"null"}],"description":"Hierarchy reconstruction instructions for frontend"}},"type":"object","required":["ticker","cik","company_name","periods","facts","total_concepts"],"title":"FactsByPeriodResponse","description":"Response with facts pivoted by period and hierarchy metadata"},"FeedbackRequest":{"properties":{"category":{"type":"string","enum":["missing_data","wrong_value","missing_capability","other"],"title":"Category"},"message":{"type":"string","maxLength":1000,"minLength":1,"title":"Message"},"source":{"type":"string","enum":["user","model"],"title":"Source"}},"additionalProperties":false,"type":"object","required":["category","message","source"],"title":"FeedbackRequest"},"FieldAdvisory":{"properties":{"metrics":{"items":{"type":"string"},"type":"array","title":"Metrics","description":"Every metric in the disagreement — none of them is withheld, and the advisory does not claim to know which one is wrong."},"reason":{"type":"string","title":"Reason","description":"Machine tag: 'margin_operand_mismatch' (a margin, its operand and revenue cannot all three be right)."},"note":{"type":"string","title":"Note","description":"Human-facing explanation ('… check the filing')."},"filing_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Filing Url","description":"Link to the source filing to check the reported figures."}},"type":"object","required":["metrics","reason","note"],"title":"FieldAdvisory","description":"Figures that are mutually inconsistent, served anyway with the disagreement named.\n\n⛔ The opposite of `WithheldField`: nothing is nulled. It exists because the\ndetector can prove a row is wrong without being able to say WHICH member is wrong.\n`margin/100 x revenue == operand` has three terms, and measured against audited\nXBRL the broken one is revenue about as often as it is the operand — AMTB serves\nrevenue $18,030 against a filed $100,737,000 while its own net income and margin\nare both right, and Visa serves an operating income of -$44.00M against a filed\n$6.877B while its revenue is right. Same three-number signature, opposite culprits.\n\nSo this names every member of the disagreement and deletes none of them. The\nprevious design picked one and was wrong 7 times in 26 (#3218), and the one after\nthat logged silently, which left Visa serving a confirmed-wrong figure with no\nreader-visible signal at all.\n\nAdditive + default-empty, so an older worker simply ignores it."},"FilingAvailability":{"properties":{"accession_number":{"type":"string","title":"Accession Number"},"form_type":{"type":"string","title":"Form Type"},"filing_date":{"type":"string","title":"Filing Date"},"fiscal_year":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Fiscal Year"},"fiscal_period":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Fiscal Period"},"section_count":{"type":"integer","title":"Section Count","default":0},"table_count":{"type":"integer","title":"Table Count","default":0},"total_words":{"type":"integer","title":"Total Words","default":0}},"type":"object","required":["accession_number","form_type","filing_date"],"title":"FilingAvailability","description":"Summary of a single filing's available data."},"FilingIndexBundleResponse":{"properties":{"ticker":{"type":"string","title":"Ticker"},"filing_intelligence":{"additionalProperties":true,"type":"object","title":"Filing Intelligence"},"ir_events":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Ir Events"},"transcript_signals":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Transcript Signals"},"earnings_latest":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Earnings Latest"},"income_statement":{"anyOf":[{"items":{"additionalProperties":true,"type":"object"},"type":"array"},{"type":"null"}],"title":"Income Statement"},"cash_flow":{"anyOf":[{"items":{"additionalProperties":true,"type":"object"},"type":"array"},{"type":"null"}],"title":"Cash Flow"},"concentration":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Concentration"},"newer_filing_not_indexed":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Newer Filing Not Indexed"},"sub_call_errors":{"items":{"type":"string"},"type":"array","title":"Sub Call Errors"}},"type":"object","required":["ticker","filing_intelligence"],"title":"FilingIndexBundleResponse","description":"Aggregated response for `get_filing_index` — bundles the sub-queries.\n\n`filing_intelligence` is required. Other fields are optional and may\nbe None if the underlying sub-call failed (graceful degradation —\npreserves prior mcp-worker `.catch()` behavior at the HTTP layer).\n\n`sub_call_errors` lists the names of optional sub-calls that failed,\nfor observability."},"FilingIntelligenceError":{"properties":{"success":{"type":"boolean","title":"Success","default":false},"error":{"type":"string","title":"Error"},"ticker":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Ticker"},"message":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Message"},"help":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Help"}},"type":"object","required":["error"],"title":"FilingIntelligenceError","description":"Error response for filing intelligence endpoints."},"FilingIntelligenceSummary":{"properties":{"ticker":{"type":"string","title":"Ticker"},"cik":{"type":"string","title":"Cik"},"company_name":{"type":"string","title":"Company Name"},"accession_number":{"type":"string","title":"Accession Number"},"form_type":{"type":"string","title":"Form Type"},"filing_date":{"type":"string","format":"date","title":"Filing Date"},"fiscal_period":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Fiscal Period"},"fiscal_year":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Fiscal Year"},"overall_score":{"anyOf":[{"type":"integer","maximum":10.0,"minimum":1.0},{"type":"null"}],"title":"Overall Score"},"executive_summary":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Executive Summary"},"top_concerns":{"items":{"type":"string"},"type":"array","title":"Top Concerns"},"top_positives":{"items":{"type":"string"},"type":"array","title":"Top Positives"},"processor_version":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Processor Version"}},"type":"object","required":["ticker","cik","company_name","accession_number","form_type","filing_date"],"title":"FilingIntelligenceSummary","description":"Simplified filing intelligence summary for list/card views.\n\nUsed by GET /api/v1/filing-intelligence/recent for dashboard feeds.\nContains only essential fields needed for displaying recent 10-Q/10-K filings."},"FilingIntelligenceSummaryListResponse":{"properties":{"data":{"items":{"$ref":"#/components/schemas/FilingIntelligenceSummary"},"type":"array","title":"Data"},"total":{"type":"integer","title":"Total"}},"type":"object","required":["data","total"],"title":"FilingIntelligenceSummaryListResponse","description":"List response for recent filing intelligence summaries.\n\nReturned by GET /api/v1/filing-intelligence/recent"},"FilingListResponse":{"properties":{"ticker":{"type":"string","title":"Ticker"},"company_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Company Name"},"filings":{"items":{"$ref":"#/components/schemas/FilingSectionSummary"},"type":"array","title":"Filings"},"total_filings":{"type":"integer","title":"Total Filings","default":0},"unextracted_filings":{"items":{"$ref":"#/components/schemas/UnextractedFiling"},"type":"array","title":"Unextracted Filings"}},"type":"object","required":["ticker","filings"],"title":"FilingListResponse","description":"Response listing filings and their section metadata for a company."},"FilingMetadata":{"properties":{"form_type":{"type":"string","title":"Form Type","description":"SEC form type (typically '8-K' for earnings)","default":"8-K"},"items":{"items":{"type":"string"},"type":"array","title":"Items","description":"8-K item numbers (e.g., ['2.02', '9.01'])"},"source_url":{"type":"string","title":"Source Url","description":"SEC EDGAR URL for the filing","default":""},"acceptance_datetime":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Acceptance Datetime","description":"SEC acceptance timestamp (UTC)"},"period_end":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Period End","description":"Quarter/period end date"}},"type":"object","title":"FilingMetadata","description":"Metadata from SEC 8-K filing.\n\nIncludes form type, items covered, SEC source URL, and timing information."},"FilingResponse":{"properties":{"cik":{"type":"string","title":"Cik"},"accession_number":{"type":"string","title":"Accession Number"},"company_name":{"type":"string","title":"Company Name"},"ticker":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Ticker"},"form_type":{"type":"string","title":"Form Type"},"filing_date":{"type":"string","format":"date","title":"Filing Date"},"period_end_date":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Period End Date"},"fiscal_year":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Fiscal Year"},"fiscal_period":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Fiscal Period"},"acceptance_datetime":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Acceptance Datetime"},"interactive_data_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Interactive Data Url"},"items":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Items"},"has_extracted_text":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Has Extracted Text"},"sec_filing_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Sec Filing Url","description":"Generate SEC EDGAR filing index URL.\n\nReturns:\n    URL string if accession_number exists, None otherwise","readOnly":true}},"type":"object","required":["cik","accession_number","company_name","form_type","filing_date","sec_filing_url"],"title":"FilingResponse","description":"SEC filing response.\n\nExtends SECFilingMixin so `sec_filing_url` (the canonical {accession}-index.htm\nEDGAR URL) is computed server-side from cik + accession_number — the\nserver-of-record link the web filings card needs (it derived it client-side\nbefore)."},"FilingSectionSummary":{"properties":{"accession_number":{"type":"string","title":"Accession Number"},"form_type":{"type":"string","title":"Form Type"},"filing_date":{"type":"string","title":"Filing Date"},"fiscal_year":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Fiscal Year"},"fiscal_period":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Fiscal Period"},"sections":{"items":{"$ref":"#/components/schemas/SectionMetadata"},"type":"array","title":"Sections"},"total_sections":{"type":"integer","title":"Total Sections","default":0},"total_tables":{"type":"integer","title":"Total Tables","default":0},"form_subtype":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Form Subtype","description":"8-K sub-type derived from section inventory. One of '8-K-earnings' (has any earnings_* section), '8-K-transcript' (has any transcript_* section), '8-K-event' (has any item_* section), '8-K-other' (8-K with none of the above), or None for non-8-K forms."}},"type":"object","required":["accession_number","form_type","filing_date","sections"],"title":"FilingSectionSummary","description":"Summary of a single filing with its available sections."},"FilingTextChunk":{"properties":{"chunk_id":{"type":"string","title":"Chunk Id"},"ticker":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Ticker"},"cik":{"type":"string","title":"Cik"},"company_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Company Name"},"accession_number":{"type":"string","title":"Accession Number"},"form_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Form Type"},"filing_date":{"type":"string","title":"Filing Date"},"fiscal_year":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Fiscal Year"},"fiscal_period":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Fiscal Period"},"section_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Section Id"},"parent_section_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Parent Section Id"},"section_display_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Section Display Name"},"category":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Category"},"content_text":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Content Text"},"content_raw":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Content Raw"},"text_chars":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Text Chars"},"text_words":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Text Words"},"token_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Token Count"},"chunk_index":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Chunk Index"},"total_chunks":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Total Chunks"},"extraction_strategy":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Extraction Strategy"},"xbrl_concept_found":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Xbrl Concept Found"},"extracted_at":{"type":"string","title":"Extracted At"},"sec_edgar_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Sec Edgar Url"},"section_anchored":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Section Anchored"},"viewer_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Viewer Url"},"source_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source Url"},"transcript_source":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Transcript Source"},"accounting_standard":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Accounting Standard"},"table_json":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Table Json"},"table_caption":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Table Caption"},"table_rows":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Table Rows"},"table_cols":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Table Cols"},"deferred_to":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Deferred To"}},"type":"object","required":["chunk_id","cik","accession_number","filing_date","extracted_at"],"title":"FilingTextChunk","description":"Single text chunk from a filing. Supports chunk, section, and table row types."},"FilingTextRequest":{"properties":{"ticker":{"anyOf":[{"type":"string","maxLength":10},{"type":"null"}],"title":"Ticker","description":"Company ticker symbol"},"cik":{"anyOf":[{"type":"string","pattern":"^\\d{10}$"},{"type":"null"}],"title":"Cik","description":"10-digit CIK"},"accession_number":{"anyOf":[{"type":"string","pattern":"^\\d{10}-\\d{2}-\\d{6}$"},{"type":"null"}],"title":"Accession Number"},"section_id":{"anyOf":[{"type":"string","maxLength":128,"pattern":"^[a-z0-9_]+$"},{"type":"null"}],"title":"Section Id","description":"Section filter (canonical IDs + header-derived sub-section IDs from list_filings)"},"form_type":{"anyOf":[{"type":"string","enum":["10-K","10-Q","10-K/A","10-Q/A","8-K","DEF 14A","20-F","20-F/A","40-F","40-F/A","6-K","6-K/A"]},{"type":"null"}],"title":"Form Type","description":"SEC form type"},"from_date":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"From Date","description":"Start date (inclusive)"},"to_date":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"To Date","description":"End date (inclusive)"},"fiscal_year":{"anyOf":[{"type":"integer","maximum":2100.0,"minimum":2000.0},{"type":"null"}],"title":"Fiscal Year"},"fiscal_period":{"anyOf":[{"type":"string","enum":["Q1","Q2","Q3","FY"]},{"type":"null"}],"title":"Fiscal Period","description":"Fiscal period"},"vantage_date":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Vantage Date","description":"As-of vantage (point-in-time): resolve the latest filing filed ON OR BEFORE this date instead of the newest. Omit for the latest filing. Filings filed after this date are excluded (filing_date <= vantage_date)."},"row_type":{"type":"string","enum":["chunk","section","table"],"title":"Row Type","description":"Content type","default":"chunk"},"since":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Since","description":"Filter by extracted_at >= timestamp (ISO 8601) for incremental sync"},"keyword":{"anyOf":[{"type":"string","maxLength":200,"minLength":2},{"type":"null"}],"title":"Keyword","description":"Keyword filter — returns only chunks containing this text (case-insensitive)"},"limit":{"type":"integer","maximum":1000.0,"minimum":1.0,"title":"Limit","default":100},"offset":{"type":"integer","minimum":0.0,"title":"Offset","default":0}},"type":"object","title":"FilingTextRequest","description":"Query parameters for filing text retrieval."},"FilingTextResponse":{"properties":{"total_results":{"type":"integer","title":"Total Results"},"results":{"items":{"$ref":"#/components/schemas/FilingTextChunk"},"type":"array","title":"Results"},"query":{"$ref":"#/components/schemas/FilingTextRequest"},"execution_time_ms":{"type":"number","title":"Execution Time Ms"},"bytes_processed":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Bytes Processed"},"keyword_matched":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Keyword Matched","description":"True when the supplied keyword matched ≥1 row. False when the service fell back to returning the full section because the keyword matched zero rows. None when no keyword was supplied. Callers (e.g. MCP tools) should annotate the response when False so the caller knows the content is a broader browse view, not a keyword hit."},"keyword_relaxed":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Keyword Relaxed","description":"True when keyword_matched is False AND the no-exact-match browse fallback was RANKED + TRIMMED to the few chunks with the most keyword-token overlap (graded degradation), rather than dumping the full section. Lets callers annotate 'showing the N most relevant chunks' instead of 'showing the full section'. None/absent otherwise."},"keyword_total_matches":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Keyword Total Matches","description":"How many chunks of the pinned section matched the keyword, before pagination; `results` is one page of those matches, in filing order, and `offset` indexes the list of matches. 0 on a keyword miss. None when no keyword was supplied or the request was not pinned to one section of one filing (no total)."},"keyword_ranked_of":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Keyword Ranked Of","description":"On a keyword miss (keyword_matched False) pinned to one section of one filing: how many of the section's chunks were ranked by term overlap to pick the closest (every chunk, up to the 500 cap). `results` is a page of those closest, in filing order; a page past them is empty with this still set (the end of the close matches, not a miss). None otherwise."},"keyword_best_overlap":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Keyword Best Overlap","description":"Set with keyword_ranked_of: how many of the keyword's terms the closest chunk holds. 0 means no chunk holds any term, so the chunks served are the section's first, not close to anything. None otherwise."},"keyword_presence":{"anyOf":[{"$ref":"#/components/schemas/KeywordPresenceResponse"},{"type":"null"}],"description":"#582, inline: when keyword_matched is False, which of the SERVED filing's sections contain the keyword -- the same probe as /filings/sections/keyword-presence, run alongside the browse fallback so the caller needs no second request. None when the keyword matched or no single served filing was probed."},"latest_filing":{"anyOf":[{"$ref":"#/components/schemas/LatestFilingHint"},{"type":"null"}],"description":"Latest filing of the resolved form type for the company. Populated when the service resolved a 'latest' filing for the request (i.e. no accession_number was supplied). Lets callers detect when results come from an older filing (e.g. when the requested section is not present in the latest filing and no fallback was possible)."},"section_fallback":{"anyOf":[{"$ref":"#/components/schemas/SectionFallback"},{"type":"null"}],"description":"Populated when the requested section was not present in the latest filing and the service auto-fell-back to a related section on the same latest filing (currently: MD&A subsections → mda_full). Callers should surface this note in the rendered response so users see what was actually served."},"served_filing":{"anyOf":[{"$ref":"#/components/schemas/LatestFilingHint"},{"type":"null"}],"description":"The filing actually served (accession, filing_date, form_type). Populated on non-empty resolutions so callers see the VINTAGE of what they received — critical when vantage_date was applied or when the latest filing predates the caller's 'now'. Distinct from latest_filing (the newest filing of that form for the company)."},"vantage_date":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Vantage Date","description":"Echo of the as-of vantage applied to this request (ISO date), or None."},"vantage_applied":{"type":"boolean","title":"Vantage Applied","description":"True when a vantage_date upper-bound constrained filing resolution.","default":false},"unextracted_period":{"items":{"$ref":"#/components/schemas/UnextractedPeriodFiling"},"type":"array","title":"Unextracted Period","description":"#582: on an EMPTY response, the filing(s) the XBRL DEI period index (or earnings-8K period derivation) resolved for the requested company/period whose section TEXT was not extracted. NON-EMPTY ⇒ State B (in MetricDuck's scope, text pending — the reported numbers ARE in XBRL; pivot to get_financials/get_xbrl_facts). EMPTY on an otherwise-empty response ⇒ State C (no XBRL period record — terminal 'not retrievable here'). Best-effort: absent when the probe is inapplicable (no fiscal_year/period requested) or errors."},"cross_section_keyword":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Cross Section Keyword","description":"#582: when a keyword matched no chunk in the requested section, the parent_section_ids of THIS filing whose text DOES contain the keyword (same stemming as the per-section match). Empty list ⇒ the term appears in NONE of the filing's servable sections (decisive absence). None ⇒ the cross-section probe did not run (no keyword fallback). Best-effort/optional."},"qa_split":{"anyOf":[{"type":"string","enum":["ir_lead","marker"]},{"type":"null"}],"title":"Qa Split","description":"r102: set when transcript_qa_session was served by splitting the call's stored prepared remarks at read time (most transcripts store the whole call as prepared remarks): 'ir_lead' = cut at the transcript IR's first Q&A turn, 'marker' = cut at the acquirer's Q&A marker (a Q&A header, the operator's hand-off or the first question). None when real qa_session rows (or the IR's text) were served."},"transcript_present":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Transcript Present","description":"r102: on an EMPTY transcript_qa_session response, True when the call's transcript IS stored (accession in transcript_accession) but its Q&A could not be separated from the prepared remarks, which then hold the whole call. None otherwise."},"transcript_accession":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Transcript Accession","description":"r102: the accession whose transcript is stored, when transcript_present."}},"type":"object","required":["total_results","results","query","execution_time_ms"],"title":"FilingTextResponse","description":"Response containing text chunks."},"FullTextFilingMatch":{"properties":{"accession_number":{"type":"string","title":"Accession Number"},"ticker":{"type":"string","title":"Ticker"},"matches":{"items":{"$ref":"#/components/schemas/KeywordMatch"},"type":"array","title":"Matches"},"total_matches":{"type":"integer","title":"Total Matches"},"sections_matched":{"items":{"type":"string"},"type":"array","title":"Sections Matched","description":"Unique section_ids with matches (for quick reference)"},"cik":{"type":"string","title":"Cik"},"form_type":{"type":"string","title":"Form Type"},"filing_date":{"type":"string","title":"Filing Date"}},"type":"object","required":["accession_number","ticker","matches","total_matches","sections_matched","cik","form_type","filing_date"],"title":"FullTextFilingMatch","description":"A single filing matched by company-scoped full-text search.\n\nExtends ``KeywordSearchResult`` (accession + section matches) with the filing\nmetadata that EFTS would otherwise supply (the fallback has no EFTS hit to read\nit from), so the MCP formatter can render identical section drill-in pointers."},"GroupingInstructions":{"properties":{"tree_view":{"additionalProperties":true,"type":"object","title":"Tree View","description":"Tree view configuration","default":{}},"pivot_view":{"additionalProperties":true,"type":"object","title":"Pivot View","description":"Pivot table configuration","default":{}}},"type":"object","title":"GroupingInstructions","description":"Instructions for frontend grouping."},"GuidanceRevision":{"properties":{"metric":{"type":"string","title":"Metric","description":"Metric name (e.g., 'Revenue', 'EPS')"},"period":{"type":"string","title":"Period","description":"Guidance period (e.g., 'FY2026', 'Q2 2025')"},"revision_direction":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Revision Direction","description":"Direction: raised, lowered, maintained, narrowed"},"current_low":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Current Low","description":"Current guidance low"},"current_high":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Current High","description":"Current guidance high"},"current_point":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Current Point","description":"Current guidance point estimate"},"prior_low":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Prior Low","description":"Prior guidance low"},"prior_high":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Prior High","description":"Prior guidance high"},"prior_point":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Prior Point","description":"Prior guidance point estimate"},"current_point_text":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Current Point Text","description":"Qualitative/range current point when not a single number"},"prior_point_text":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Prior Point Text","description":"Qualitative/range prior point when not a single number"},"revision_magnitude_pct":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Revision Magnitude Pct","description":"Magnitude of revision as percentage"},"commentary":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Commentary","description":"Management commentary on revision"}},"type":"object","required":["metric","period"],"title":"GuidanceRevision","description":"Guidance revision tracking (raised/lowered/maintained)."},"GuidanceVsActualResponse":{"properties":{"ticker":{"type":"string","title":"Ticker"},"cik":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cik"},"target_period":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Target Period"},"guidance":{"items":{"$ref":"#/components/schemas/src__routes__companies__guidance_vs_actual__GuidanceItem"},"type":"array","title":"Guidance"},"actuals":{"items":{"$ref":"#/components/schemas/ActualItem"},"type":"array","title":"Actuals"},"comparisons":{"items":{"$ref":"#/components/schemas/Comparison"},"type":"array","title":"Comparisons"},"notes":{"additionalProperties":true,"type":"object","title":"Notes"}},"type":"object","required":["ticker","target_period","guidance","actuals","notes"],"title":"GuidanceVsActualResponse"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"HealthResponse":{"properties":{"status":{"type":"string","title":"Status"},"timestamp":{"type":"number","title":"Timestamp"},"version":{"type":"string","title":"Version"},"environment":{"type":"string","title":"Environment"},"uptime_seconds":{"type":"number","title":"Uptime Seconds"},"instance_id":{"type":"string","title":"Instance Id"},"commit_sha":{"type":"string","title":"Commit Sha"}},"type":"object","required":["status","timestamp","version","environment","uptime_seconds","instance_id","commit_sha"],"title":"HealthResponse","description":"Health check response model"},"HierarchyMetadata":{"properties":{"axis_priority":{"items":{"$ref":"#/components/schemas/AxisPriority"},"type":"array","title":"Axis Priority","description":"Axes ranked by priority","default":[]},"member_trees":{"additionalProperties":{"$ref":"#/components/schemas/AxisTree"},"type":"object","title":"Member Trees","description":"Member trees per axis","default":{}},"grouping_instructions":{"$ref":"#/components/schemas/GroupingInstructions"}},"type":"object","title":"HierarchyMetadata","description":"Top-level hierarchy metadata for frontend reconstruction."},"HighlightItem":{"properties":{"text":{"type":"string","title":"Text"},"signal":{"type":"string","title":"Signal"}},"type":"object","required":["text","signal"],"title":"HighlightItem","description":"Highlight with sentiment signal"},"IREvent":{"properties":{"title":{"type":"string","title":"Title"},"link":{"type":"string","title":"Link"},"published":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Published"},"event_type":{"type":"string","title":"Event Type"},"materiality":{"type":"integer","title":"Materiality","default":3},"facts":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Facts"},"source_id":{"type":"string","title":"Source Id"},"ticker":{"type":"string","title":"Ticker"},"source_count":{"type":"integer","title":"Source Count","default":1}},"type":"object","required":["title","link","event_type","source_id","ticker"],"title":"IREvent","description":"Classified IR event from feed item (deduplicated by event key)"},"IREventsResponse":{"properties":{"ticker":{"type":"string","title":"Ticker"},"company_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Company Name"},"events":{"items":{"$ref":"#/components/schemas/IREvent"},"type":"array","title":"Events"},"count":{"type":"integer","title":"Count"}},"type":"object","required":["ticker","events","count"],"title":"IREventsResponse","description":"Response for IR events endpoint"},"IncomeStatementItem":{"properties":{"primary_document":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Primary Document"},"cik":{"type":"string","title":"Cik"},"accession_number":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Accession Number"},"date":{"type":"string","title":"Date"},"symbol":{"type":"string","title":"Symbol"},"filing_date":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Filing Date"},"fiscal_year":{"type":"integer","title":"Fiscal Year"},"period":{"type":"string","title":"Period"},"industry":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Industry"},"original_accession_number":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Original Accession Number"},"revised_after_vantage":{"type":"boolean","title":"Revised After Vantage","default":false},"source_attribution":{"anyOf":[{"additionalProperties":{"items":{"type":"string"},"type":"array"},"type":"object"},{"type":"null"}],"title":"Source Attribution"},"metric_basis":{"anyOf":[{"additionalProperties":{"type":"string"},"type":"object"},{"type":"null"}],"title":"Metric Basis"},"reporting_currency":{"type":"string","title":"Reporting Currency","default":"USD"},"metrics":{"additionalProperties":{"anyOf":[{"type":"number"},{"type":"null"}]},"type":"object","title":"Metrics","default":{}},"sec_document_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Sec Document Url","readOnly":true},"sec_filing_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Sec Filing Url","description":"Generate SEC EDGAR filing index URL.\n\nReturns:\n    URL string if accession_number exists, None otherwise","readOnly":true}},"type":"object","required":["cik","date","symbol","fiscal_year","period","sec_document_url","sec_filing_url"],"title":"IncomeStatementItem","description":"Individual income statement period data"},"IndustryResponse":{"properties":{"industry_code":{"type":"string","title":"Industry Code"},"industry_name":{"type":"string","title":"Industry Name"},"sector_code":{"type":"string","title":"Sector Code"}},"type":"object","required":["industry_code","industry_name","sector_code"],"title":"IndustryResponse","description":"Industry information"},"IndustryTaxonomyItem":{"properties":{"code":{"type":"string","title":"Code"},"name":{"type":"string","title":"Name"}},"type":"object","required":["code","name"],"title":"IndustryTaxonomyItem","description":"Industry in taxonomy hierarchy"},"IndustryWithCountResponse":{"properties":{"industry_code":{"type":"string","title":"Industry Code"},"industry_name":{"type":"string","title":"Industry Name"},"sector_code":{"type":"string","title":"Sector Code"},"company_count":{"type":"integer","title":"Company Count"}},"type":"object","required":["industry_code","industry_name","sector_code","company_count"],"title":"IndustryWithCountResponse","description":"Industry information with company count"},"IrCompanyEvent":{"properties":{"event_key":{"type":"string","title":"Event Key","description":"Opaque, stable event id (the permalink key). NOT a fiscal-tuple slug."},"event_type":{"type":"string","title":"Event Type","description":"What happened (open vocab): earnings | annual_meeting | conference | investor_day | other. Render an unrecognized value generically."},"source_title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source Title","description":"VERBATIM event title from the IR source (never rewritten)."},"occurred_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Occurred At","description":"Event datetime, ISSUER-LOCAL and timezone-naive (no tz conversion). Pair with time_precision; do not assume UTC. NOTE (#1383): the source clock-time's locale can vary between events of the same issuer (not yet normalized) — render the DATE as authoritative and treat the clock time as low-confidence; never convert to viewer-local."},"time_precision":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Time Precision","description":"'exact' (a real clock time) | 'date' (day only) | 'unknown'."},"fiscal_year":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Fiscal Year","description":"Best-effort fiscal year (title-parsed; DISPLAY only)."},"fiscal_period":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Fiscal Period","description":"Best-effort bare fiscal quarter (title-parsed; see period_source). DISPLAY metadata — not an event key."},"period_source":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Period Source"},"webcast_link":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Webcast Link","description":"Live/recorded webcast URL, if any."},"location":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Location"},"detail_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Detail Url","description":"IR-site event detail page, if any."},"materials":{"items":{"$ref":"#/components/schemas/EventMaterial"},"type":"array","title":"Materials"}},"type":"object","required":["event_key","event_type"],"title":"IrCompanyEvent"},"IrDeck":{"properties":{"doc_id":{"type":"string","title":"Doc Id","description":"Stable deterministic item identity ('{cik10}:u:{sha1(url)}'). Dedup-safe across URL variants; the join/reference key. NOT an event key."},"doc_kind":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Doc Kind","description":"Item type — 'presentation' or 'guidance' (the served kinds). Pipeline-classified; the surface gate."},"ticker":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Ticker"},"cik":{"type":"string","title":"Cik"},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Title","description":"Catalog title (e.g., 'Presentation') when known"},"doc_date":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Doc Date","description":"Fiscal-period ANCHOR date (YYYY-MM-DD) — a synthetic period-END date, NOT the real publish/upload date, and ~24% NULL. Display via fiscal_year/fiscal_period; never render as 'Published {date}' or plot it on a real-time axis (the real event datetime lives on /companies/{ticker}/events occurred_at)."},"fiscal_year":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Fiscal Year","description":"Best-effort fiscal year (int) parsed from the deck; may be null."},"fiscal_period":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Fiscal Period","description":"Best-effort BARE fiscal quarter ('Q1'..'Q4' or 'FY'); pair with fiscal_year. Filename/feed-parsed DISCOVERY metadata — may be null; NOT an event key (do not group events on it server-side)."},"url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Url","description":"RUNG 1 — original IR-hosted source URL (freshest/complete; provenance). Fetch + read this yourself if you can."},"gcs_uri":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Gcs Uri","description":"RUNG 2 — stable MetricDuck-hosted copy (gs:// URI). Present when we mirrored the deck; fetch THIS if the original url is unreachable / bot-walled / link-rotted — it's the identical bytes, immune to those."},"mirrored":{"type":"boolean","title":"Mirrored","description":"True when a stable mirrored copy (gcs_uri) exists — i.e. MetricDuck successfully fetched the deck, so an agent-fetchable path is guaranteed.","default":false},"total_pages":{"type":"integer","title":"Total Pages","description":"Total extracted pages in this deck","default":0},"pages":{"items":{"$ref":"#/components/schemas/IrDeckPage"},"type":"array","title":"Pages","description":"RUNG 3 — MetricDuck-extracted slide text (most reliable: pre-parsed, no fetch/parse needed, immune to bot-walls). When `query` given: only matching pages; else a bounded prefix. Empty when text isn't extracted yet (use rung 1/2)."},"pages_matched":{"type":"integer","title":"Pages Matched","description":"Count of pages matching the query (0 when no query)","default":0},"pages_truncated":{"type":"boolean","title":"Pages Truncated","description":"True when more pages exist than were returned (raise/refine the query, or read the deck via url/gcs_uri).","default":false}},"type":"object","required":["doc_id","cik"],"title":"IrDeck","description":"One served IR document (presentation deck or guidance doc) and (optionally) its\nmatching slide text. `doc_kind` types the item; `doc_id` is its stable identity."},"IrDeckCoverage":{"properties":{"count":{"type":"integer","title":"Count","description":"Distinct catalogued presentation decks"},"latest_date":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Latest Date","description":"Most-recent deck date (YYYY-MM-DD)"},"latest_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Latest Url","description":"Source URL of the most-recent deck"},"unavailable":{"type":"boolean","title":"Unavailable","description":"True when the coverage LOOKUP failed (timeout/quota/byte-cap) — a distinct state from a genuine zero (#1264). Consumers MUST render 'coverage unavailable', never conflate it with 'not catalogued' (a failed check is not a real zero).","default":false}},"type":"object","required":["count"],"title":"IrDeckCoverage","description":"IR investor-presentation coverage — catalogued decks the agent can read."},"IrDeckPage":{"properties":{"page":{"type":"integer","title":"Page","description":"1-based page number within the deck"},"text":{"type":"string","title":"Text","description":"Extracted slide text (may be truncated)"},"truncated":{"type":"boolean","title":"Truncated","description":"True when text was capped at the per-page char limit","default":false}},"type":"object","required":["page","text"],"title":"IrDeckPage","description":"A single slide/page of extracted deck text."},"IrDocumentsResponse":{"properties":{"ticker":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Ticker"},"cik":{"type":"string","title":"Cik"},"company_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Company Name"},"query":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Query"},"decks":{"items":{"$ref":"#/components/schemas/IrDeck"},"type":"array","title":"Decks"},"total_decks":{"type":"integer","title":"Total Decks","default":0},"source_access":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source Access","description":"Honest reachability hint for the issuer's IR SITE (from the resolver's ir_reachability) so an agent doesn't thrash fetching a dead/bot-walled source — e.g. 'bot_walled' (prefer the mirrored copy / extracted text) or 'live'."},"note":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Note","description":"Coverage note when a catalog deck exists but its text is not yet extracted, when no decks matched, or when the response's page budget left decks out (how many, and how to reach them)."}},"type":"object","required":["cik"],"title":"IrDocumentsResponse"},"KeywordMatch":{"properties":{"section_id":{"type":"string","title":"Section Id","description":"Section containing the match (e.g., risk_factors)"},"display_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Display Name","description":"Human-readable section name"},"chunk_index":{"type":"integer","title":"Chunk Index","description":"Chunk position within section (0-based)"},"total_chunks":{"type":"integer","title":"Total Chunks","description":"Total chunks in this section"},"text_words":{"type":"integer","title":"Text Words","description":"Word count of this chunk","default":0},"snippet":{"type":"string","title":"Snippet","description":"First ~300 chars of matching chunk content"}},"type":"object","required":["section_id","chunk_index","total_chunks","snippet"],"title":"KeywordMatch","description":"A single chunk matching a keyword search."},"KeywordPresenceResponse":{"properties":{"accession_number":{"type":"string","title":"Accession Number"},"keyword":{"type":"string","title":"Keyword"},"matched_sections":{"items":{"type":"string"},"type":"array","title":"Matched Sections","description":"parent_section_ids of THIS filing whose chunk text contains the keyword (stemmed). Empty ⇒ absent in every servable section."},"all_sections":{"items":{"type":"string"},"type":"array","title":"All Sections","description":"The filing's servable section_ids (so the caller can name 'NONE of a, b, c…')."},"terms":{"type":"integer","title":"Terms","description":"How many independent terms the matcher ANDs, order-free (a compound such as '5.750%' or 'R&D' is one term). Lets the caller describe the match without re-tokenizing.","default":0}},"type":"object","required":["accession_number","keyword","matched_sections","all_sections"],"title":"KeywordPresenceResponse","description":"#582: which of ONE filing's servable sections contain a keyword.\n\nPowers get_filing_section's decisive cross-section verdict — when a keyword\nmisses in the requested section, the worker asks here to say either \"it's in\nsibling X\" (one pivot) or \"it appears in NONE of these N sections\" (terminal\nabsence) instead of dumping ranked tangential chunks + a \"refine/browse\" nudge.\n`matched_sections` uses the SAME stemming as the per-section keyword filter, so\nthe verdict can never contradict the served browse."},"KeywordSearchResult":{"properties":{"accession_number":{"type":"string","title":"Accession Number"},"ticker":{"type":"string","title":"Ticker"},"matches":{"items":{"$ref":"#/components/schemas/KeywordMatch"},"type":"array","title":"Matches"},"total_matches":{"type":"integer","title":"Total Matches"},"sections_matched":{"items":{"type":"string"},"type":"array","title":"Sections Matched","description":"Unique section_ids with matches (for quick reference)"}},"type":"object","required":["accession_number","ticker","matches","total_matches","sections_matched"],"title":"KeywordSearchResult","description":"Keyword search results for a single filing."},"LatestCallCoverage":{"properties":{"fiscal_period":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Fiscal Period","description":"e.g. 'Q3'"},"fiscal_year":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Fiscal Year","description":"Fiscal year of the latest servable call"},"event_date":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Event Date","description":"Earnings-call date (YYYY-MM-DD)"},"provenance_tier":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Provenance Tier","description":"Source credibility tier: sec_filed | issuer_published | machine_reconstructed | unrecorded (null if unknown)"},"viewer_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Viewer Url","description":"In-app transcript viewer URL"},"analyzed":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Analyzed","description":"False when the transcript is TEXT_STORED — text captured and the viewer page rendered, L2 signals deferred. The link is real either way (#1874)."}},"type":"object","title":"LatestCallCoverage","description":"The most-recent earnings call with a rendered transcript (coverage-card header).\n\n#1874: 'most-recent SERVABLE', not 'most-recent COMPLETED' — a TEXT_STORED call has\ncaptured text and a rendered viewer page, so it is linkable; gating on COMPLETED made\nthe card show a months-stale quarter (BAC: newest 2026-07-14, card showed 2026-01-14)."},"LatestFilingHint":{"properties":{"accession_number":{"type":"string","title":"Accession Number"},"filing_date":{"type":"string","title":"Filing Date"},"form_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Form Type"},"text_extracted":{"type":"boolean","title":"Text Extracted","default":true}},"type":"object","required":["accession_number","filing_date"],"title":"LatestFilingHint","description":"Pointer to the latest filing of a given form type for a company.\n\nPopulated on latest-resolution paths so callers can detect when a section\nrequest was satisfied against a filing OTHER than the latest — previously\na silent failure mode that returned prior-year content under the\n`get_filing_section` contract."},"LineageAnnualization":{"properties":{"factor":{"type":"number","title":"Factor","description":"Multiplier the engine applied (4 numerator-flow, 0.25 denominator-flow)"},"note":{"type":"string","title":"Note","description":"Human explanation of the annualization step"}},"type":"object","required":["factor","note"],"title":"LineageAnnualization","description":"#1041: the engine-level quarterly annualization step, made explicit.\n\nFor `annualize_quarterly` metrics the processor scales the FORMULA RESULT on\nquarterly rows AFTER evaluation (engine_context.py) — so\n`output.value == (formula applied to inputs) × factor`. #1060: `factor` is\ndirectional — 4 for numerator-flow ratios, 0.25 (÷4) for denominator-flow\nratios (net_debt_to_ebitda, useful_life_proxy). Without this field the\ndisplayed derivation is off (CAT roic Q1 FY2026: inputs said 3.86%, value said\n15.45%). `formula`/`inputs` stay raw on purpose: they match what drilling each\ninput returns."},"LineageDimension":{"properties":{"scale":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Scale","description":"'actual' — api serves absolute values"},"currency":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Currency","description":"As-filed ISO-4217 (USD/BRL…) for monetary figures; null otherwise"},"period":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Period","description":"Fiscal period label, e.g. 'Q2 FY2025'"}},"type":"object","title":"LineageDimension"},"LineageHandle":{"properties":{"mdck":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Mdck","description":"Stable mdck:// filing handle"},"edgar":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Edgar","description":"SEC EDGAR filing-index URL (primary source)"},"viewer":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Viewer","description":"Always null (founder D40.2): a filing-level viewer link opened <accession>/index.htm, a 404. Use `edgar`."}},"type":"object","title":"LineageHandle"},"LineageInput":{"properties":{"symbol":{"type":"string","title":"Symbol","description":"Input metric id / XBRL concept (base concepts colon-stripped). This is the concept's LOCAL NAME without its taxonomy prefix, so it does not distinguish us-gaap from ifrs-full from a company extension. NOTE the list this belongs to is every concept that RESOLVED in expression order, not the coalesce's choice — see the module docstring; inputs[0] is not the winner."},"display_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Display Name","description":"Human name (metric_definitions)"},"value":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Value","description":"Byte-exact value the evaluator consumed"},"dimension":{"anyOf":[{"$ref":"#/components/schemas/LineageDimension"},{"type":"null"}]},"source":{"$ref":"#/components/schemas/LineageSource"},"as_filed":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"As Filed","description":"r103: the figure as the cited filing states it, when a stock split since that filing was applied (the filer's own tagged ratio, confirmed by its restated comparatives) — `value` is then on one share basis with the rest of the series. Absent otherwise."},"split_factor":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Split Factor","description":"r103: the filed split ratio applied to `as_filed` (per-share figures are divided by it, share counts multiplied). Absent when no split was applied."},"partial":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Partial","description":"#2130: for a DERIVED input — true = an arithmetic-composed derivation at or below this input genuinely missed an arm at compute time (drill it before treating this node's figure as fully decomposed); false = trusted-complete; null = base input, or NOT ASSESSABLE (the input's row could not be located, or it is chain-style — if/coalesce — whose stored completeness flag is structural). Completeness is never asserted from a structural flag."}},"type":"object","required":["symbol","source"],"title":"LineageInput"},"LineageNode":{"properties":{"output":{"$ref":"#/components/schemas/LineageOutput"},"formula":{"type":"string","title":"Formula","description":"Human, fully-parenthesized expression (NOT internal notation)"},"inputs":{"items":{"$ref":"#/components/schemas/LineageInput"},"type":"array","title":"Inputs"},"annualization":{"anyOf":[{"$ref":"#/components/schemas/LineageAnnualization"},{"type":"null"}],"description":"Present on quarterly rows of annualized metrics: output.value = formula(inputs) × factor"},"gloss":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Gloss","description":"Optional one-line plain-text courtesy"},"partial":{"type":"boolean","title":"Partial","description":"True when some immediate inputs were unresolved at compute time, OR (#2130) when an ARITHMETIC-composed input's derivation below is genuinely partial (transitive over required-operand-rooted formulas only — chain-style formulas enumerate alternatives, so their stored flags are structural and reported per-input as null/not-assessable instead of ORed into this flag). partial:false therefore means no PROVEN incompleteness — check per-input `partial` for what could not be assessed.","default":false}},"type":"object","required":["output","formula"],"title":"LineageNode"},"LineageOutput":{"properties":{"metric":{"type":"string","title":"Metric"},"display_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Display Name"},"value":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Value"},"dimension":{"anyOf":[{"$ref":"#/components/schemas/LineageDimension"},{"type":"null"}]},"kind":{"type":"string","title":"Kind","description":"A node exists only for computed (derived) figures","default":"derived"}},"type":"object","required":["metric"],"title":"LineageOutput"},"LineageSource":{"properties":{"kind":{"type":"string","title":"Kind","description":"'base' (an XBRL fact) or 'derived' (another computed metric)"},"handle":{"anyOf":[{"$ref":"#/components/schemas/LineageHandle"},{"type":"null"}],"description":"Filing handle for a base input; drill to the fact via get_xbrl_facts"},"accession":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Accession","description":"Source SEC accession (base inputs)"}},"type":"object","required":["kind"],"title":"LineageSource"},"ManagementAssessment":{"properties":{"overall_tone":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Overall Tone","description":"Tone: confident, cautious, defensive, evasive"},"tone_confidence":{"anyOf":[{"type":"number","maximum":1.0,"minimum":0.0},{"type":"null"}],"title":"Tone Confidence","description":"Confidence in tone assessment (0.0-1.0)"},"disclosure_quality":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Disclosure Quality","description":"Disclosure quality: transparent, adequate, opaque"},"strategy_clarity":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Strategy Clarity","description":"Strategy clarity: clear, adequate, unclear"},"specific_vs_vague":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Specific Vs Vague","description":"Specificity: highly_specific, specific, vague, very_vague"},"key_strategic_themes":{"items":{"type":"string"},"type":"array","title":"Key Strategic Themes","description":"Key strategic themes mentioned"},"positive_language_examples":{"items":{"type":"string"},"type":"array","title":"Positive Language Examples","description":"Examples of positive language used"},"new_risks_mentioned":{"items":{"type":"string"},"type":"array","title":"New Risks Mentioned","description":"New risks mentioned in this release"}},"type":"object","title":"ManagementAssessment","description":"Management tone and disclosure quality analysis."},"MarginMetric":{"properties":{"current":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Current","description":"Current period margin as percentage"},"prior_year":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Prior Year","description":"Prior year period margin as percentage"},"change_bps":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Change Bps","description":"Year-over-year change in basis points (100 bps = 1.0%)"}},"type":"object","title":"MarginMetric","description":"Margin metric in percentage terms with YoY change in basis points.\n\nExample:\n    Gross margin: 10.85% current, 10.42% prior year → +43 bps"},"MarketDataPoint":{"properties":{"trade_date":{"type":"string","format":"date","title":"Trade Date","description":"Trading date"},"ticker":{"type":"string","title":"Ticker","description":"Stock ticker symbol"},"open":{"anyOf":[{"type":"number","minimum":0.0},{"type":"null"}],"title":"Open","description":"Opening price"},"high":{"anyOf":[{"type":"number","minimum":0.0},{"type":"null"}],"title":"High","description":"Daily high price"},"low":{"anyOf":[{"type":"number","minimum":0.0},{"type":"null"}],"title":"Low","description":"Daily low price"},"close":{"anyOf":[{"type":"number","minimum":0.0},{"type":"null"}],"title":"Close","description":"Closing price (unadjusted)"},"adj_close":{"anyOf":[{"type":"number","minimum":0.0},{"type":"null"}],"title":"Adj Close","description":"Adjusted closing price"},"volume":{"anyOf":[{"type":"integer","minimum":0.0},{"type":"null"}],"title":"Volume","description":"Trading volume in shares"},"vwap":{"anyOf":[{"type":"number","minimum":0.0},{"type":"null"}],"title":"Vwap","description":"Volume-weighted average price"}},"type":"object","required":["trade_date","ticker"],"title":"MarketDataPoint","description":"Individual daily market data point"},"MarketDataResponse":{"properties":{"ticker":{"type":"string","title":"Ticker","description":"Stock ticker symbol"},"company_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Company Name","description":"Company name"},"requested_ticker":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Requested Ticker","description":"The ticker the caller asked for, when it was an alias"},"is_alias":{"type":"boolean","title":"Is Alias","description":"True when `ticker` was substituted for `requested_ticker`","default":false},"request_start_date":{"type":"string","format":"date","title":"Request Start Date","description":"Requested start date"},"request_end_date":{"type":"string","format":"date","title":"Request End Date","description":"Requested end date"},"data_points":{"items":{"$ref":"#/components/schemas/MarketDataPoint"},"type":"array","title":"Data Points","description":"Daily market data points"},"summary":{"$ref":"#/components/schemas/MarketDataSummary","description":"Summary statistics"},"shares_outstanding":{"anyOf":[{"$ref":"#/components/schemas/SharesOutstandingInfo"},{"type":"null"}],"description":"Latest reported period-end share count <= request end date"},"market_cap_at_close":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Market Cap At Close","description":"Latest close in range x shares_outstanding.value (same share basis)"},"metadata":{"additionalProperties":true,"type":"object","title":"Metadata","description":"Additional metadata"}},"type":"object","required":["ticker","request_start_date","request_end_date","data_points","summary"],"title":"MarketDataResponse","description":"Complete market data response"},"MarketDataSummary":{"properties":{"price_attribution":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Price Attribution","description":"The price source's required attribution, present only when the prices in this response come from a source that requires one (IEX HIST)."},"trading_days":{"type":"integer","title":"Trading Days","description":"Number of trading days with data"},"first_date":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"First Date","description":"First available trading date"},"last_date":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Last Date","description":"Last available trading date"},"min_price":{"anyOf":[{"type":"number","minimum":0.0},{"type":"null"}],"title":"Min Price","description":"Lowest intraday low in the period, split-adjusted to the last bar's basis where the stored basis is known"},"max_price":{"anyOf":[{"type":"number","minimum":0.0},{"type":"null"}],"title":"Max Price","description":"Highest intraday high in the period, split-adjusted to the last bar's basis where the stored basis is known"},"avg_close":{"anyOf":[{"type":"number","minimum":0.0},{"type":"null"}],"title":"Avg Close","description":"Average close, split-adjusted to the last bar's basis where the stored basis is known"},"avg_volume":{"anyOf":[{"type":"integer","minimum":0.0},{"type":"null"}],"title":"Avg Volume","description":"Average volume, in shares of the last bar's basis where the stored basis is known"},"avg_vwap":{"anyOf":[{"type":"number","minimum":0.0},{"type":"null"}],"title":"Avg Vwap","description":"Average VWAP, split-adjusted to the last bar's basis where the stored basis is known"},"price_volatility":{"anyOf":[{"type":"number","minimum":0.0},{"type":"null"}],"title":"Price Volatility","description":"Std dev of the close split-adjusted to the last bar's basis where the stored basis is known"}},"type":"object","required":["trading_days"],"title":"MarketDataSummary","description":"Summary statistics for market data"},"MaterialEvent":{"properties":{"event_type":{"type":"string","title":"Event Type","description":"Event type: acquisition, divestiture, regulatory, restructuring, legal"},"description":{"type":"string","title":"Description","description":"Description of the event"},"counterparty":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Counterparty","description":"Counterparty involved (e.g., acquired company)"},"value_millions":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Value Millions","description":"Transaction value in millions USD"},"status":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Status","description":"Status: pending, closed, announced"},"signal":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Signal","description":"Signal: positive, negative, attention"}},"type":"object","required":["event_type","description"],"title":"MaterialEvent","description":"Material corporate event (M&A, regulatory, restructuring)."},"MemberNode":{"properties":{"member":{"type":"string","title":"Member","description":"Member QName"},"label":{"type":"string","title":"Label","description":"Display label"},"order":{"type":"number","title":"Order","description":"Presentation order"},"depth":{"type":"integer","title":"Depth","description":"Hierarchy depth (0=root)"},"parent":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Parent","description":"Parent member QName"},"children":{"items":{"type":"string"},"type":"array","title":"Children","description":"Child member QNames","default":[]}},"type":"object","required":["member","label","order","depth"],"title":"MemberNode","description":"Member in hierarchy tree."},"MetricBenchmarkList":{"properties":{"metric_id":{"type":"string","title":"Metric Id","description":"Metric identifier (e.g., 'gross_margin')"},"metric_name":{"type":"string","title":"Metric Name","description":"Human-readable metric name"},"metric_unit":{"type":"string","title":"Metric Unit","description":"Unit of measurement (e.g., 'percent', 'ratio', 'usd')"},"metric_description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Metric Description","description":"Description of what this metric measures"},"benchmarks":{"items":{"$ref":"#/components/schemas/src__models__benchmarks__MetricBenchmark"},"type":"array","title":"Benchmarks","description":"List of sector benchmarks"},"total_sectors":{"type":"integer","title":"Total Sectors","description":"Total number of sectors included"},"total_companies":{"type":"integer","title":"Total Companies","description":"Total companies across all sectors"},"period":{"type":"string","title":"Period","description":"Period type for all benchmarks"},"generated_at":{"type":"string","title":"Generated At","description":"Timestamp when benchmarks were generated"}},"type":"object","required":["metric_id","metric_name","metric_unit","benchmarks","total_sectors","total_companies","period","generated_at"],"title":"MetricBenchmarkList","description":"Response model for sector benchmark list endpoint.\n\nReturns all sector benchmarks with metric metadata."},"MetricCatalogItem":{"properties":{"metric_id":{"type":"string","title":"Metric Id"},"display_name":{"type":"string","title":"Display Name"},"description":{"type":"string","title":"Description"},"category":{"type":"string","title":"Category"},"subcategory":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Subcategory"},"data_type":{"type":"string","title":"Data Type"},"temporal_type":{"type":"string","title":"Temporal Type"},"is_derived":{"type":"boolean","title":"Is Derived"},"is_highlighted":{"type":"boolean","title":"Is Highlighted"},"hide_if_all_null":{"type":"boolean","title":"Hide If All Null"},"search_tags":{"items":{"type":"string"},"type":"array","title":"Search Tags","default":[]},"aliases":{"items":{"type":"string"},"type":"array","title":"Aliases","default":[]},"depends_on":{"items":{"type":"string"},"type":"array","title":"Depends On","default":[]},"related_metrics":{"items":{"type":"string"},"type":"array","title":"Related Metrics","default":[]},"formatting_config":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Formatting Config"},"formula_plain_english":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Formula Plain English"},"expression":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Expression"}},"type":"object","required":["metric_id","display_name","description","category","subcategory","data_type","temporal_type","is_derived","is_highlighted","hide_if_all_null"],"title":"MetricCatalogItem","description":"Enhanced metric metadata for metric picker"},"MetricCatalogResponse":{"properties":{"metrics":{"items":{"$ref":"#/components/schemas/MetricCatalogItem"},"type":"array","title":"Metrics"},"total_count":{"type":"integer","title":"Total Count"},"categories":{"items":{"type":"string"},"type":"array","title":"Categories"}},"type":"object","required":["metrics","total_count","categories"],"title":"MetricCatalogResponse","description":"Metrics catalog response for metric picker"},"MetricData":{"properties":{"display_name":{"type":"string","title":"Display Name","description":"Human-readable metric name"},"unit":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Unit","description":"Unit type (usd, pct, ratio)"},"values":{"items":{"$ref":"#/components/schemas/MetricValue"},"type":"array","title":"Values","description":"Historical values"}},"type":"object","required":["display_name"],"title":"MetricData","description":"Metric data with metadata and historical values"},"MetricFilter":{"properties":{"metric_id":{"type":"string","title":"Metric Id","description":"Metric identifier (e.g., 'pe_ratio')"},"period_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Period Type","description":"Period type: 'ttm', 'ss', or growth metrics like 'ttm.yoy'","default":"ttm"},"operator":{"type":"string","title":"Operator","description":"Comparison operator: lt, lte, gt, gte, eq, between"},"value":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Value","description":"Single value for lt/lte/gt/gte/eq operators"},"min_value":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Min Value","description":"Minimum value for 'between' operator"},"max_value":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Max Value","description":"Maximum value for 'between' operator"}},"type":"object","required":["metric_id","operator"],"title":"MetricFilter","description":"A single metric filter condition"},"MetricHistoryPoint":{"properties":{"period_end":{"type":"string","format":"date","title":"Period End","description":"Period end date (fiscal)"},"value":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Value","description":"Metric value at this period"},"fiscal_year":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Fiscal Year","description":"Fiscal year"},"fiscal_period":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Fiscal Period","description":"Fiscal period label (Q1, Q2, Q3, Q4, FY)"},"accession_number":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Accession Number","description":"SEC accession that sourced this value, for citation"},"original_accession_number":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Original Accession Number","description":"The originally-filed (pre-amendment) accession, when accession_number above cites a later restating amendment instead (#959). Null for normal (non-restated) periods."},"revised_after_vantage":{"type":"boolean","title":"Revised After Vantage","description":"VANTAGE PATH ONLY. True when the period's OWN filing was amended after the requested vantage_date (a later filing of that period, e.g. a 10-K/A, restates it) — so the served value may include a revision that was NOT knowable as of that date, even though the citation correctly names a pre-vantage filing. NOT set for a later filing's comparative recast (e.g. the next 10-K's prior-year column): filing_metrics stores exactly one CURRENT version of history, so that value is served too, unflagged. For the value as known at the vantage use get_xbrl_facts pinned to the latest filing on or before it that reports the period; get_xbrl_facts(period_history=true) gives the as-originally-filed value. Always False when no vantage_date was supplied.","default":false},"currency":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Currency","description":"As-filed reporting currency (ISO-4217, e.g. USD/BRL) for monetary metrics; null for non-monetary metrics (ratios/percentages/counts). #728 PR-2."},"sec_document_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Sec Document Url","description":"The filing document this value was tagged in (the 10-Q/10-K page that carries it), ahead of the filing index. Null when the filing has no iXBRL document on record; cite the accession's index then (D40.2)."},"basis_concept":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Basis Concept","description":"The XBRL concept this value was actually taken from, when a coalesce chain resolved to something OTHER than the concept the metric's label names (#2149) — e.g. shares_diluted served from WeightedAverageNumberOfSharesOutstandingBasic because the filer never tagged the diluted concept. \"unknown\" when the row predates lineage capture. Null when the label's own concept won, i.e. no ambiguity arose."}},"type":"object","required":["period_end"],"title":"MetricHistoryPoint","description":"Single observation in a metric's time series."},"MetricHistorySeries":{"properties":{"metric_id":{"type":"string","title":"Metric Id"},"display_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Display Name","description":"Human-readable name from metric_definitions"},"unit":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Unit","description":"Unit (ratio, USD, percent, etc.)"},"points":{"items":{"$ref":"#/components/schemas/MetricHistoryPoint"},"type":"array","title":"Points","description":"Observations ordered by period_end DESC, capped at `window`"},"comparability_note":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Comparability Note","description":"#1149: set for operating KPIs whose definition varies by industry (e.g. passenger_load_factor, gross_booking_value). Each issuer's own value is correct, but the id is NOT comparable across companies."}},"type":"object","required":["metric_id"],"title":"MetricHistorySeries","description":"Time series for a single metric_id, newest-first."},"MetricItem":{"properties":{"name":{"type":"string","title":"Name"},"displayName":{"type":"string","title":"Displayname"},"description":{"type":"string","title":"Description"},"unit":{"type":"string","title":"Unit"},"dataType":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Datatype"},"temporalType":{"type":"string","title":"Temporaltype"},"isDerived":{"type":"boolean","title":"Isderived"}},"type":"object","required":["name","displayName","description","unit","temporalType","isDerived"],"title":"MetricItem","description":"Individual metric metadata"},"MetricLineageResponse":{"properties":{"price_attribution":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Price Attribution","description":"The price source's required attribution, present only when the prices in this response come from a source that requires one (IEX HIST)."},"ticker":{"type":"string","title":"Ticker"},"cik":{"type":"string","title":"Cik"},"company_name":{"type":"string","title":"Company Name"},"metric":{"type":"string","title":"Metric"},"period_type":{"$ref":"#/components/schemas/PeriodType"},"fiscal_year":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Fiscal Year"},"fiscal_period":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Fiscal Period"},"lineage":{"anyOf":[{"$ref":"#/components/schemas/LineageNode"},{"type":"null"}],"description":"The derivation node; null when no lineage is available (see `note`)"},"note":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Note","description":"Informative affordance, present only when `lineage` is null"},"component_absent":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Component Absent","description":"r117: set when this value is built from a component the filer does not report, which the formula engine read as zero (#3071). `lineage.output.value` is then null and the formula and resolved inputs stay as the evidence; get_metric_history withholds the same point with the same sentence."}},"type":"object","required":["ticker","cik","company_name","metric","period_type"],"title":"MetricLineageResponse"},"MetricSEOResponse":{"properties":{"metric_id":{"type":"string","title":"Metric Id"},"display_name":{"type":"string","title":"Display Name"},"description":{"type":"string","title":"Description"},"category":{"type":"string","title":"Category"},"subcategory":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Subcategory"},"seo_slug":{"type":"string","title":"Seo Slug"},"seo_keywords":{"items":{"type":"string"},"type":"array","title":"Seo Keywords","default":[]},"aliases":{"items":{"type":"string"},"type":"array","title":"Aliases","default":[]},"formula_plain_english":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Formula Plain English"},"use_cases":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Use Cases"},"interpretation_guidance":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Interpretation Guidance"},"typical_range":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Typical Range"},"example_interpretation":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Example Interpretation"},"industry_notes":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Industry Notes"},"related_metrics":{"items":{"type":"string"},"type":"array","title":"Related Metrics","default":[]},"depends_on":{"items":{"type":"string"},"type":"array","title":"Depends On","default":[]},"data_type":{"type":"string","title":"Data Type"},"temporal_type":{"type":"string","title":"Temporal Type"},"is_derived":{"type":"boolean","title":"Is Derived"}},"type":"object","required":["metric_id","display_name","description","category","subcategory","seo_slug","data_type","temporal_type","is_derived"],"title":"MetricSEOResponse","description":"SEO-optimized metric metadata for blog/glossary pages"},"MetricValue":{"properties":{"period":{"type":"string","title":"Period","description":"Period type (TTM, Q1 2024, FY 2023)"},"period_end":{"type":"string","title":"Period End","description":"Period end date (YYYY-MM-DD)"},"value":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Value","description":"Metric value"},"dimension":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Dimension","description":"Compound period type dimension (Q.TREND8, Q.MED8, TTM.YOY, etc.)"}},"type":"object","required":["period","period_end"],"title":"MetricValue","description":"Single metric value for a period"},"MetricsHistoryResponse":{"properties":{"price_attribution":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Price Attribution","description":"The price source's required attribution, present only when the prices in this response come from a source that requires one (IEX HIST)."},"ticker":{"type":"string","title":"Ticker"},"cik":{"type":"string","title":"Cik"},"company_name":{"type":"string","title":"Company Name"},"period_type":{"$ref":"#/components/schemas/PeriodType"},"window":{"type":"integer","title":"Window","description":"Max observations requested per metric"},"metrics":{"additionalProperties":{"$ref":"#/components/schemas/MetricHistorySeries"},"type":"object","title":"Metrics","description":"Keyed by metric_id. Missing metrics are omitted (not nulled)."},"equity_basis_absent":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Equity Basis Absent","description":"#2517: set when the filer is a POOLED INVESTMENT VEHICLE (a commodity/crypto/currency grantor trust), for which market_cap — and every multiple derived from it — has no basis. Those metric_ids are OMITTED from `metrics` above and named here, so an absence reads as a decision rather than as 'no data'."},"listing_basis_absent":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Listing Basis Absent","description":"r119: set when the issuer's primary listing is a preferred share, warrant or right rather than its common stock (its common is not listed), so that listing's price x the common share count is not a market capitalisation. The stored market_cap and every multiple on it are OMITTED from `metrics` above and named here. Revenue, earnings and the cash-flow statement are unaffected. Distinct from `equity_basis_absent` (a pooled vehicle has no equity basis at all)."},"currency_basis_absent":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Currency Basis Absent","description":"r82 (#571): set when the filer reports in a currency other than USD. The share price is USD and MetricDuck does not convert currencies, so every metric that divides the price (or the USD market cap) by the filer's own-currency figures would mix two currencies: EV, P/E, P/B, P/S, the EV multiples and the yields. Those metric_ids are OMITTED from `metrics` above and named here. market_cap itself is served, in USD."},"depositary_basis_absent":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Depositary Basis Absent","description":"#2443: set when the filer is a FOREIGN PRIVATE ISSUER (or one of the few 10-K filers whose US listing is an ADS, r84), whose US listing price is quoted per ADS while its cover-page share count is in ordinary shares. The ratio between them is a per-filer fact MetricDuck does not verify, so shares x price is not a market capitalisation and every multiple built on it is withheld. Those metric_ids are OMITTED from `metrics` above and named here. Distinct from `equity_basis_absent`: a pooled vehicle has NO equity basis, an FPI has one that is UNVERIFIED — so the next step differs (the annual report's cover page or its deposit-agreement exhibit states the ADS ratio)."},"operating_kpi_withheld":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Operating Kpi Withheld","description":"Founder decision 2026-10-12 (r98): set when an asked id is an operating KPI that an LLM extracted from earnings releases (operating_kpi_facts: subscribers, backlog, net_interest_margin, combined_ratio...). A two-reader audit found 70% of those values correct, below MetricDuck's accuracy bar, so they are not served. Those metric_ids are OMITTED from `metrics` above and named here in backticks, with where the company states the figure: its earnings release, or for headcount the 10-K's Human Capital discussion. Null when no such id was asked or when SERVE_OPERATING_KPIS is on."},"component_absent":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Component Absent","description":"#3071: set when a served metric's own component is absent for this filer, so the formula engine read the missing operand as 0 and stored a number built out of nothing — `roic_vs_cost_of_debt` becomes `roic - 0`, byte-identical to `roic`. Those POINTS carry a null value (the period and citation are kept); this field names the metric and the component that decided it. Rows minted before the formula was guarded keep their fabricated value until a new filing touches the period, which is why the check runs at read time. Silent for a row with no lineage: absence of evidence is not evidence of absence."},"pending_annual_8k":{"anyOf":[{"$ref":"#/components/schemas/PendingAnnual8K"},{"type":"null"}],"description":"Reporting-gap affordance (FY only): when the latest structured FY is older than an already-released annual earnings 8-K (filed ahead of the not-yet-filed 10-K), names that 8-K so the caller can read the newer full-year figure via get_filing_section. Null otherwise."},"pending_quarterly_8k":{"anyOf":[{"$ref":"#/components/schemas/PendingQuarterly8K"},{"type":"null"}],"description":"#1813 reporting-gap affordance (quarterly cash-flow family only — capex/net_cf_ops/fcf): when the latest structured quarter is older than an already-released quarterly earnings 8-K (filed ahead of the not-yet-filed 10-Q, whose XBRL is what populates this series), names that 8-K so the caller can read the as-released capex/OCF/FCF via get_earnings. Value-free — substitutes no value; the agent navigates. Null otherwise."},"note":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Note","description":"Navigation affordance. On a complete miss (empty `metrics`): names any asked ids that are not in the served catalog (with ranked closest candidates, #2296) and points at get_ir_documents — operational KPIs / forward guidance often live only in the IR earnings deck. On a partial hit it carries ONLY the catalog-miss sentence(s) for the ids that matched nothing; null when every requested metric returned."},"resolved":{"anyOf":[{"additionalProperties":{"type":"string"},"type":"object"},{"type":"null"}],"title":"Resolved","description":"Near-miss metric_id substitutions performed (#2296), asked -> served (e.g. {'revenue': 'revenues'}). Series in `metrics` are keyed by the SERVED id. Present only when a substitution happened — the renderer must state it (⛔ no silent aliasing, #2150)."},"ir_source":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Ir Source","description":"Investor-relations page (#597), a clean https:// URL from companies.ir_domain. Populated ONLY on a not-found result (empty `metrics`) AND when the company has a known ir_domain — the concrete IR pointer that complements `note`'s get_ir_documents nudge for operational-KPI / forward-schedule misses, which often live in the earnings DECK rather than SEC filings. Null otherwise (never fabricated)."}},"type":"object","required":["ticker","cik","company_name","period_type","window"],"title":"MetricsHistoryResponse"},"MetricsListResponse":{"properties":{"category":{"type":"string","title":"Category"},"metrics":{"items":{"$ref":"#/components/schemas/MetricItem"},"type":"array","title":"Metrics"}},"type":"object","required":["category","metrics"],"title":"MetricsListResponse","description":"Available metrics response"},"NewsletterUnsubscribeResponse":{"properties":{"success":{"type":"boolean","title":"Success"},"message":{"type":"string","title":"Message"}},"type":"object","required":["success","message"],"title":"NewsletterUnsubscribeResponse","description":"Response after successful unsubscribe"},"NextFiling":{"properties":{"predicted_date":{"type":"string","format":"date","title":"Predicted Date","description":"Predicted filing date"},"days_until":{"type":"integer","title":"Days Until","description":"Days until filing from today"},"confidence":{"type":"string","title":"Confidence","description":"Prediction confidence: high, medium, low"},"time_window":{"type":"string","title":"Time Window","description":"Time window: BEFORE_MARKET, AFTER_MARKET, DURING_MARKET, UNKNOWN"},"date_range_start":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Date Range Start","description":"Earliest possible filing date"},"date_range_end":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Date Range End","description":"Latest possible filing date"}},"type":"object","required":["predicted_date","days_until","confidence","time_window"],"title":"NextFiling","description":"Predicted filing with confidence and time window"},"NextFilingsResponse":{"properties":{"total":{"type":"integer","title":"Total","description":"Total number of companies with upcoming filings"},"items":{"items":{"$ref":"#/components/schemas/CompanyNextFilings"},"type":"array","title":"Items","description":"List of companies with next filings"},"pagination":{"$ref":"#/components/schemas/PaginationInfo","description":"Pagination information"}},"type":"object","required":["total","items","pagination"],"title":"NextFilingsResponse","description":"Response for next filings endpoint"},"ObjectiveFlags":{"properties":{"is_financial_services":{"type":"boolean","title":"Is Financial Services","default":false},"is_reit":{"type":"boolean","title":"Is Reit","default":false},"is_utility":{"type":"boolean","title":"Is Utility","default":false},"has_negative_equity":{"type":"boolean","title":"Has Negative Equity","default":false},"is_net_cash_positive":{"type":"boolean","title":"Is Net Cash Positive","default":false},"has_sufficient_history":{"type":"boolean","title":"Has Sufficient History","default":false},"has_recent_filing":{"type":"boolean","title":"Has Recent Filing","default":false},"dcf_has_min_history":{"type":"boolean","title":"Dcf Has Min History","default":false},"dcf_latest_fcf_positive":{"type":"boolean","title":"Dcf Latest Fcf Positive","default":false},"dcf_is_suitable_industry":{"type":"boolean","title":"Dcf Is Suitable Industry","default":true}},"type":"object","title":"ObjectiveFlags","description":"Boolean facts only - no subjective judgments"},"OperationalEfficiencyAnalysis":{"properties":{"roic_ttm":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Roic Ttm"},"roic_yoy_change":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Roic Yoy Change"},"roic_8q_median":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Roic 8Q Median"},"roic_8q_trend":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Roic 8Q Trend"},"roic_8q_volatility":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Roic 8Q Volatility"},"nopat_margin_ttm":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Nopat Margin Ttm"},"nopat_margin_yoy":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Nopat Margin Yoy"},"nopat_margin_8q_median":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Nopat Margin 8Q Median"},"nopat_margin_8q_trend":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Nopat Margin 8Q Trend"},"asset_turnover_ttm":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Asset Turnover Ttm"},"asset_turnover_fy":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Asset Turnover Fy"},"asset_turnover_yoy":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Asset Turnover Yoy"},"asset_turnover_8q_median":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Asset Turnover 8Q Median"},"asset_turnover_8q_trend":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Asset Turnover 8Q Trend"},"debt_to_equity":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Debt To Equity"},"fixed_asset_turnover_ttm":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Fixed Asset Turnover Ttm"},"fixed_asset_turnover_8q_median":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Fixed Asset Turnover 8Q Median"},"fixed_asset_turnover_8q_trend":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Fixed Asset Turnover 8Q Trend"},"invested_cap_turnover_ttm":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Invested Cap Turnover Ttm"},"invested_cap_turnover_8q_median":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Invested Cap Turnover 8Q Median"},"invested_cap_turnover_8q_trend":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Invested Cap Turnover 8Q Trend"},"capex_intensity_ttm":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Capex Intensity Ttm"},"capex_intensity_8q_median":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Capex Intensity 8Q Median"},"capex_to_depreciation_ttm":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Capex To Depreciation Ttm"},"depreciation_rate_8q_median":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Depreciation Rate 8Q Median"},"depreciation_rate_8q_trend":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Depreciation Rate 8Q Trend"},"sector_roic_median":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Sector Roic Median"},"sector_roic_p25":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Sector Roic P25"},"sector_roic_p75":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Sector Roic P75"},"sector_nopat_margin_median":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Sector Nopat Margin Median"},"sector_asset_turnover_median":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Sector Asset Turnover Median"},"sector_debt_to_equity_median":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Sector Debt To Equity Median"}},"type":"object","title":"OperationalEfficiencyAnalysis","description":"Operational efficiency and asset productivity analysis with ROIC focus.\n\nEnhanced with 8Q historical context for deep reveal indicators:\n- Sparklines (8Q values)\n- Medians for stability assessment\n- Trends for direction\n- Volatility for consistency analysis"},"OperationalMetric":{"properties":{"current":{"title":"Current","description":"Current period value (can be float, int, or string)"},"prior_year":{"anyOf":[{},{"type":"null"}],"title":"Prior Year","description":"Prior year period value"},"growth_pct":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Growth Pct","description":"Year-over-year growth percentage"},"unit":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Unit","description":"Unit of measurement (e.g., 'members', 'locations', 'vehicles')"}},"type":"object","required":["current"],"title":"OperationalMetric","description":"Operational/non-financial metric (KPI).\n\nExamples: Active users, locations, memberships, vehicles sold, subscriptions"},"OverviewPageResponse":{"properties":{"company":{"$ref":"#/components/schemas/ComprehensiveOverviewResponse","description":"Company overview with comprehensive metrics"},"mda_insights":{"anyOf":[{},{"type":"null"}],"title":"Mda Insights","description":"Latest MD&A insights (10-Q/10-K)"},"earnings_insights":{"anyOf":[{"$ref":"#/components/schemas/EarningsInsight"},{"type":"null"}],"description":"Latest earnings insights (8-K)"},"market_data":{"anyOf":[{},{"type":"null"}],"title":"Market Data","description":"Market data for price chart (2-year history)"},"quarterly_trends":{"anyOf":[{"$ref":"#/components/schemas/QuarterlyTrendsData"},{"type":"null"}],"description":"Quarterly statement trends (8Q + TTM)"},"filing_intelligence":{"anyOf":[{},{"type":"null"}],"title":"Filing Intelligence","description":"Latest filing intelligence (comprehensive SEC analysis)"},"classification":{"anyOf":[{},{"type":"null"}],"title":"Classification","description":"Business model classification: GICS codes, tags, revenue mix, SIC accuracy"},"segment_breakdown":{"anyOf":[{"$ref":"#/components/schemas/SegmentBreakdown"},{"type":"null"}],"description":"Latest-FY business segment and geographic revenue breakdown from XBRL dimensional facts"},"coverage":{"anyOf":[{"$ref":"#/components/schemas/CoverageBlock"},{"type":"null"}],"description":"Compact IR + earnings-call coverage ('what your agent reads'); null if neither present"},"page_metadata":{"$ref":"#/components/schemas/PageMetadata","description":"Metadata about data availability and caching"}},"type":"object","required":["company","page_metadata"],"title":"OverviewPageResponse","description":"BFF (Backend for Frontend) aggregated response for company overview page.\n\nCombines data from multiple endpoints into a single response:\n- Company overview (comprehensive metrics with peer comparison)\n- Latest MD&A insights (10-Q/10-K)\n- Latest earnings insights (8-K)\n- Market data (2-year price history)\n\nBenefits:\n- Reduces API calls from 6 to 1 (83% reduction)\n- Server-side parallel aggregation (faster than client waterfall)\n- Unified caching strategy (single cache key vs 6+)\n- Graceful degradation (partial data if some sources fail)"},"PageMetadata":{"properties":{"cached":{"type":"boolean","title":"Cached","description":"Whether response was served from cache"},"cache_age_seconds":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Cache Age Seconds","description":"Age of cached data in seconds"},"data_sources_available":{"items":{"type":"string"},"type":"array","title":"Data Sources Available","description":"List of data sources that returned data"},"data_sources_failed":{"items":{"type":"string"},"type":"array","title":"Data Sources Failed","description":"List of data sources that failed"},"query_time_ms":{"type":"integer","title":"Query Time Ms","description":"Total server-side query time in milliseconds"},"cache_ttl_seconds":{"type":"integer","title":"Cache Ttl Seconds","description":"TTL for this cached response"}},"type":"object","required":["cached","data_sources_available","query_time_ms","cache_ttl_seconds"],"title":"PageMetadata","description":"Metadata about aggregated page data availability and freshness"},"PaginationInfo":{"properties":{"limit":{"type":"integer","title":"Limit","description":"Number of items per page"},"offset":{"type":"integer","title":"Offset","description":"Current offset"},"has_next":{"type":"boolean","title":"Has Next","description":"Whether there are more items"}},"type":"object","required":["limit","offset","has_next"],"title":"PaginationInfo","description":"Pagination metadata"},"PeerCompany":{"properties":{"cik":{"type":"string","title":"Cik"},"ticker":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Ticker"},"company_name":{"type":"string","title":"Company Name"},"sector":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Sector"},"industry":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Industry"},"reporting_currency":{"type":"string","title":"Reporting Currency","default":"USD"},"metrics":{"additionalProperties":{"anyOf":[{"type":"number"},{"type":"null"}]},"type":"object","title":"Metrics"},"market_cap":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Market Cap"},"revenues_ttm":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Revenues Ttm"},"revenue_growth_yoy":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Revenue Growth Yoy"},"revenue_3y_cagr":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Revenue 3Y Cagr"},"net_margin":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Net Margin"},"pe_ratio":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Pe Ratio"},"pb_ratio":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Pb Ratio"},"roe":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Roe"},"debt_to_equity":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Debt To Equity"},"roic":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Roic"},"gross_margin":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Gross Margin"},"oper_margin":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Oper Margin"},"oper_margin_yoy":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Oper Margin Yoy"},"oper_margin_8q_trend":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Oper Margin 8Q Trend"},"oper_margin_8q_median":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Oper Margin 8Q Median"},"roic_yoy":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Roic Yoy"},"roic_8q_trend":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Roic 8Q Trend"},"roic_8q_median":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Roic 8Q Median"},"capex_intensity":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Capex Intensity"},"capex_intensity_yoy":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Capex Intensity Yoy"},"fcf_yield":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Fcf Yield"},"fcf_yield_8q_trend":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Fcf Yield 8Q Trend"},"net_debt_to_ebitda":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Net Debt To Ebitda"},"net_debt_to_ebitda_8q_trend":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Net Debt To Ebitda 8Q Trend"},"net_debt_to_ebitda_8q_stdv":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Net Debt To Ebitda 8Q Stdv"},"roiic":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Roiic"},"roiic_3y_avg":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Roiic 3Y Avg"},"interest_coverage":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Interest Coverage"},"interest_coverage_8q_trend":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Interest Coverage 8Q Trend"},"capex_deprec_ratio":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Capex Deprec Ratio"},"capex_deprec_ratio_8q_trend":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Capex Deprec Ratio 8Q Trend"},"ffo":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Ffo"},"affo":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Affo"},"noi":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Noi"},"noi_margin":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Noi Margin"},"ffo_payout_ratio":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Ffo Payout Ratio"},"affo_payout_ratio":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Affo Payout Ratio"},"latest_period_end":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Latest Period End"},"price_as_of":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Price As Of"},"latest_filing_date":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Latest Filing Date"},"latest_filing_form":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Latest Filing Form"},"sec_filing_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Sec Filing Url"}},"type":"object","required":["cik","company_name"],"title":"PeerCompany","description":"Single peer company with comparison metrics"},"PeerInsights":{"properties":{"roic_trend":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Roic Trend"},"margin_trend":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Margin Trend"},"revenue_trend":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Revenue Trend"},"rankings":{"additionalProperties":{"type":"integer"},"type":"object","title":"Rankings"},"target_vs_peers":{"additionalProperties":{"type":"string"},"type":"object","title":"Target Vs Peers"},"strongest_metrics":{"items":{"type":"string"},"type":"array","title":"Strongest Metrics"},"weakest_metrics":{"items":{"type":"string"},"type":"array","title":"Weakest Metrics"},"summary":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Summary"}},"type":"object","title":"PeerInsights","description":"Pre-computed insights for SEO and AI consumption"},"PeerSuggestion":{"properties":{"cik":{"type":"string","title":"Cik"},"ticker":{"type":"string","title":"Ticker"},"company_name":{"type":"string","title":"Company Name"},"sector":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Sector"},"industry":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Industry"},"market_cap":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Market Cap"},"relevance_score":{"type":"number","maximum":1.0,"minimum":0.0,"title":"Relevance Score"}},"type":"object","required":["cik","ticker","company_name","relevance_score"],"title":"PeerSuggestion","description":"Lightweight peer suggestion for Add Peer dialog"},"PeerSuggestionsResponse":{"properties":{"suggestions":{"items":{"$ref":"#/components/schemas/PeerSuggestion"},"type":"array","title":"Suggestions"},"target_sector":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Target Sector"},"target_industry":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Target Industry"}},"type":"object","required":["suggestions"],"title":"PeerSuggestionsResponse","description":"Response for peer suggestions endpoint"},"PeersComparisonResponse":{"properties":{"target":{"$ref":"#/components/schemas/PeerCompany"},"peers":{"items":{"$ref":"#/components/schemas/PeerCompany"},"type":"array","title":"Peers"},"metadata":{"additionalProperties":true,"type":"object","title":"Metadata"},"insights":{"anyOf":[{"$ref":"#/components/schemas/PeerInsights"},{"type":"null"}]}},"type":"object","required":["target","peers"],"title":"PeersComparisonResponse","description":"Peer comparison response with target company and peers"},"PendingAnnual8K":{"properties":{"accession_number":{"type":"string","title":"Accession Number"},"filing_date":{"type":"string","title":"Filing Date"},"fiscal_year":{"type":"integer","title":"Fiscal Year"}},"type":"object","required":["accession_number","filing_date","fiscal_year"],"title":"PendingAnnual8K"},"PendingQuarterly8K":{"properties":{"accession_number":{"type":"string","title":"Accession Number"},"filing_date":{"type":"string","title":"Filing Date"},"fiscal_year":{"type":"integer","title":"Fiscal Year"},"fiscal_period":{"type":"string","title":"Fiscal Period"}},"type":"object","required":["accession_number","filing_date","fiscal_year","fiscal_period"],"title":"PendingQuarterly8K"},"PeriodInfo":{"properties":{"accn":{"type":"string","title":"Accn","description":"Accession number"},"form_type":{"type":"string","title":"Form Type","description":"Form type (10-K, 10-Q)"},"period_end":{"type":"string","format":"date","title":"Period End","description":"Period end date"},"label":{"type":"string","title":"Label","description":"Human-readable label (FY 2024, Q3 2024)"},"viewer_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Viewer Url","description":"URL to view filing in filing-viewer"}},"type":"object","required":["accn","form_type","period_end","label"],"title":"PeriodInfo","description":"Filing period information"},"PeriodType":{"type":"string","enum":["Q","FY","TTM"],"title":"PeriodType"},"PeriodValue":{"properties":{"value":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Value","description":"Numeric value"},"native_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Native Id","description":"XBRL fact ID for deep linking"}},"type":"object","title":"PeriodValue","description":"Value with deep-link metadata for a specific period"},"ProfitabilityAnalysis":{"properties":{"roe_ttm":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Roe Ttm"},"roic_vs_roe_ratio":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Roic Vs Roe Ratio"},"gross_margin_ttm":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Gross Margin Ttm"},"operating_margin_ttm":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Operating Margin Ttm"},"net_margin_ttm":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Net Margin Ttm"},"fcf_margin_ttm":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Fcf Margin Ttm"},"gross_margin_fy":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Gross Margin Fy"},"operating_margin_fy":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Operating Margin Fy"},"net_margin_fy":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Net Margin Fy"},"fcf_margin_fy":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Fcf Margin Fy"},"roe_fy":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Roe Fy"},"roa_fy":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Roa Fy"},"rotce_ttm":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Rotce Ttm"},"rotce_fy":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Rotce Fy"},"revenue_growth_fy":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Revenue Growth Fy"},"roa_ttm":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Roa Ttm"},"revenue_growth_ttm":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Revenue Growth Ttm"},"net_income_growth_ttm":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Net Income Growth Ttm"},"eps_growth_ttm":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Eps Growth Ttm"},"revenues_ttm":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Revenues Ttm"},"operating_income_ttm":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Operating Income Ttm"},"operating_income_basis":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Operating Income Basis"},"net_income_ttm":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Net Income Ttm"},"roic_sector_percentile":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Roic Sector Percentile"},"roic_sector_median":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Roic Sector Median"},"roic_sector_p25":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Roic Sector P25"},"roic_sector_p75":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Roic Sector P75"},"roe_sector_percentile":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Roe Sector Percentile"},"roe_sector_median":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Roe Sector Median"},"gross_margin_sector_percentile":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Gross Margin Sector Percentile"},"gross_margin_sector_median":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Gross Margin Sector Median"},"operating_margin_sector_percentile":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Operating Margin Sector Percentile"},"operating_margin_sector_median":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Operating Margin Sector Median"},"fcf_margin_sector_percentile":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Fcf Margin Sector Percentile"},"fcf_margin_sector_median":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Fcf Margin Sector Median"}},"type":"object","title":"ProfitabilityAnalysis","description":"Multi-dimensional profitability analysis"},"QuarterlyTrendsData":{"properties":{"quarters":{"items":{"type":"string"},"type":"array","title":"Quarters","description":"Quarter labels in descending order (most recent first)"},"revenues":{"items":{"anyOf":[{"type":"number"},{"type":"null"}]},"type":"array","title":"Revenues","description":"Quarterly revenues"},"operating_income":{"items":{"anyOf":[{"type":"number"},{"type":"null"}]},"type":"array","title":"Operating Income","description":"Quarterly operating income/EBIT"},"net_income":{"items":{"anyOf":[{"type":"number"},{"type":"null"}]},"type":"array","title":"Net Income","description":"Quarterly net income"},"operating_cash_flow":{"items":{"anyOf":[{"type":"number"},{"type":"null"}]},"type":"array","title":"Operating Cash Flow","description":"Quarterly operating cash flow"},"free_cash_flow":{"items":{"anyOf":[{"type":"number"},{"type":"null"}]},"type":"array","title":"Free Cash Flow","description":"Quarterly free cash flow (OCF - Capex)"},"total_equity":{"anyOf":[{"items":{"anyOf":[{"type":"number"},{"type":"null"}]},"type":"array"},{"type":"null"}],"title":"Total Equity","description":"Quarterly total equity/shareholders' equity"},"ttm_revenues":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Ttm Revenues","description":"TTM revenues"},"ttm_operating_income":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Ttm Operating Income","description":"TTM operating income"},"ttm_net_income":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Ttm Net Income","description":"TTM net income"},"ttm_operating_cash_flow":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Ttm Operating Cash Flow","description":"TTM operating cash flow"},"ttm_free_cash_flow":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Ttm Free Cash Flow","description":"TTM free cash flow"},"ttm_total_equity":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Ttm Total Equity","description":"Latest total equity (point-in-time)"}},"type":"object","required":["quarters","revenues","operating_income","net_income","operating_cash_flow","free_cash_flow"],"title":"QuarterlyTrendsData","description":"Quarterly financial statement trends for FinancialStatementsPreview component.\n\nProvides 8 quarters + TTM of core statement metrics:\n- Income Statement: Revenue, Operating Income, Net Income\n- Cash Flow: Operating Cash Flow, Free Cash Flow\n- Balance Sheet: Total Equity (point-in-time)"},"RatiosItem":{"properties":{"date":{"type":"string","title":"Date"},"symbol":{"type":"string","title":"Symbol"},"cik":{"type":"string","title":"Cik"},"filing_date":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Filing Date"},"fiscal_year":{"type":"integer","title":"Fiscal Year"},"period":{"type":"string","title":"Period"},"industry":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Industry"},"market_cap":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Market Cap"},"ev":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Ev"},"pe_ratio":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Pe Ratio"},"ps_ratio":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Ps Ratio"},"pb_ratio":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Pb Ratio"},"ev_sales":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Ev Sales"},"ev_ebitda":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Ev Ebitda"},"ev_ebit":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Ev Ebit"},"ev_fcf":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Ev Fcf"},"pocf_ratio":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Pocf Ratio"},"quick_ratio":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Quick Ratio"},"current_ratio":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Current Ratio"},"debt_to_equity":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Debt To Equity"},"roe":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Roe"},"roa":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Roa"},"efficiency_ratio":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Efficiency Ratio"},"cash_conversion":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Cash Conversion"},"defensive_interval":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Defensive Interval"},"ebitda":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Ebitda"},"ebitda_margin":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Ebitda Margin"},"ebit":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Ebit"},"accession_number":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Accession Number"}},"type":"object","required":["date","symbol","cik","fiscal_year","period"],"title":"RatiosItem","description":"Individual ratios period data"},"RawFact":{"properties":{"concept":{"type":"string","title":"Concept","description":"XBRL concept/account name"},"concept_label":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Concept Label","description":"Human-readable standard label"},"concept_label_terse":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Concept Label Terse","description":"Human-readable terse/short label for compact UIs"},"tag":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Tag","description":"XBRL taxonomy namespace: 'dei' = cover-page entity metadata (e.g. EntityCommonStockSharesOutstanding = the most-current shares outstanding, as of the filing/cover date — use for market cap / equity value); 'us-gaap'/'ifrs' = financial-statement concepts (e.g. CommonStockSharesOutstanding = balance-sheet period-end count)."},"segment_label":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Segment Label","description":"Segment/dimension label if present (legacy)"},"value":{"anyOf":[{"type":"number"},{"type":"integer"},{"type":"string"},{"type":"null"}],"title":"Value","description":"Fact value"},"unit":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Unit","description":"Unit of measure (USD, shares, etc.)"},"start_date":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Start Date","description":"Period start date (for duration facts)"},"end_date":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"End Date","description":"Period end date"},"fact_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Fact Type","description":"'instant' or 'duration'"},"native_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Native Id","description":"Native XBRL fact ID for deep linking"},"is_consolidated":{"type":"boolean","title":"Is Consolidated","description":"True if no dimensional breakdown","default":true},"dimensions":{"items":{"$ref":"#/components/schemas/src__models__xbrl__DimensionInfo"},"type":"array","title":"Dimensions","description":"All dimensional axes and members","default":[]},"duration_days":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Duration Days","description":"Period length in days for duration facts — ~90=quarter, ~180=6mo YTD, ~270=9mo YTD, ~365=FY. With start/end this is how you de-cumulate a cumulative cash-flow line (Q2 standalone = 180-day YTD minus 90-day Q1)."},"fiscal_year":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Fiscal Year","description":"Fiscal year (filing DEI)"},"fiscal_period":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Fiscal Period","description":"Fiscal period (Q1/Q2/Q3/FY) — filing-stamped; for the period's own identity trust start_date/end_date/duration_days, not this label."},"accession_number":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Accession Number","description":"Source filing accession for this fact (per-fact citation)."},"decimals":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Decimals","description":"As-reported XBRL precision (the floor — never imply more precision than this): -3 = filed to the nearest thousand, -6 = millions, 0 = dollar, 2 = cents. e.g. value 18801000 with decimals=-3 was filed as '18,801' thousand."},"is_negated":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Is Negated","description":"SEC negated-label role. True means the face of the statement reads MINUS the `value` here — a cash OUTFLOW (PaymentsTo…), an IncreaseDecrease use of cash, or a contra-asset (accumulated depreciation). `value` is the raw as-filed XBRL instance value: a positive magnitude for the outflow/contra-asset concepts, but SIGNED by construction for the IncreaseDecreaseIn… working-capital family (where ~38-40% of negated facts are stored negative, and the face therefore reads positive). Compute the face as -value; do not read this flag as 'the number is negative' (#2355)."},"fact_key":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Fact Key","description":"Stable cross-filing fact identity (hash of cik|concept|period|dimensions); survives restatement/amendment for durable referencing."},"fact_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Fact Url","description":"Deep-link to this EXACT fact in the SEC EDGAR inline-XBRL document (primary source — independently verifiable). Null when the filing's iXBRL doc / native_id is unavailable."},"fact_viewer_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Fact Viewer Url","description":"Deep-link to this EXACT fact in the MetricDuck filing viewer (highlighted: scroll + outline + fact name). Convenience view of MD's copy of the SAME iXBRL doc; fact_url (EDGAR) remains the independent primary source. Emitted on the same conditions as fact_url; falls back to EDGAR (scroll, no highlight) when the filing isn't cached in MD."}},"type":"object","required":["concept","value"],"title":"RawFact","description":"Individual XBRL fact"},"RawFactsResponse":{"properties":{"ticker":{"type":"string","title":"Ticker"},"cik":{"type":"string","title":"Cik"},"company_name":{"type":"string","title":"Company Name"},"accession_number":{"type":"string","title":"Accession Number"},"form_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Form Type"},"filing_date":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Filing Date"},"period_end_date":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Period End Date"},"viewer_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Viewer Url","description":"URL to view filing in filing-viewer"},"facts":{"items":{"$ref":"#/components/schemas/RawFact"},"type":"array","title":"Facts"},"total_facts":{"type":"integer","title":"Total Facts"},"has_more":{"type":"boolean","title":"Has More"},"concept_search_relaxed":{"type":"boolean","title":"Concept Search Relaxed","default":false},"period_history":{"type":"boolean","title":"Period History","default":false},"match_map":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Match Map"}},"type":"object","required":["ticker","cik","company_name","accession_number","facts","total_facts","has_more"],"title":"RawFactsResponse","description":"Response containing raw XBRL facts for a filing"},"Receipt":{"properties":{"covers":{"items":{"type":"string"},"type":"array","title":"Covers","description":"Period keys this receipt attests to, e.g. ['q_current']. A receipt never implies coverage of a period outside this list."},"quote":{"type":"string","title":"Quote","description":"Verbatim quote from the source filing the value was extracted from."},"viewer_url":{"type":"string","title":"Viewer Url","description":"Deep link into the source exhibit at the cited block. Pass-through from the producer's locator — never rebuilt downstream."},"block_id":{"type":"string","title":"Block Id","description":"Producer-assigned id of the source block the quote was extracted from. Version-scoped, NOT a durable identifier: it encodes the block's POSITION in one normalization of the exhibit, so re-extracting the same filing under a later producer version can move it — or leave it pointing at different content (#1890). Treat it as an internal coordinate, not a stable handle; `quote` + `viewer_url` are the pair that navigates back to the source."},"exhibit_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Exhibit Id","description":"Id of the exhibit (within the filing) the block belongs to."}},"type":"object","required":["covers","quote","viewer_url","block_id"],"title":"Receipt","description":"Per-figure provenance (\"receipt\") for one served financial metric (#1397).\n\nA receipt attests ONLY the period(s) listed in `covers` — e.g. a receipt\nwith `covers=[\"q_current\"]` says nothing about `q_prior_year` or the\nannual fields, which may come from a different source (see\n`EarningsMetric.provenance` for why a served metric can be mixed-source).\nNever infer coverage of a field this receipt doesn't explicitly list.\n\nLives in `base` (not `financial_statements`) so BOTH `financial_statements`\n(EarningsMetric/EarningsInsight) and `earnings_insights` (CashFlowInsight,\n#1813) can carry it without a circular import."},"RecentFilingItem":{"properties":{"ticker":{"type":"string","title":"Ticker"},"cik":{"type":"string","title":"Cik"},"accession_number":{"type":"string","title":"Accession Number"},"filed_at":{"type":"string","format":"date","title":"Filed At","description":"Filing date (YYYY-MM-DD)"},"form_type":{"type":"string","title":"Form Type"},"form_subtype":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Form Subtype","description":"8-K sub-type derived from section inventory: '8-K-earnings', '8-K-transcript', '8-K-event', '8-K-other'. Null for non-8-K forms."}},"type":"object","required":["ticker","cik","accession_number","filed_at","form_type"],"title":"RecentFilingItem","description":"One row in the recent-filings discovery response."},"RequestMetadata":{"properties":{"tickers":{"items":{"type":"string"},"type":"array","title":"Tickers","description":"Requested tickers"},"metrics":{"items":{"type":"string"},"type":"array","title":"Metrics","description":"Requested metric IDs"},"period":{"type":"string","title":"Period","description":"Period type (ttm, quarterly, annual)"},"years":{"type":"integer","title":"Years","description":"Years of historical data"},"dimensions":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Dimensions","description":"Compound period types requested (Q.TREND8, Q.MED8, TTM.YOY, etc.)"},"price":{"type":"string","title":"Price","description":"Price basis: historical (period-end) or current (today's price)","default":"historical"}},"type":"object","required":["tickers","metrics","period","years"],"title":"RequestMetadata","description":"Metadata about the original request"},"ResponseMetadata":{"properties":{"price_attribution":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Price Attribution","description":"The price source's required attribution, present only when the prices in this response come from a source that requires one (IEX HIST)."},"request":{"$ref":"#/components/schemas/RequestMetadata"},"resolved_tickers":{"type":"integer","title":"Resolved Tickers","description":"Number of tickers found"},"total_values":{"type":"integer","title":"Total Values","description":"Total metric values returned"},"generated_at":{"type":"string","format":"date-time","title":"Generated At"},"warnings":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Warnings","description":"Warnings about missing dimension data (e.g., 'No Q.TREND8 data for shares_outstanding (AAPL)')"},"credits":{"anyOf":[{"$ref":"#/components/schemas/CreditInfo"},{"type":"null"}],"description":"Credit usage info (present for authenticated developer-tier users)"}},"type":"object","required":["request","resolved_tickers","total_values"],"title":"ResponseMetadata","description":"Metadata about the response"},"ScreenRequest":{"properties":{"filters":{"items":{"$ref":"#/components/schemas/MetricFilter"},"type":"array","title":"Filters","description":"List of metric filters to apply","default":[]},"include_metrics":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Include Metrics","description":"List of metric IDs to include in results. If null, returns common metrics."},"sectors":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Sectors","description":"List of sector codes to filter by (e.g., ['TECH', 'HEALTH'])"},"industries":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Industries","description":"List of industry codes to filter by (e.g., ['TECH_SOFTWARE'])"},"tickers":{"anyOf":[{"items":{"type":"string"},"type":"array","maxItems":50},{"type":"null"}],"title":"Tickers","description":"Filter to specific ticker symbols (max 50). Returns only these companies."},"required_tags":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Required Tags","description":"Filter to companies whose classification includes ALL of these tags (e.g., ['saas_enterprise'])."},"excluded_tags":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Excluded Tags","description":"Filter to companies whose classification includes NONE of these tags (e.g., ['china_revenue_heavy'])."},"signals":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Signals","description":"DEPRECATED (#1535) — no longer accepted; a non-empty value returns 400. Signal screening moved to screen_filing_signals (a universe-correct cross-company screen); intersect its results with your metric screen. Kept only to fail loudly instead of silently ignoring the field.","deprecated":true},"limit":{"type":"integer","maximum":100.0,"minimum":1.0,"title":"Limit","description":"Maximum number of results per page","default":20},"page":{"type":"integer","minimum":1.0,"title":"Page","description":"Page number (1-indexed) for pagination","default":1},"sort_by":{"type":"string","title":"Sort By","description":"Metric ID to sort by","default":"market_cap"},"sort_order":{"type":"string","title":"Sort Order","description":"Sort order: asc or desc","default":"desc"}},"type":"object","title":"ScreenRequest","description":"Request body for POST /screener/screen"},"SecEarningsRelease":{"properties":{"filing_date":{"type":"string","title":"Filing Date","description":"Date the company filed this earnings release with the SEC (8-K Item 2.02)."},"fiscal_year":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Fiscal Year","description":"Implied fiscal year of the results released (from the company's fiscal year end and the filing date; DISPLAY only)."},"fiscal_period":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Fiscal Period","description":"Implied fiscal quarter of the results released (DISPLAY only)."},"accession_number":{"type":"string","title":"Accession Number"},"url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Url","description":"SEC filing index URL."}},"type":"object","required":["filing_date","accession_number"],"title":"SecEarningsRelease"},"SectionFallback":{"properties":{"requested_section_id":{"type":"string","title":"Requested Section Id"},"served_section_id":{"type":"string","title":"Served Section Id"},"reason":{"type":"string","title":"Reason"},"referenced_form":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Referenced Form"},"referenced_accession":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Referenced Accession"},"referenced_filing_date":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Referenced Filing Date"},"kind":{"anyOf":[{"type":"string","enum":["incorporated_by_reference","older_filing_served","older_filing_withheld"]},{"type":"null"}],"title":"Kind"}},"type":"object","required":["requested_section_id","served_section_id","reason"],"title":"SectionFallback","description":"Populated when the requested section is absent from the latest filing\nand the service fell back to a related section on the SAME latest filing,\nOR when the latest filing's section is an incorporation-by-reference stub\nthat points the caller at a different filing.\n\nTriggers today:\n  - MD&A subsection missing from latest filing → served via `mda_full` on\n    the same filing (Candidate A fix).\n  - 10-Q section is incorporated-by-reference to 10-K (`deferred_to`\n    signal) → served as-is but with `referenced_form` + `referenced_\n    accession` pointing at the latest 10-K so callers can retrieve the\n    real content without guessing."},"SectionMetadata":{"properties":{"section_id":{"type":"string","title":"Section Id"},"display_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Display Name"},"category":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Category"},"word_count":{"type":"integer","title":"Word Count","default":0},"chunk_count":{"type":"integer","title":"Chunk Count","default":0},"table_count":{"type":"integer","title":"Table Count","default":0},"preview":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Preview","description":"First ~100 words of the section text for preview"}},"type":"object","required":["section_id"],"title":"SectionMetadata","description":"Metadata for a single filing section (no full content)."},"SectorResponse":{"properties":{"sector_code":{"type":"string","title":"Sector Code"},"sector_name":{"type":"string","title":"Sector Name"}},"type":"object","required":["sector_code","sector_name"],"title":"SectorResponse","description":"Sector information"},"SectorTaxonomyItem":{"properties":{"code":{"type":"string","title":"Code"},"name":{"type":"string","title":"Name"},"industries":{"items":{"$ref":"#/components/schemas/IndustryTaxonomyItem"},"type":"array","title":"Industries"}},"type":"object","required":["code","name","industries"],"title":"SectorTaxonomyItem","description":"Sector with its industries"},"SectorTaxonomyResponse":{"properties":{"sectors":{"items":{"$ref":"#/components/schemas/BenchmarkSector"},"type":"array","title":"Sectors"},"default_sectors":{"items":{"type":"string"},"type":"array","title":"Default Sectors"},"warning_sectors":{"items":{"type":"string"},"type":"array","title":"Warning Sectors"},"unified_to_benchmark":{"additionalProperties":{"type":"string"},"type":"object","title":"Unified To Benchmark"},"benchmark_to_unified":{"additionalProperties":{"items":{"type":"string"},"type":"array"},"type":"object","title":"Benchmark To Unified"},"version":{"type":"string","title":"Version"}},"type":"object","required":["sectors","default_sectors","warning_sectors","unified_to_benchmark","benchmark_to_unified","version"],"title":"SectorTaxonomyResponse","description":"Response model for sector taxonomy endpoint."},"SectorWithCountResponse":{"properties":{"sector_code":{"type":"string","title":"Sector Code"},"sector_name":{"type":"string","title":"Sector Name"},"company_count":{"type":"integer","title":"Company Count"}},"type":"object","required":["sector_code","sector_name","company_count"],"title":"SectorWithCountResponse","description":"Sector information with company count"},"SegmentBreakdown":{"properties":{"fiscal_year":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Fiscal Year","description":"Current fiscal year used for the breakdown"},"accession_number":{"type":"string","title":"Accession Number","description":"Source 10-K (or 20-F) accession"},"business_segments":{"items":{"$ref":"#/components/schemas/SegmentLine"},"type":"array","title":"Business Segments","description":"Top business segments by revenue, capped at 8"},"geographic_segments":{"items":{"$ref":"#/components/schemas/SegmentLine"},"type":"array","title":"Geographic Segments","description":"Top geographic regions by revenue, capped at 8"},"truncated_segments":{"type":"integer","title":"Truncated Segments","description":"Count of segments omitted past the cap","default":0},"truncated_geographies":{"type":"integer","title":"Truncated Geographies","description":"Count of geographies omitted past the cap","default":0},"basis":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Basis","description":"Basis stamp for the block, e.g. 'XBRL segment revenue, FY2025 10-K'"},"non_additive_note":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Non Additive Note","description":"Set when the kept rows sum materially past same-filing consolidated revenue — the list likely mixes overlapping breakdowns and must not be summed"}},"type":"object","required":["accession_number"],"title":"SegmentBreakdown","description":"Latest-FY business segment + geographic revenue decomposition from XBRL."},"SegmentData":{"properties":{"level":{"type":"integer","maximum":3.0,"minimum":0.0,"title":"Level","description":"Tree depth (0 = root, 1-3 = children)"},"name":{"type":"string","title":"Name","description":"Segment name"},"growth_yoy_pct":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Growth Yoy Pct","description":"Year-over-year growth percentage"},"growth_yoy_pct_constant_currency":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Growth Yoy Pct Constant Currency","description":"YoY growth in constant currency (if reported)"},"metric_type":{"type":"string","title":"Metric Type","description":"Type of metric ('revenue', 'users', 'gmv', etc.)","default":"revenue"},"revenue":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Revenue","description":"Current period revenue"},"prior_year_revenue":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Prior Year Revenue","description":"Prior year period revenue"},"extraction_method":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Extraction Method","description":"Extraction method: 'llm', 'regex', 'table_parser', 'migration'"},"children":{"items":{"$ref":"#/components/schemas/SegmentData"},"type":"array","title":"Children","description":"Child segments (next level down)"}},"type":"object","required":["level","name"],"title":"SegmentData","description":"Hierarchical segment data with parent-child relationships.\n\nSegments can be geographic (U.S., International) or product-based (iPhone, Services).\nSupports up to 4 levels of hierarchy (L0 = root, L3 = most granular)."},"SegmentLine":{"properties":{"name":{"type":"string","title":"Name","description":"Segment or geography name as filed (e.g., 'AWS', 'Americas')"},"revenue":{"type":"number","title":"Revenue","description":"Current FY revenue, USD"},"revenue_yoy_pct":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Revenue Yoy Pct","description":"YoY revenue change as decimal (0.19 = 19%); null if prior year unavailable"},"operating_income":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Operating Income","description":"Current FY operating income, USD"},"operating_margin":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Operating Margin","description":"operating_income / revenue as decimal; null if either missing"}},"type":"object","required":["name","revenue"],"title":"SegmentLine","description":"One row of a segment or geographic revenue breakdown, current FY."},"SessionResponse":{"properties":{"id":{"type":"string","title":"Id"},"tier":{"type":"string","title":"Tier","description":"User tier: anonymous, trial, free, pro, enterprise"},"email":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Email"},"usage":{"$ref":"#/components/schemas/UsageData"},"capabilities":{"$ref":"#/components/schemas/UserCapabilities"}},"type":"object","required":["id","tier","usage","capabilities"],"title":"SessionResponse","description":"Session information response"},"SharesOutstandingInfo":{"properties":{"value":{"type":"number","exclusiveMinimum":0.0,"title":"Value","description":"Shares outstanding (count)"},"as_of":{"type":"string","format":"date","title":"As Of","description":"Reporting date of the share count (period end)"},"source":{"type":"string","title":"Source","description":"Basis of the count","default":"period-end balance sheet (dei cover where absent)"}},"type":"object","required":["value","as_of"],"title":"SharesOutstandingInfo","description":"Latest reported period-end shares outstanding on or before the request end date.\n\nPairs the price-at-date surface with the share count every market-cap / EV /\nP-B computation needs (q010/q012: agents improvised weighted-average counts\nwhen this wasn't on the same surface as the price)."},"SignalCount":{"properties":{"signal_id":{"type":"string","title":"Signal Id","description":"Catalog signal_id (e.g. 'ir_partnership', 'material_weakness_found')"},"source_event_type":{"type":"string","title":"Source Event Type","description":"Source: sec_filing | earnings_transcript | ir_press_release | earnings_release | earnings_release_8k | def_14a"},"count":{"type":"integer","title":"Count","description":"Distinct (source_id) occurrences of this signal for the ticker","default":0},"latest_event_date":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Latest Event Date","description":"ISO date of most recent occurrence"}},"type":"object","required":["signal_id","source_event_type"],"title":"SignalCount","description":"One row per (signal_id, source_event_type) for the company."},"SignalScreenMatch":{"properties":{"ticker":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Ticker"},"company_name":{"type":"string","title":"Company Name"},"sector":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Sector"},"form_type":{"type":"string","title":"Form Type"},"filing_date":{"type":"string","title":"Filing Date"},"fiscal_period":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Fiscal Period"},"matched_signals":{"items":{"type":"string"},"type":"array","title":"Matched Signals"},"match_detail":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Match Detail"},"matched_payloads":{"anyOf":[{"items":{"additionalProperties":true,"type":"object"},"type":"array"},{"type":"null"}],"title":"Matched Payloads"},"cik":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cik"},"accession_number":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Accession Number"},"source_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source Url"},"source_event_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source Event Type"},"transcript_version":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Transcript Version"},"market_cap":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Market Cap"}},"type":"object","required":["company_name","form_type","filing_date","matched_signals"],"title":"SignalScreenMatch","description":"A single company match from signal screening."},"SignalScreenRequest":{"properties":{"signals":{"items":{"type":"string"},"type":"array","title":"Signals","description":"Signal filters to match. Pass any signal_id present in the signals.signals catalog. The api is id-agnostic — no allowlist enforced here; mcp-worker SCREENING_SIGNALS (mcp-worker/src/tools/signal-catalog.ts) is the SSOT for client-facing valid IDs."},"ticker":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Ticker","description":"Filter to a single ticker (e.g. 'NVDA'). Per-ticker cross-source signal inventory. Combines with sectors as AND."},"sectors":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Sectors","description":"Sector codes to filter by (e.g., ['TECH', 'FIN'])"},"recency_days":{"type":"integer","maximum":365.0,"minimum":1.0,"title":"Recency Days","description":"Only filings from last N days","default":90},"limit":{"type":"integer","maximum":50.0,"minimum":1.0,"title":"Limit","description":"Max results to return","default":20},"match_mode":{"type":"string","enum":["all","any"],"title":"Match Mode","description":"Signal-list match semantics within each source type. 'all' (default, backwards-compat): row qualifies only if every requested signal_id fires on the same source row. 'any': row qualifies if any requested signal_id fires. Use 'any' for broadcast-discovery; 'all' for targeted screening.","default":"all"},"order_by":{"type":"string","enum":["recency","market_cap"],"title":"Order By","description":"Result ordering. 'recency' (default): event_date / filing_date DESC. 'market_cap': company market cap DESC NULLS LAST, recency as tiebreaker. Use 'market_cap' for broadcast-digest discovery so high-impact filings aren't pushed past the limit by fresher small-cap noise.","default":"recency"},"since_date":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Since Date","description":"Time-travel lower bound (inclusive) on event_date / filing_date. When provided alongside until_date, defines an explicit date range — overrides recency_days. Format: YYYY-MM-DD. Use for backfilling past digests or anchoring research to specific historical windows."},"until_date":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Until Date","description":"Time-travel upper bound (inclusive) on event_date / filing_date. When provided alongside since_date, defines an explicit date range — overrides recency_days. Defaults to today (UTC) when only since_date is set. Format: YYYY-MM-DD."},"agreement_type_filter":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Agreement Type Filter","description":"Discriminator filter for ir_partnership signals — restricts results to a specific agreement_type (e.g., 'm_and_a_announcement', 'partnership_strategic'). Values mirror services/sec-8k-material-agreement/extraction/schemas.py AgreementType. Only applied to ir_press_release source rows; ignored for other sources."}},"type":"object","required":["signals"],"title":"SignalScreenRequest","description":"Request for cross-company filing intelligence signal screening."},"SignalScreenResponse":{"properties":{"price_attribution":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Price Attribution","description":"The price source's required attribution, present only when the prices in this response come from a source that requires one (IEX HIST)."},"matches":{"items":{"$ref":"#/components/schemas/SignalScreenMatch"},"type":"array","title":"Matches"},"total":{"type":"integer","title":"Total"},"signals_requested":{"items":{"type":"string"},"type":"array","title":"Signals Requested"},"coverage":{"items":{"$ref":"#/components/schemas/SurfaceCoverage"},"type":"array","title":"Coverage","description":"Per-surface coverage DENOMINATORS (#coverage-honesty): distinct companies evaluated on each screened surface. `total` is the MATCH count, NOT a share of the universe — read this to scope the result. A company absent from a surface's source table was NOT evaluated for that surface's criteria (absence ≠ not-fired). NOTE: the denominator window is a fixed trailing ~2y and may exceed a narrower `recency_days` screen window."},"coverage_note":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Coverage Note","description":"Human scope caveat, esp. when a screen mixes surfaces with divergent coverage (e.g. filings ~3,795 vs transcripts ~830)."},"available_signals":{"items":{"type":"string"},"type":"array","title":"Available Signals","description":"(Reserved.) Empty by default. The api does not enumerate the signals catalog in responses; mcp-worker SCREENING_SIGNALS (mcp-worker/src/tools/signal-catalog.ts) is the SSOT for valid IDs. Kept on the model for back-compat with consumers that read the field name."}},"type":"object","required":["matches","total","signals_requested"],"title":"SignalScreenResponse","description":"Response for cross-company filing intelligence signal screening."},"SignalSummaryResponse":{"properties":{"ticker":{"type":"string","title":"Ticker"},"cik":{"type":"string","title":"Cik"},"company_name":{"type":"string","title":"Company Name"},"signals":{"items":{"$ref":"#/components/schemas/SignalCount"},"type":"array","title":"Signals","description":"Per-signal counts, ordered by count DESC, latest_event_date DESC","default":[]},"generated_at":{"type":"string","title":"Generated At","description":"UTC ISO timestamp of the query"}},"type":"object","required":["ticker","cik","company_name","generated_at"],"title":"SignalSummaryResponse","description":"Per-signal availability snapshot for a single company."},"SignalWallItem":{"properties":{"signal_id":{"type":"string","title":"Signal Id","description":"Signal catalog ID (e.g. 'material_weakness')"},"signal_label":{"type":"string","title":"Signal Label","description":"Human-readable signal name"},"category":{"type":"string","title":"Category","description":"Signal category (tone, risk, accounting, etc.)"},"source_event_type":{"type":"string","title":"Source Event Type","description":"Source type: sec_filing, earnings_release_8k, ir_press_release, etc."},"ticker":{"type":"string","title":"Ticker","description":"Company ticker"},"company_name":{"type":"string","title":"Company Name","description":"Company name"},"event_date":{"type":"string","title":"Event Date","description":"Filing/event date (YYYY-MM-DD)"},"fiscal_period":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Fiscal Period","description":"Fiscal period (e.g. 'Q1 FY2026')"},"form_type":{"type":"string","title":"Form Type","description":"Form type (10-K, 10-Q, 8-K, IR, DEF 14A)"},"short_quote":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Short Quote","description":"15-30 word verbatim excerpt from source"},"display_sentence":{"type":"string","title":"Display Sentence","description":"Template-generated one-liner for card display"},"priority_score":{"type":"number","title":"Priority Score","description":"Priority score 0.0-1.0 for ordering"},"drill_url":{"type":"string","title":"Drill Url","description":"Relative URL for drill-down (e.g. '/company/nvda/factsheet')"}},"type":"object","required":["signal_id","signal_label","category","source_event_type","ticker","company_name","event_date","form_type","display_sentence","priority_score","drill_url"],"title":"SignalWallItem","description":"A single signal card for the signal wall."},"SignalWallResponse":{"properties":{"signals":{"items":{"$ref":"#/components/schemas/SignalWallItem"},"type":"array","title":"Signals","description":"Prioritized signal batch"},"generated_at":{"type":"string","title":"Generated At","description":"ISO timestamp of generation"},"ttl_seconds":{"type":"integer","title":"Ttl Seconds","description":"Cache TTL in seconds"}},"type":"object","required":["signals","generated_at","ttl_seconds"],"title":"SignalWallResponse","description":"Response from the signal wall endpoint."},"SoftwareBenchmarks":{"properties":{"metrics":{"items":{"$ref":"#/components/schemas/src__routes__screener__software_benchmarks__MetricBenchmark"},"type":"array","title":"Metrics","description":"Benchmark statistics for each metric"},"total_companies":{"type":"integer","title":"Total Companies","description":"Total software companies in dataset"},"industry_description":{"type":"string","title":"Industry Description","description":"Industry classification","default":"Software (SIC 7370-7379)"},"methodology_notes":{"type":"string","title":"Methodology Notes","description":"Notes on methodology and limitations","default":"Benchmarks based on TTM metrics. Rule of 40 = Revenue Growth (YoY) + EBITDA Margin. ROIC included with caveat: software's near-zero invested capital makes traditional ROIC misleading. Source methodology: McKinsey 'SaaS and the Rule of 40', BCG 'Rule of 40 Lessons'."},"as_of_date":{"type":"string","title":"As Of Date","description":"Date benchmarks were calculated"},"generated_at":{"type":"string","title":"Generated At","description":"Timestamp of generation"}},"type":"object","required":["metrics","total_companies","as_of_date","generated_at"],"title":"SoftwareBenchmarks","description":"Complete software sector financial benchmarks."},"SpecialItem":{"properties":{"period":{"type":"string","title":"Period","description":"Fiscal period (e.g., 'Q2 FY2025')"},"description":{"type":"string","title":"Description","description":"Description of the special item"},"amount_millions":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Amount Millions","description":"Amount in millions USD"},"per_share_impact":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Per Share Impact","description":"Per-share impact (diluted)"},"note":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Note","description":"Additional context or note"}},"type":"object","required":["period","description"],"title":"SpecialItem","description":"Non-recurring or special item affecting earnings.\n\nExamples: Restructuring charges, asset impairments, tax benefits, litigation settlements"},"SupersededBy":{"properties":{"given_on":{"type":"string","title":"Given On","description":"When the newer guide was given (ISO)"},"source_id":{"type":"string","title":"Source Id","description":"Accession of the newer guide's release or call"},"value":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Value","description":"The newer guide's value"}},"type":"object","required":["given_on","source_id"],"title":"SupersededBy"},"SurfaceCoverage":{"properties":{"surface":{"type":"string","title":"Surface"},"companies_covered":{"type":"integer","title":"Companies Covered"}},"type":"object","required":["surface","companies_covered"],"title":"SurfaceCoverage","description":"#coverage-honesty: how many DISTINCT companies were EVALUATED on one screened\nsurface (trailing ~2y) — the screen's DENOMINATOR for that surface, counted from the\nSAME table the surface's handler screens, so a caller can tell '0 of 3,795 filers'\nfrom '0 of ~830 with transcripts'. Absence from a surface's source table means\nNOT-EVALUATED for that surface's criteria, not evaluated-and-not-fired."},"TaxonomyResponse":{"properties":{"sectors":{"items":{"$ref":"#/components/schemas/SectorTaxonomyItem"},"type":"array","title":"Sectors"},"version":{"type":"string","title":"Version"}},"type":"object","required":["sectors","version"],"title":"TaxonomyResponse","description":"Complete sector → industry taxonomy"},"TranscriptCell":{"properties":{"state":{"type":"string","title":"State","description":"'present' | 'pending' | 'none'."},"status":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Status","description":"Raw transcript_processing.status."},"provenance":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Provenance","description":"Source credibility tier: sec_filed | issuer_published | machine_reconstructed | unrecorded."},"accession_number":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Accession Number","description":"The tracked earnings 8-K accession (may be a related 8-K of the row)."},"viewer_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Viewer Url","description":"Versioned in-app transcript viewer URL (no-404 target). Set only when state='present'."},"prepared_remarks_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Prepared Remarks Url","description":"Deep-link to the prepared-remarks section (present-only)."},"qa_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Qa Url","description":"Deep-link to the Q&A section (present-only)."},"watch_until":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Watch Until","description":"ISO date the capture watch ends (pending tracked cells only)."},"late":{"type":"boolean","title":"Late","description":"A capture watch past day 14 from the release: a transcript rarely arrives this late (29 of 13,849 closed watches since 2025).","default":false},"source_table":{"type":"string","title":"Source Table","default":"transcript_processing"},"key_used":{"type":"string","title":"Key Used","default":"accession_number"}},"type":"object","required":["state"],"title":"TranscriptCell","description":"Honest tri-state transcript cell keyed on a spine 8-K accession: the best state across the\nrow's release cycle; `accession_number` names the 8-K that holds it."},"UnextractedFiling":{"properties":{"accession_number":{"type":"string","title":"Accession Number"},"form_type":{"type":"string","title":"Form Type"},"filing_date":{"type":"string","title":"Filing Date","default":""},"fiscal_year":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Fiscal Year"},"fiscal_period":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Fiscal Period"},"covered_but_unextracted":{"type":"boolean","title":"Covered But Unextracted","default":false},"item":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Item"},"period_source":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Period Source"}},"type":"object","required":["accession_number","form_type"],"title":"UnextractedFiling","description":"A filing that EXISTS in MetricDuck (XBRL period index OR sec_filings) but\nwhose section text has not been extracted into filing_text_sections. Surfaced\n(instead of an empty response) so a navigating agent pivots to get_xbrl_facts /\nget_financials for the same period rather than concluding the filing doesn't\nexist."},"UnextractedPeriodFiling":{"properties":{"accession_number":{"type":"string","title":"Accession Number"},"form_type":{"type":"string","title":"Form Type"},"filing_date":{"type":"string","title":"Filing Date","default":""},"fiscal_year":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Fiscal Year"},"fiscal_period":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Fiscal Period"}},"type":"object","required":["accession_number","form_type"],"title":"UnextractedPeriodFiling","description":"A filing that EXISTS in MetricDuck's XBRL DEI period index (or, for an\nearnings 8-K, resolves via the deterministic period derivation) but whose\nrequested section TEXT was not extracted into filing_text_sections.\n\n#582: attached to an EMPTY get_filing_section response so the MCP can tell\nState B (in-scope, text pending — pivot to XBRL/get_financials, the numbers\nARE there) from State C (no XBRL period record at all — terminal \"not in\nMetricDuck\"). Distinct from routes.filing_text.UnextractedFiling (the\nlist_filings analog) so the get_text response model stays self-contained."},"UniverseResponse":{"properties":{"companies":{"items":{"$ref":"#/components/schemas/CompanyInfo"},"type":"array","title":"Companies"},"total_count":{"type":"integer","title":"Total Count"}},"type":"object","required":["companies","total_count"],"title":"UniverseResponse","description":"Response for company universe endpoint."},"UsageCheckRequest":{"properties":{"endpoint":{"type":"string","title":"Endpoint"}},"type":"object","required":["endpoint"],"title":"UsageCheckRequest","description":"Request to check if user can make an API call"},"UsageCheckResponse":{"properties":{"can_proceed":{"type":"boolean","title":"Can Proceed"},"remaining_calls":{"type":"integer","title":"Remaining Calls"},"limit_type":{"type":"string","title":"Limit Type","description":"Type of limit: trial, monthly, or none"},"message":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Message"}},"type":"object","required":["can_proceed","remaining_calls","limit_type"],"title":"UsageCheckResponse","description":"Response for usage check"},"UsageData":{"properties":{"trial_calls_used":{"type":"integer","title":"Trial Calls Used","default":0},"trial_calls_limit":{"type":"integer","title":"Trial Calls Limit","default":10},"monthly_calls_used":{"type":"integer","title":"Monthly Calls Used","default":0},"monthly_calls_limit":{"type":"integer","title":"Monthly Calls Limit","default":100},"reset_date":{"type":"string","format":"date-time","title":"Reset Date"}},"type":"object","title":"UsageData","description":"Usage data for a session"},"UsageStatsResponse":{"properties":{"current_month_requests":{"type":"integer","title":"Current Month Requests"},"monthly_request_limit":{"type":"integer","title":"Monthly Request Limit"},"usage_percentage":{"type":"number","title":"Usage Percentage"},"subscription_tier":{"type":"string","title":"Subscription Tier"},"request_reset_date":{"type":"string","title":"Request Reset Date"},"credits_used":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Credits Used"},"credits_remaining":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Credits Remaining"},"monthly_credit_limit":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Monthly Credit Limit"},"last_call_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Last Call At"},"tool_calls_today":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Tool Calls Today"},"tool_calls_this_month":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Tool Calls This Month"},"daily_tool_call_limit":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Daily Tool Call Limit"},"monthly_tool_call_limit":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Monthly Tool Call Limit"},"allowance_label":{"type":"string","title":"Allowance Label","default":""},"counted_since":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Counted Since"},"count_started_this_month":{"type":"boolean","title":"Count Started This Month","default":false},"daily_cap_enforced":{"type":"boolean","title":"Daily Cap Enforced","default":false},"upgrade_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Upgrade Url"}},"type":"object","required":["current_month_requests","monthly_request_limit","usage_percentage","subscription_tier","request_reset_date"],"title":"UsageStatsResponse","description":"User usage statistics.\n\nThe ``tool_calls_*`` fields are the count the tool-call allowance is measured in: the same\nshared counter and unit the free daily cap uses (middleware/free_daily_cap.py), one per MCP\ntool call (its signed sid) or per REST ``fda_`` request, never per internal api request.\nNone means \"not known\" (internal account, counter unreachable), never zero."},"UserCapabilities":{"properties":{"can_access_api":{"type":"boolean","title":"Can Access Api","default":true},"can_export_data":{"type":"boolean","title":"Can Export Data","default":false},"can_view_historical":{"type":"boolean","title":"Can View Historical","default":true},"data_years_limit":{"type":"integer","title":"Data Years Limit","default":2},"rate_limit_per_minute":{"type":"integer","title":"Rate Limit Per Minute","default":10}},"type":"object","title":"UserCapabilities","description":"User capabilities based on tier"},"UserProfileResponse":{"properties":{"user_id":{"type":"string","title":"User Id"},"email":{"type":"string","title":"Email"},"subscription_tier":{"type":"string","title":"Subscription Tier"},"full_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Full Name"},"company_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Company Name"},"website_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Website Url"},"avatar_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Avatar Url"},"subscription_start_date":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Subscription Start Date"},"subscription_end_date":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Subscription End Date"},"created_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Created At"},"updated_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Updated At"}},"type":"object","required":["user_id","email","subscription_tier"],"title":"UserProfileResponse","description":"Owner-facing profile response — an explicit field WHITELIST (#1556).\n\nNEVER the raw `users` row: that carries billing (`stripe_*`), marketing\nattribution (`utm_*`), and internal quota counters, which a `SELECT *`-minus-id\nhandler leaked to the client. Only the account owner's own display/identity\nfields belong here; quota counters are served (credit-augmented) by\n`/users/usage` + `/users/subscription`.\n\nDisplay fields are Optional: `ensure_user_profile`'s create-on-missing path\npopulates only id/email/subscription_tier/counters, so a brand-new user's row\nhas no full_name/company_name/etc. — required fields there would 500."},"UserProfileUpdate":{"properties":{"full_name":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"title":"Full Name"},"company_name":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"title":"Company Name"},"website_url":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}],"title":"Website Url"}},"type":"object","title":"UserProfileUpdate","description":"User profile update model"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"},"ValuationAnalysis":{"properties":{"market_cap":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Market Cap"},"enterprise_value":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Enterprise Value"},"price_basis":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Price Basis"},"price_basis_date":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Price Basis Date"},"component_absent":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Component Absent"},"pe_ratio_ttm":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Pe Ratio Ttm"},"pb_ratio_ttm":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Pb Ratio Ttm"},"ev_sales_ttm":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Ev Sales Ttm"},"ev_fcf_ttm":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Ev Fcf Ttm"},"peg_ratio":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Peg Ratio"},"expected_growth_rate":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Expected Growth Rate"},"pe_to_roic_ratio":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Pe To Roic Ratio"},"dividend_yield":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Dividend Yield"},"total_shareholder_yield":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Total Shareholder Yield"},"payout_ratio":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Payout Ratio"},"pe_8q_median":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Pe 8Q Median"},"pe_8q_trend":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Pe 8Q Trend"},"pe_8q_volatility":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Pe 8Q Volatility"},"ev_fcf_8q_median":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Ev Fcf 8Q Median"},"ev_fcf_8q_trend":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Ev Fcf 8Q Trend"},"ev_fcf_8q_volatility":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Ev Fcf 8Q Volatility"},"ev_ebitda_ttm":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Ev Ebitda Ttm"},"ev_ebitda_8q_median":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Ev Ebitda 8Q Median"},"ev_ebitda_8q_trend":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Ev Ebitda 8Q Trend"},"ev_ebitda_8q_volatility":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Ev Ebitda 8Q Volatility"},"tier1_as_of_date":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Tier1 As Of Date"},"current_price":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Current Price"},"pct_change_1d":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Pct Change 1D"},"pct_change_1w":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Pct Change 1W"},"pct_change_1m":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Pct Change 1M"},"pct_change_ytd":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Pct Change Ytd"},"pct_change_1y":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Pct Change 1Y"},"high_52w":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"High 52W"},"low_52w":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Low 52W"},"pct_from_52w_high":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Pct From 52W High"},"pct_from_52w_low":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Pct From 52W Low"}},"type":"object","title":"ValuationAnalysis","description":"Valuation multiples"},"WarmupResponse":{"properties":{"status":{"type":"string","title":"Status"},"timestamp":{"type":"string","title":"Timestamp"},"operations_completed":{"type":"integer","title":"Operations Completed"},"cache_entries_warmed":{"type":"integer","title":"Cache Entries Warmed"},"execution_time_ms":{"type":"number","title":"Execution Time Ms"}},"type":"object","required":["status","timestamp","operations_completed","cache_entries_warmed","execution_time_ms"],"title":"WarmupResponse","description":"Warmup operation response"},"WithheldField":{"properties":{"metric":{"type":"string","title":"Metric","description":"Withheld metric: 'revenue' | 'net_income' | 'operating_income' | 'eps_diluted' | 'eps_basic' | 'gross_margin' | 'operating_margin' | 'net_margin' | 'cash_flow' (the whole cash-flow family) | 'segments' (segment monetary values; names are kept, and growth rates too except under 'segment_scale_mismatch', which keeps only those the release states) | 'guidance' (one or more forward-guidance figures; the qualitative text is retained)."},"reason":{"type":"string","title":"Reason","description":"Machine tag for why the field was withheld: 'serve_cap' (implausible magnitude, #1508), 'prior_scale' (the release's prior-year figure is a probable units error against the company's own filings, #3242), 'cash_flow_scale_revenue' (a cash-flow figure over $2B and at least 20x the release's own revenue; the whole cash-flow block is withheld) and the other 'cash_flow_scale_*' arms of the same check (the block withheld on other evidence of a units error; each reason's note says which), 'currency_unverified' (non-USD reporter whose per-figure currency is not yet recorded, #2615), 'margin_implausible' (a margin outside the range a margin can take), 'extractor_conflict' (a release whose results exist only as page images, or whose two readings put the quarters in opposite columns, where our two readings of the named figure disagree), 'image_transcription_unreconciled' (the same kind of release on a surface that shows one reading without the cross-check), 'net_income_sign_conflict' (a table-read net income whose sign contradicts the release's own net margin), 'table_reader_implausible' (a table-read quarterly figure that cannot be the release's: an income under $10K beside revenue of $10M or more, a negative revenue, or a revenue below net income and 20x below the company's filed revenue), 'segment_scale_mismatch' (segment amounts totalling 10^3 or 10^6 times the quarter's filed revenue), 'period_misread' (a figure read from another period's column of a 6-K release, listed against the filing) or 'figure_misread' (a listed figure that is not the company's own for the period: printed nowhere for that line, one segment's, or in cents) or 'figure_unchecked' (a 6-K figure printed only in a column that names no single period, r112).","default":"serve_cap"},"note":{"type":"string","title":"Note","description":"Human-facing explanation ('… check the filing')."},"filing_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Filing Url","description":"Link to the source filing to check the reported figure."}},"type":"object","required":["metric","note"],"title":"WithheldField","description":"A metric that was withheld rather than served, and why. The reasons:\n\n- ``reason=\"serve_cap\"`` (#1508) — the figure exceeded the company's own SEC-filed\n  XBRL magnitude by more than the cap multiple (a probable scale error or\n  cross-wire), so it is served null instead of a physically-impossible number.\n- ``reason=\"prior_scale\"`` (#3242) — the release's prior-year figure for revenue,\n  net income or operating income is more than 10x anything the company has filed\n  for that line AND larger than any figure in the standard revenue and income\n  lines of its XBRL filings (a probable units error — a table in thousands read as\n  dollars), so the metric, current period included, is served null. Runs for every\n  company, not just the serve-cap's confirmed set.\n- ``reason=\"cash_flow_scale_revenue\"`` — the block's largest current operating cash\n  flow, free cash flow or capex figure is over $2B and at least 20x the revenue the\n  same release reports (80x for a block that is not the quarter alone), and larger\n  than anything the company has filed, so the whole cash-flow block is served null.\n  Rows stored before the earnings-release extractor checked this were never\n  re-checked (GLOP-PA served free cash flow $70.00B beside revenue of $89.5M). Runs\n  for every company. Any other ``cash_flow_scale_*`` reason is a further arm of the\n  same check, withholding the same block on different evidence; each arm's rule and\n  note live with it in ``serve_cap.CASH_FLOW_SCALE_ARMS``.\n- ``reason=\"currency_unverified\"`` (#2615) — the company reports in a currency\n  other than USD, and the earnings-release extraction does not yet record the\n  currency of each extracted figure, so the value cannot honestly be rendered as a\n  dollar amount (SONY's ¥2,837.77B was served as \"$2837.77B\").\n- ``reason=\"extractor_conflict\"`` — the release's results exist only as images of\n  its pages, and the two readings of them (v3 and legacy) disagree on this figure\n  beyond rounding, so neither is served; a margin computed from such a figure is\n  withheld with it. On the six such releases measured, v3-first served 10 wrong\n  headline figures; withholding the disagreements leaves 3. The same reason is used\n  for a release where one reading put a headline metric's quarters in opposite\n  columns (r108; NBIS Q2 FY2026 served its prior-year revenue as the quarter's);\n  its note says so.\n- ``reason=\"image_transcription_unreconciled\"`` — the same kind of release on the\n  overview card, which reads one extraction and cannot run that cross-check, so\n  its headline figures are withheld there; the earnings history serves the\n  reconciled ones.\n- ``reason=\"margin_implausible\"`` — the value is a margin outside the range a\n  margin can take (|value| > 1000%), so it is a unit or basis error rather than a\n  real ratio (DaVita served 7,467.38%). Needs no XBRL anchor, so it reaches filings\n  the serve-cap's confirmed set does not. ⚠ The bound is deliberately blunt and it\n  over-suppresses: a pre-revenue issuer with $0.28M of revenue and a $127M loss\n  genuinely has a margin of -44,760% and loses it too. Sparing that case by\n  checking the margin against its own operands does NOT work — BBDC's 44,408% is a\n  1000x scale error that reconciles just as exactly. The operands themselves are\n  always still served.\n- ``reason=\"net_income_sign_conflict\"`` — the net income has the opposite sign to\n  the net margin the same release reports, and it was read by the legacy\n  extractor's income-statement table reader, which takes a column by header\n  position and a row by first keyword match: QMLS served its prior-year $12.1M\n  profit beside a correct -339.3% margin. All 32 such figures measured were wrong\n  against XBRL. The quarterly pair and its growth are withheld; the margin is\n  served. Where the net income came from a model's reading, the same\n  contradiction was the margin's fault as often as not, so it does not fire.\n- ``reason=\"table_reader_implausible\"`` (r121) — the figure is the quarterly pair the\n  legacy extractor's income-statement table reader produced, and it cannot be the\n  release's figure for the line: an operating or net income under $10K beside revenue\n  of $10M or more (GL's per-share 4.84 read as $4,840; TROW's dash as $0.00), a\n  negative revenue (EXR's -$230.0M), or a revenue below a positive net income and at\n  least 20x below the largest revenue the company has filed (FIBK's $16.7M fee line;\n  MSTR's real $125.4M beside a $19.5B gain is 4.7x below and serves). A revenue arm\n  stands only when v3's own reading of the release does not corroborate the figure\n  (JXN's real $168.0M, a variable-annuity writer's revenue net of hedge losses, is\n  spared that way). Graded against the company's own XBRL over every firing in the\n  stored rows, JXN's was the only correct figure. The pair and its growth are\n  withheld; a slot v3 read itself still serves.\n- ``reason=\"segment_scale_mismatch\"`` (#3363 r88) — the release's top-level segment\n  amounts add up to 10^3 or 10^6 times the revenue the company filed for the quarter,\n  while the release's own headline revenue (when it has one) agrees with the filing:\n  so the amounts do not reconcile with the filing: a units error in reading the\n  segment table (HAIN served $263K against a filed $263.1M), or rows that are not\n  revenue at all (IVR's portfolio balances). The segment amounts are withheld, and so is every growth rate the\n  release does not state itself (one computed from the misread table can be wrong:\n  HAIN North America -83.6% against a stated -46%); names are kept.\n\n- ``reason=\"period_misread\"`` / ``\"figure_misread\"`` (r110 / r111) — a 6-K figure\n  listed in ``data/earnings_period_misreads.json`` after a census against the filing:\n  read from another period's column, or not the company's own figure for the period\n  (printed nowhere for that line, one segment's, or EPS in cents served as dollars).\n  From r112 the earnings processor judges every 6-K figure itself (the figure gate):\n  the same two reasons, plus ``\"figure_unchecked\"`` for a figure printed only in a\n  column that names no single period, so it could not be checked.\n\nThese are HONESTY signals, not attestations — a field NOT listed here is not thereby\nverified. An empty list means nothing was withheld; a present entry names exactly\nwhich metric to distrust and points at the filing to check."},"src__models__benchmarks__MetricBenchmark":{"properties":{"sector_code":{"type":"string","title":"Sector Code","description":"Sector code (e.g., 'TECHNOLOGY', 'HEALTHCARE')"},"sector_name":{"type":"string","title":"Sector Name","description":"Human-readable sector name"},"period":{"type":"string","title":"Period","description":"Period type: 'ttm', 'annual', or 'quarterly'"},"median":{"type":"number","title":"Median","description":"Median value across companies in sector"},"p25":{"type":"number","title":"P25","description":"25th percentile (bottom quartile threshold)"},"p75":{"type":"number","title":"P75","description":"75th percentile (top quartile threshold)"},"min_value":{"type":"number","title":"Min Value","description":"Minimum value in sector"},"max_value":{"type":"number","title":"Max Value","description":"Maximum value in sector"},"company_count":{"type":"integer","title":"Company Count","description":"Number of companies included in benchmark"},"as_of_date":{"type":"string","title":"As Of Date","description":"Benchmark calculation date (YYYY-MM-DD)"},"has_warning":{"type":"boolean","title":"Has Warning","description":"True if sector benchmarks may be unreliable for this metric","default":false}},"type":"object","required":["sector_code","sector_name","period","median","p25","p75","min_value","max_value","company_count","as_of_date"],"title":"MetricBenchmark","description":"Sector benchmark statistics for any metric.\n\nProvides percentile-based benchmarks (P25, Median, P75) to enable\nsector-aware analysis and research page generation.\n\nExample:\n    {\n        \"sector_code\": \"TECHNOLOGY\",\n        \"sector_name\": \"Technology\",\n        \"period\": \"ttm\",\n        \"median\": 0.652,\n        \"p25\": 0.485,\n        \"p75\": 0.782,\n        \"min_value\": 0.125,\n        \"max_value\": 0.924,\n        \"company_count\": 847\n    }"},"src__models__earnings_insights__GuidanceItem":{"properties":{"metric":{"type":"string","title":"Metric","description":"Metric name (e.g., 'Revenue', 'EPS', 'Operating Margin')"},"period":{"type":"string","title":"Period","description":"Forward period (e.g., 'Q3 FY2025', 'FY2025')"},"low_estimate":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Low Estimate","description":"Low end of guidance range"},"high_estimate":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"High Estimate","description":"High end of guidance range"},"point_estimate":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Point Estimate","description":"Single point estimate"},"qualitative":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Qualitative","description":"Qualitative guidance text (e.g., 'expect strong growth')"}},"type":"object","required":["metric","period"],"title":"GuidanceItem","description":"Forward-looking guidance provided by management.\n\nCan be quantitative (range or point estimate) or qualitative."},"src__models__xbrl__DimensionInfo":{"properties":{"axis":{"type":"string","title":"Axis","description":"Axis name (e.g., us-gaap:DebtInstrumentAxis)"},"axis_label":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Axis Label","description":"Human-readable axis label from XBRL linkbase"},"axis_display_label":{"type":"string","title":"Axis Display Label","description":"Formatted axis label for display"},"member":{"type":"string","title":"Member","description":"Member value (e.g., aapl:A2025DebtMember)"},"member_label":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Member Label","description":"Human-readable member label from XBRL linkbase"},"member_display_label":{"type":"string","title":"Member Display Label","description":"Formatted member label for display"},"is_typed":{"type":"boolean","title":"Is Typed","description":"True if typed dimension (value-based, not enumerated)","default":false},"member_order":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Member Order","description":"Presentation order from definition linkbase"},"member_depth":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Member Depth","description":"Hierarchy depth (0=root level)"},"member_parent":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Member Parent","description":"Parent member in hierarchy"}},"type":"object","required":["axis","axis_display_label","member","member_display_label"],"title":"DimensionInfo","description":"Dimensional axis and member information with hierarchy metadata."},"src__routes__companies__facts_by_period__DimensionInfo":{"properties":{"axis":{"type":"string","title":"Axis","description":"Axis name (e.g., us-gaap:DebtInstrumentAxis)"},"axis_label":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Axis Label","description":"Human-readable axis label from XBRL linkbase"},"axis_display_label":{"type":"string","title":"Axis Display Label","description":"Formatted axis label for display"},"member":{"type":"string","title":"Member","description":"Member value (e.g., aapl:A2025DebtMember)"},"member_label":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Member Label","description":"Human-readable member label from XBRL linkbase"},"member_display_label":{"type":"string","title":"Member Display Label","description":"Formatted member label for display"},"is_typed":{"type":"boolean","title":"Is Typed","description":"True if typed dimension (value-based, not enumerated)","default":false},"member_order":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Member Order","description":"Presentation order from definition linkbase"},"member_depth":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Member Depth","description":"Hierarchy depth (0=root level)"},"member_parent":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Member Parent","description":"Parent member in hierarchy"},"axis_priority":{"type":"integer","title":"Axis Priority","description":"Axis priority (1=primary, lower=more important)","default":0},"is_subtotal":{"type":"boolean","title":"Is Subtotal","description":"True if this member has child members","default":false},"path":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Path","description":"Display path: 'Americas > iPhone'"}},"type":"object","required":["axis","axis_display_label","member","member_display_label"],"title":"DimensionInfo","description":"Extended dimension info with hierarchy reconstruction fields."},"src__routes__companies__guidance_vs_actual__GuidanceItem":{"properties":{"given_on":{"type":"string","title":"Given On","description":"Transcript event date (ISO)"},"given_for_period":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Given For Period","description":"Period guided FOR, from item.period"},"metric":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Metric"},"value":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Value","description":"Guidance value — may be range, point, or directional"},"specificity":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Specificity"},"speaker":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Speaker"},"source_context":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source Context","description":"transcript_prepared | transcript_qa | transcript_unsplit"},"verbatim":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Verbatim","description":"Exact source quote for the guidance (8-K earnings-release items only; transcript items carry the quote in a separate evidence row — not surfaced here yet)"},"source_id":{"type":"string","title":"Source Id"},"locator":{"additionalProperties":true,"type":"object","title":"Locator"},"period_scope":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Period Scope","description":"'requested' | 'other' | null — vs the requested fiscal period"},"attribution_status":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Attribution Status","description":"'date_period_inconsistent' when this call's given_on and the periods its items target are mutually inconsistent, so MD does not assert the attribution. Absent when the attribution is trusted."},"source_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source Type","description":"Transcript platform (edgar_exhibit / q4inc_vtt / youtube_captions / …) for transcript-sourced items; null for 8-K items. Drives the source link."},"transcript_source":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Transcript Source","description":"Credibility tier (sec_filed / issuer_published / machine_reconstructed / unrecorded) derived from source_type; null for 8-K items."},"basis":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Basis","description":"gaap | non_gaap | unspecified — from the row's own words only: its metric and value, its table row label, or the clause printing its figure. A marker on another figure of the same sentence does not count. Unmarked stays unspecified, never GAAP."},"basis_status":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Basis Status","description":"'multiple_values' when the release prints more than one figure for this 8-K line (GAAP and non-GAAP columns, prior and updated guidance, or a segment and the consolidated total) and the row does not say which one its value is; `other_values` holds the other figure(s). Absent otherwise."},"other_values":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Other Values","description":"The other figure(s) the same release prints for this line, from the row's own verbatim or a sibling row. Set only with basis_status."},"superseded_by":{"anyOf":[{"$ref":"#/components/schemas/SupersededBy"},{"type":"null"}],"description":"Set when a later guide of the same kind (call after call, release after release), given before the target period ended, guided the same metric, period and basis with different figures: that newer guide's date, accession and value. This row is then not current guidance and is never compared. Absent on the current guide and on a reaffirmed one."}},"type":"object","required":["given_on","source_id"],"title":"GuidanceItem"},"src__routes__screener__software_benchmarks__MetricBenchmark":{"properties":{"metric_id":{"type":"string","title":"Metric Id","description":"Metric identifier"},"metric_name":{"type":"string","title":"Metric Name","description":"Human-readable metric name"},"p25":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"P25","description":"25th percentile"},"median":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Median","description":"50th percentile (median)"},"p75":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"P75","description":"75th percentile"},"min_value":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Min Value","description":"Minimum value"},"max_value":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Max Value","description":"Maximum value"},"company_count":{"type":"integer","title":"Company Count","description":"Number of companies in sample"},"unit":{"type":"string","title":"Unit","description":"Unit of measurement","default":"%"},"interpretation":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Interpretation","description":"How to interpret this metric"}},"type":"object","required":["metric_id","metric_name","company_count"],"title":"MetricBenchmark","description":"Benchmark statistics for a single metric."}},"securitySchemes":{"HTTPBearer":{"type":"http","scheme":"bearer"},"APIKeyHeader":{"type":"apiKey","in":"header","name":"X-API-Key"}}}}