{
  "openapi": "3.1.0",
  "info": {
    "title": "Fundamentaly API",
    "version": "1",
    "description": "A REST API for earnings calendars, results, consensus estimates, management guidance, insider trades, short interest, supply chains and prices across 1,300+ companies in the US, Europe, the UK and India. 1,000 free credits on your first key. Docs: https://app.fundamentaly.io/api-docs"
  },
  "servers": [
    {
      "url": "https://api.fundamentaly.io"
    }
  ],
  "security": [
    {
      "bearer": []
    }
  ],
  "components": {
    "securitySchemes": {
      "bearer": {
        "type": "http",
        "scheme": "bearer",
        "description": "Your key, fk_live_..."
      }
    }
  },
  "tags": [
    {
      "name": "Company",
      "description": "Who is covered."
    },
    {
      "name": "Ecosystem",
      "description": "Who a company is compared with, sells to and buys from."
    },
    {
      "name": "Earnings & events",
      "description": "When companies report, and what the price does around it."
    },
    {
      "name": "Estimates",
      "description": "What the Street expects, and whether it was right."
    },
    {
      "name": "Reported financials",
      "description": "What companies actually reported."
    },
    {
      "name": "Prices & risk",
      "description": "How the stock trades."
    },
    {
      "name": "Positioning",
      "description": "Who is short, who is buying, and the read-across."
    },
    {
      "name": "Macro",
      "description": "What is happening outside the company."
    }
  ],
  "paths": {
    "/v1/ceo-history/{ticker}": {
      "get": {
        "operationId": "ceo_history_ticker",
        "summary": "CEO history",
        "description": "Full point-in-time CEO history for ticker — tenure spells (newest first) plus the sourced transition events. Costs 1 credit per call.",
        "tags": [
          "Company"
        ],
        "parameters": [
          {
            "name": "ticker",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "include_transitions",
            "in": "query",
            "required": false,
            "schema": {
              "type": "boolean",
              "default": true
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success. X-Credits-Charged and X-Credits-Remaining report the cost."
          },
          "401": {
            "description": "Missing, invalid, revoked or expired key"
          },
          "402": {
            "description": "Out of credits"
          },
          "403": {
            "description": "The key does not include this endpoint's tab"
          },
          "404": {
            "description": "Not an endpoint available to API keys"
          },
          "429": {
            "description": "Rate limit exceeded; see Retry-After"
          }
        },
        "x-credits": 1,
        "x-credits-per-company": false
      }
    },
    "/v1/ceo-history/{ticker}/at": {
      "get": {
        "operationId": "ceo_history_ticker_at",
        "summary": "CEO on a date",
        "description": "Who was CEO of ticker on a given date (point-in-time lookup). Costs 1 credit per call.",
        "tags": [
          "Company"
        ],
        "parameters": [
          {
            "name": "ticker",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "date",
            "in": "query",
            "required": false,
            "description": "As-of date YYYY-MM-DD (default: today)",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success. X-Credits-Charged and X-Credits-Remaining report the cost."
          },
          "401": {
            "description": "Missing, invalid, revoked or expired key"
          },
          "402": {
            "description": "Out of credits"
          },
          "403": {
            "description": "The key does not include this endpoint's tab"
          },
          "404": {
            "description": "Not an endpoint available to API keys"
          },
          "429": {
            "description": "Rate limit exceeded; see Retry-After"
          }
        },
        "x-credits": 1,
        "x-credits-per-company": false
      }
    },
    "/v1/companies": {
      "get": {
        "operationId": "companies",
        "summary": "All companies",
        "description": "Every company in the universe with its ticker, name, exchange and sector. The starting point for the ticker_exchange values the other endpoints take. Costs 1 credit per call.",
        "tags": [
          "Company"
        ],
        "parameters": [],
        "responses": {
          "200": {
            "description": "Success. X-Credits-Charged and X-Credits-Remaining report the cost."
          },
          "401": {
            "description": "Missing, invalid, revoked or expired key"
          },
          "402": {
            "description": "Out of credits"
          },
          "403": {
            "description": "The key does not include this endpoint's tab"
          },
          "404": {
            "description": "Not an endpoint available to API keys"
          },
          "429": {
            "description": "Rate limit exceeded; see Retry-After"
          }
        },
        "x-credits": 1,
        "x-credits-per-company": false
      }
    },
    "/v1/logos": {
      "get": {
        "operationId": "logos",
        "summary": "Logos",
        "description": "Logo URLs for up to 100 companies in one call. Costs 1 credit per call.",
        "tags": [
          "Company"
        ],
        "parameters": [
          {
            "name": "tickers",
            "in": "query",
            "required": true,
            "description": "Comma-separated ticker_exchange values (e.g. AAPL@US,MSFT@US)",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success. X-Credits-Charged and X-Credits-Remaining report the cost."
          },
          "401": {
            "description": "Missing, invalid, revoked or expired key"
          },
          "402": {
            "description": "Out of credits"
          },
          "403": {
            "description": "The key does not include this endpoint's tab"
          },
          "404": {
            "description": "Not an endpoint available to API keys"
          },
          "429": {
            "description": "Rate limit exceeded; see Retry-After"
          }
        },
        "x-credits": 1,
        "x-credits-per-company": false
      }
    },
    "/v1/reference-data": {
      "get": {
        "operationId": "reference_data",
        "summary": "Company data",
        "description": "Get reference company data with optional filtering. Costs 1 credit per call.",
        "tags": [
          "Company"
        ],
        "parameters": [
          {
            "name": "ticker",
            "in": "query",
            "required": false,
            "description": "Filter by ticker (e.g., AAPL@US)",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "exchange",
            "in": "query",
            "required": false,
            "description": "Filter by exchange (e.g., US, LN)",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "sector",
            "in": "query",
            "required": false,
            "description": "Filter by GICS sector",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "sub_industry",
            "in": "query",
            "required": false,
            "description": "Filter by GICS sub-industry",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "index",
            "in": "query",
            "required": false,
            "description": "Filter by index (e.g., SP500, FTSE100)",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success. X-Credits-Charged and X-Credits-Remaining report the cost."
          },
          "401": {
            "description": "Missing, invalid, revoked or expired key"
          },
          "402": {
            "description": "Out of credits"
          },
          "403": {
            "description": "The key does not include this endpoint's tab"
          },
          "404": {
            "description": "Not an endpoint available to API keys"
          },
          "429": {
            "description": "Rate limit exceeded; see Retry-After"
          }
        },
        "x-credits": 1,
        "x-credits-per-company": false
      }
    },
    "/v1/company/{ticker}/customers": {
      "get": {
        "operationId": "company_ticker_customers",
        "summary": "Customers",
        "description": "Customers {ticker} names in its annual filings, plus companies that name {ticker} as a supplier. Costs 1 credit per call.",
        "tags": [
          "Ecosystem"
        ],
        "parameters": [
          {
            "name": "ticker",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success. X-Credits-Charged and X-Credits-Remaining report the cost."
          },
          "401": {
            "description": "Missing, invalid, revoked or expired key"
          },
          "402": {
            "description": "Out of credits"
          },
          "403": {
            "description": "The key does not include this endpoint's tab"
          },
          "404": {
            "description": "Not an endpoint available to API keys"
          },
          "429": {
            "description": "Rate limit exceeded; see Retry-After"
          }
        },
        "x-credits": 1,
        "x-credits-per-company": false
      }
    },
    "/v1/company/{ticker}/suppliers": {
      "get": {
        "operationId": "company_ticker_suppliers",
        "summary": "Suppliers",
        "description": "Suppliers {ticker} names in its annual filings, plus companies that name {ticker} as a customer. Costs 1 credit per call.",
        "tags": [
          "Ecosystem"
        ],
        "parameters": [
          {
            "name": "ticker",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success. X-Credits-Charged and X-Credits-Remaining report the cost."
          },
          "401": {
            "description": "Missing, invalid, revoked or expired key"
          },
          "402": {
            "description": "Out of credits"
          },
          "403": {
            "description": "The key does not include this endpoint's tab"
          },
          "404": {
            "description": "Not an endpoint available to API keys"
          },
          "429": {
            "description": "Rate limit exceeded; see Retry-After"
          }
        },
        "x-credits": 1,
        "x-credits-per-company": false
      }
    },
    "/v1/company/{ticker}/peers": {
      "get": {
        "operationId": "company_ticker_peers",
        "summary": "Peers",
        "description": "Peers of {ticker}, derived from same GICS sub-industry, ranked by market-cap proximity. Costs 1 credit per call.",
        "tags": [
          "Ecosystem"
        ],
        "parameters": [
          {
            "name": "ticker",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "default": 20
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success. X-Credits-Charged and X-Credits-Remaining report the cost."
          },
          "401": {
            "description": "Missing, invalid, revoked or expired key"
          },
          "402": {
            "description": "Out of credits"
          },
          "403": {
            "description": "The key does not include this endpoint's tab"
          },
          "404": {
            "description": "Not an endpoint available to API keys"
          },
          "429": {
            "description": "Rate limit exceeded; see Retry-After"
          }
        },
        "x-credits": 1,
        "x-credits-per-company": false
      }
    },
    "/v1/company/{ticker}/read-x-sentiment": {
      "get": {
        "operationId": "company_ticker_read_x_sentiment",
        "summary": "Read-across",
        "description": "Read-across sentiment for a company on a given date, today by default. Costs 1 credit per call.",
        "tags": [
          "Ecosystem"
        ],
        "parameters": [
          {
            "name": "ticker",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "as_of",
            "in": "query",
            "required": false,
            "description": "ISO date (YYYY-MM-DD). Defaults to today. Must be <= today.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success. X-Credits-Charged and X-Credits-Remaining report the cost."
          },
          "401": {
            "description": "Missing, invalid, revoked or expired key"
          },
          "402": {
            "description": "Out of credits"
          },
          "403": {
            "description": "The key does not include this endpoint's tab"
          },
          "404": {
            "description": "Not an endpoint available to API keys"
          },
          "429": {
            "description": "Rate limit exceeded; see Retry-After"
          }
        },
        "x-credits": 1,
        "x-credits-per-company": false
      }
    },
    "/v1/earnings-calendar": {
      "get": {
        "operationId": "earnings_calendar",
        "summary": "Earnings calendar",
        "description": "Get corporate events/earnings calendar with flexible filtering. Costs 1 credit per company.",
        "tags": [
          "Earnings & events"
        ],
        "parameters": [
          {
            "name": "ticker",
            "in": "query",
            "required": false,
            "description": "Filter by single ticker_exchange (e.g., AAPL@US). For multiple tickers use 'tickers' param instead.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "tickers",
            "in": "query",
            "required": false,
            "description": "Comma-separated ticker_exchange values (e.g., 'AAPL@US,MSFT@US'). Takes precedence over 'ticker' if both provided.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "start_date",
            "in": "query",
            "required": false,
            "description": "Start date in YYYY-MM-DD format",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "end_date",
            "in": "query",
            "required": false,
            "description": "End date in YYYY-MM-DD format",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "event_type",
            "in": "query",
            "required": false,
            "description": "Filter by event type(s), comma-separated (e.g., earnings_conference_call,interim_statement)",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "index",
            "in": "query",
            "required": false,
            "description": "Filter by index (e.g., FTSE100, SP500, STOXX600), or 'TOP' for the largest companies per day (see top_per_day)",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "top_per_day",
            "in": "query",
            "required": false,
            "description": "Only used with index=TOP: max earnings/sales events per calendar day, ranked by market cap",
            "schema": {
              "type": "integer",
              "default": 15
            }
          },
          {
            "name": "order_by_market_cap",
            "in": "query",
            "required": false,
            "description": "When true, sort by market cap (largest first), then by date, then by ticker. When false (default), sort by date then by ticker. Ignored when filtering by a single ticker.",
            "schema": {
              "type": "boolean",
              "default": false
            }
          },
          {
            "name": "sort_order",
            "in": "query",
            "required": false,
            "description": "Date sort direction: 'desc' (newest first, default) or 'asc' (oldest first). Acts as secondary sort when order_by_market_cap is true.",
            "schema": {
              "type": "string",
              "default": "desc"
            }
          },
          {
            "name": "page",
            "in": "query",
            "required": false,
            "description": "Page number (1-indexed). Enables pagination when provided.",
            "schema": {
              "type": "integer"
            }
          },
          {
            "name": "page_size",
            "in": "query",
            "required": false,
            "description": "Number of events per page (max 100). Only used when page is provided.",
            "schema": {
              "type": "integer",
              "default": 20
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success. X-Credits-Charged and X-Credits-Remaining report the cost."
          },
          "401": {
            "description": "Missing, invalid, revoked or expired key"
          },
          "402": {
            "description": "Out of credits"
          },
          "403": {
            "description": "The key does not include this endpoint's tab"
          },
          "404": {
            "description": "Not an endpoint available to API keys"
          },
          "429": {
            "description": "Rate limit exceeded; see Retry-After"
          }
        },
        "x-credits": 1,
        "x-credits-per-company": true
      }
    },
    "/v1/earnings-results": {
      "get": {
        "operationId": "earnings_results",
        "summary": "Earnings returns",
        "description": "Get realized event-period returns for corporate events in a date range. Costs 5 credits per company.",
        "tags": [
          "Earnings & events"
        ],
        "parameters": [
          {
            "name": "start_date",
            "in": "query",
            "required": true,
            "description": "Start date (YYYY-MM-DD)",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "end_date",
            "in": "query",
            "required": true,
            "description": "End date (YYYY-MM-DD)",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "index",
            "in": "query",
            "required": false,
            "description": "Filter by index (e.g., 'SP500')",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "tickers",
            "in": "query",
            "required": false,
            "description": "Comma-separated ticker_exchange values (e.g., 'AAPL@US,MSFT@US')",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "type_group",
            "in": "query",
            "required": false,
            "description": "Event type filter: 'earnings', 'sales', 'earnings-sales'",
            "schema": {
              "type": "string",
              "default": "earnings-sales"
            }
          },
          {
            "name": "include_eps",
            "in": "query",
            "required": false,
            "description": "Include EPS actual, estimate, and surprise for each event",
            "schema": {
              "type": "boolean",
              "default": false
            }
          },
          {
            "name": "return_type",
            "in": "query",
            "required": false,
            "description": "Return type: total (raw), market_model (stock - benchmark), beta_adjusted (stock - beta*benchmark)",
            "schema": {
              "type": "string",
              "default": "total"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success. X-Credits-Charged and X-Credits-Remaining report the cost."
          },
          "401": {
            "description": "Missing, invalid, revoked or expired key"
          },
          "402": {
            "description": "Out of credits"
          },
          "403": {
            "description": "The key does not include this endpoint's tab"
          },
          "404": {
            "description": "Not an endpoint available to API keys"
          },
          "429": {
            "description": "Rate limit exceeded; see Retry-After"
          }
        },
        "x-credits": 5,
        "x-credits-per-company": true
      }
    },
    "/v1/earnings-performance": {
      "get": {
        "operationId": "earnings_performance",
        "summary": "Price around earnings",
        "description": "Get stock performance around corporate events. Costs 5 credits per company.",
        "tags": [
          "Earnings & events"
        ],
        "parameters": [
          {
            "name": "ticker",
            "in": "query",
            "required": false,
            "description": "Ticker in format TICKER@EXCHANGE (e.g., AAPL@US). For multiple tickers use 'tickers' instead.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "tickers",
            "in": "query",
            "required": false,
            "description": "Comma-separated tickers (e.g., 'AAPL@US,MSFT@US'). Returns results keyed by ticker. Takes precedence over ticker.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "num_events",
            "in": "query",
            "required": false,
            "description": "Number of most recent earnings events to include",
            "schema": {
              "type": "integer",
              "default": 4
            }
          },
          {
            "name": "pre_days",
            "in": "query",
            "required": false,
            "description": "Number of trading days before event window to include (0 = none)",
            "schema": {
              "type": "integer",
              "default": 0
            }
          },
          {
            "name": "post_days",
            "in": "query",
            "required": false,
            "description": "Number of trading days after event window to include (0 = none)",
            "schema": {
              "type": "integer",
              "default": 0
            }
          },
          {
            "name": "event_period",
            "in": "query",
            "required": false,
            "description": "Event period as 'start-end' range, e.g., '0-1' (days 0,1 — the default; canonical close(t-1)→close(t+1) reaction window), '-1-1' (days -1,0,1), '0-0' (day 0 only). Overrides event_window if provided.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "event_window",
            "in": "query",
            "required": false,
            "description": "Symmetric days before/after event (legacy; baselines at close(-window-1)). When 0 and event_period unset, the canonical event_period='0-1' applies. Ignored if event_period is set.",
            "schema": {
              "type": "integer",
              "default": 0
            }
          },
          {
            "name": "type_group",
            "in": "query",
            "required": false,
            "description": "Filter by type_group: 'earnings', 'sales', 'earnings-sales' (both), or 'other'. Recommended over event_type.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "event_type",
            "in": "query",
            "required": false,
            "description": "Deprecated: use type_group instead. Event type filter(s), comma-separated.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "include_upcoming",
            "in": "query",
            "required": false,
            "description": "Include upcoming events whose pre-period has already started (at least 1 trading day of pre_days window is in the past)",
            "schema": {
              "type": "boolean",
              "default": false
            }
          },
          {
            "name": "return_type",
            "in": "query",
            "required": false,
            "description": "Return type: total (raw), market_model (stock - benchmark), beta_adjusted (stock - beta*benchmark)",
            "schema": {
              "type": "string",
              "default": "total"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success. X-Credits-Charged and X-Credits-Remaining report the cost."
          },
          "401": {
            "description": "Missing, invalid, revoked or expired key"
          },
          "402": {
            "description": "Out of credits"
          },
          "403": {
            "description": "The key does not include this endpoint's tab"
          },
          "404": {
            "description": "Not an endpoint available to API keys"
          },
          "429": {
            "description": "Rate limit exceeded; see Retry-After"
          }
        },
        "x-credits": 5,
        "x-credits-per-company": true
      }
    },
    "/v1/earnings-theme": {
      "get": {
        "operationId": "earnings_theme",
        "summary": "Earnings drivers",
        "description": "Get AI-generated earnings theme summaries — one sentence per ticker describing what consistently drives the stock around earnings. Costs 1 credit per company.",
        "tags": [
          "Earnings & events"
        ],
        "parameters": [
          {
            "name": "tickers",
            "in": "query",
            "required": true,
            "description": "Comma-separated ticker_exchange values (e.g., 'AAPL@US,MSFT@US')",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success. X-Credits-Charged and X-Credits-Remaining report the cost."
          },
          "401": {
            "description": "Missing, invalid, revoked or expired key"
          },
          "402": {
            "description": "Out of credits"
          },
          "403": {
            "description": "The key does not include this endpoint's tab"
          },
          "404": {
            "description": "Not an endpoint available to API keys"
          },
          "429": {
            "description": "Rate limit exceeded; see Retry-After"
          }
        },
        "x-credits": 1,
        "x-credits-per-company": true
      }
    },
    "/v1/earnings-volatility": {
      "get": {
        "operationId": "earnings_volatility",
        "summary": "Earnings moves",
        "description": "Get earnings volatility summary for multiple tickers in a single request. Costs 5 credits per company.",
        "tags": [
          "Earnings & events"
        ],
        "parameters": [
          {
            "name": "tickers",
            "in": "query",
            "required": false,
            "description": "Comma-separated ticker_exchange values (e.g., 'AAPL@US,MSFT@US')",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "index",
            "in": "query",
            "required": false,
            "description": "Index name (e.g., 'SP500'). Alternative to tickers.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "num_events",
            "in": "query",
            "required": false,
            "description": "Number of historical events to analyze",
            "schema": {
              "type": "integer",
              "default": 8
            }
          },
          {
            "name": "type_group",
            "in": "query",
            "required": false,
            "description": "Event type filter: 'earnings', 'sales', 'earnings-sales'",
            "schema": {
              "type": "string",
              "default": "earnings-sales"
            }
          },
          {
            "name": "include_events",
            "in": "query",
            "required": false,
            "description": "Include individual event breakdowns per ticker",
            "schema": {
              "type": "boolean",
              "default": false
            }
          },
          {
            "name": "return_type",
            "in": "query",
            "required": false,
            "description": "Return type: total (raw), market_model (stock - benchmark), beta_adjusted (stock - beta*benchmark)",
            "schema": {
              "type": "string",
              "default": "total"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success. X-Credits-Charged and X-Credits-Remaining report the cost."
          },
          "401": {
            "description": "Missing, invalid, revoked or expired key"
          },
          "402": {
            "description": "Out of credits"
          },
          "403": {
            "description": "The key does not include this endpoint's tab"
          },
          "404": {
            "description": "Not an endpoint available to API keys"
          },
          "429": {
            "description": "Rate limit exceeded; see Retry-After"
          }
        },
        "x-credits": 5,
        "x-credits-per-company": true
      }
    },
    "/v1/implied-earnings-move": {
      "get": {
        "operationId": "implied_earnings_move",
        "summary": "Implied move",
        "description": "Get options-implied earnings move for upcoming earnings events. Costs 5 credits per company.",
        "tags": [
          "Earnings & events"
        ],
        "parameters": [
          {
            "name": "ticker",
            "in": "query",
            "required": false,
            "description": "One or more tickers, comma-separated (e.g., 'AAPL@US,MSFT@US')",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "event",
            "in": "query",
            "required": false,
            "description": "Earnings event period (e.g., 'Q4 2025', 'Q1 2026'). Overrides days_ahead.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "days_ahead",
            "in": "query",
            "required": false,
            "description": "Look-ahead window for upcoming earnings (days)",
            "schema": {
              "type": "integer",
              "default": 30
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success. X-Credits-Charged and X-Credits-Remaining report the cost."
          },
          "401": {
            "description": "Missing, invalid, revoked or expired key"
          },
          "402": {
            "description": "Out of credits"
          },
          "403": {
            "description": "The key does not include this endpoint's tab"
          },
          "404": {
            "description": "Not an endpoint available to API keys"
          },
          "429": {
            "description": "Rate limit exceeded; see Retry-After"
          }
        },
        "x-credits": 5,
        "x-credits-per-company": true
      }
    },
    "/v1/estimate-revisions": {
      "get": {
        "operationId": "estimate_revisions",
        "summary": "Revisions",
        "description": "How the consensus moved — the dated path of each estimate, not just today's level. Costs 1 credit per company.",
        "tags": [
          "Estimates"
        ],
        "parameters": [
          {
            "name": "tickers",
            "in": "query",
            "required": false,
            "description": "Comma-separated ticker_exchange values (e.g., 'AAPL@US')",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "index",
            "in": "query",
            "required": false,
            "description": "Index name. Alternative to tickers.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "metric",
            "in": "query",
            "required": false,
            "description": "Comma-separated metrics: 'eps', 'revenue'. Default: eps.",
            "schema": {
              "type": "string",
              "default": "eps"
            }
          },
          {
            "name": "period",
            "in": "query",
            "required": false,
            "description": "Filter by period type: 'annual' or 'quarter'",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "fiscal_period_end_date",
            "in": "query",
            "required": false,
            "description": "Restrict to one fiscal period end (YYYY-MM-DD)",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "since",
            "in": "query",
            "required": false,
            "description": "Only snapshots on/after this date (YYYY-MM-DD). Default: 90 days back.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "forward_only",
            "in": "query",
            "required": false,
            "description": "Only periods that have not ended yet",
            "schema": {
              "type": "boolean",
              "default": true
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success. X-Credits-Charged and X-Credits-Remaining report the cost."
          },
          "401": {
            "description": "Missing, invalid, revoked or expired key"
          },
          "402": {
            "description": "Out of credits"
          },
          "403": {
            "description": "The key does not include this endpoint's tab"
          },
          "404": {
            "description": "Not an endpoint available to API keys"
          },
          "429": {
            "description": "Rate limit exceeded; see Retry-After"
          }
        },
        "x-credits": 1,
        "x-credits-per-company": true
      }
    },
    "/v1/estimates": {
      "get": {
        "operationId": "estimates",
        "summary": "Consensus",
        "description": "Forward analyst consensus for multiple tickers, with the metric as data. Costs 1 credit per company.",
        "tags": [
          "Estimates"
        ],
        "parameters": [
          {
            "name": "tickers",
            "in": "query",
            "required": false,
            "description": "Comma-separated ticker_exchange values (e.g., 'AAPL@US,MSFT@US')",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "index",
            "in": "query",
            "required": false,
            "description": "Index name (e.g., 'SP500'). Alternative to tickers.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "metric",
            "in": "query",
            "required": false,
            "description": "Comma-separated metrics: 'eps', 'revenue'. Default: all.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "period",
            "in": "query",
            "required": false,
            "description": "Filter by period type: 'annual' or 'quarter'",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "fiscal_year",
            "in": "query",
            "required": false,
            "description": "Filter by fiscal year (e.g., 2026)",
            "schema": {
              "type": "integer"
            }
          },
          {
            "name": "fiscal_period",
            "in": "query",
            "required": false,
            "description": "Filter by fiscal period: Q1, Q2, Q3, Q4",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Max periods per ticker (default: 20) — applied before metric expansion",
            "schema": {
              "type": "integer",
              "default": 20
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success. X-Credits-Charged and X-Credits-Remaining report the cost."
          },
          "401": {
            "description": "Missing, invalid, revoked or expired key"
          },
          "402": {
            "description": "Out of credits"
          },
          "403": {
            "description": "The key does not include this endpoint's tab"
          },
          "404": {
            "description": "Not an endpoint available to API keys"
          },
          "429": {
            "description": "Rate limit exceeded; see Retry-After"
          }
        },
        "x-credits": 1,
        "x-credits-per-company": true
      }
    },
    "/v1/surprises": {
      "get": {
        "operationId": "surprises",
        "summary": "Surprises",
        "description": "Reported actual vs expected — EPS and revenue — with the metric as data. Costs 1 credit per company.",
        "tags": [
          "Estimates"
        ],
        "parameters": [
          {
            "name": "tickers",
            "in": "query",
            "required": false,
            "description": "Comma-separated ticker_exchange values (e.g., 'AAPL@US')",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "index",
            "in": "query",
            "required": false,
            "description": "Index name. Alternative to tickers.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "metric",
            "in": "query",
            "required": false,
            "description": "Comma-separated metrics: 'eps', 'revenue'. Default: both.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "period",
            "in": "query",
            "required": false,
            "description": "Revenue only: 'annual' or 'quarter'",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "fiscal_year",
            "in": "query",
            "required": false,
            "description": "Filter by fiscal year (e.g., 2026)",
            "schema": {
              "type": "integer"
            }
          },
          {
            "name": "num_events",
            "in": "query",
            "required": false,
            "description": "Recent prints per ticker per metric (default: 8)",
            "schema": {
              "type": "integer",
              "default": 8
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success. X-Credits-Charged and X-Credits-Remaining report the cost."
          },
          "401": {
            "description": "Missing, invalid, revoked or expired key"
          },
          "402": {
            "description": "Out of credits"
          },
          "403": {
            "description": "The key does not include this endpoint's tab"
          },
          "404": {
            "description": "Not an endpoint available to API keys"
          },
          "429": {
            "description": "Rate limit exceeded; see Retry-After"
          }
        },
        "x-credits": 1,
        "x-credits-per-company": true
      }
    },
    "/v1/deep-estimates": {
      "get": {
        "operationId": "deep_estimates",
        "summary": "Deep estimates",
        "description": "Deep estimates — issuer-compiled analyst consensus, the Street's expectations bar for upcoming periods, line by line. Costs 5 credits per company.",
        "tags": [
          "Estimates"
        ],
        "parameters": [
          {
            "name": "tickers",
            "in": "query",
            "required": false,
            "description": "Comma-separated ticker_exchange (e.g. 'KNEBV@HE,BAYN@GR')",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "index",
            "in": "query",
            "required": false,
            "description": "Index name. Alternative to tickers.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "canonical_metric",
            "in": "query",
            "required": false,
            "description": "Filter to a canonical metric, e.g. 'revenue', 'eps_adjusted'",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "metric_search",
            "in": "query",
            "required": false,
            "description": "Case-insensitive substring match on the verbatim metric label",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "period_type",
            "in": "query",
            "required": false,
            "description": "Q1|Q2|Q3|Q4|H1|H2|9M|FY",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "fiscal_year",
            "in": "query",
            "required": false,
            "description": "Fiscal year the period ends in",
            "schema": {
              "type": "integer"
            }
          },
          {
            "name": "estimates_only",
            "in": "query",
            "required": false,
            "description": "Exclude reported-actual columns",
            "schema": {
              "type": "boolean",
              "default": true
            }
          },
          {
            "name": "exclude_submetrics",
            "in": "query",
            "required": false,
            "description": "Drop derived sub-lines (growth rates, margins)",
            "schema": {
              "type": "boolean",
              "default": false
            }
          },
          {
            "name": "as_of",
            "in": "query",
            "required": false,
            "description": "Point-in-time: the snapshot on/before this date (YYYY-MM-DD). Defaults to latest.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Max records per ticker",
            "schema": {
              "type": "integer",
              "default": 200
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success. X-Credits-Charged and X-Credits-Remaining report the cost."
          },
          "401": {
            "description": "Missing, invalid, revoked or expired key"
          },
          "402": {
            "description": "Out of credits"
          },
          "403": {
            "description": "The key does not include this endpoint's tab"
          },
          "404": {
            "description": "Not an endpoint available to API keys"
          },
          "429": {
            "description": "Rate limit exceeded; see Retry-After"
          }
        },
        "x-credits": 5,
        "x-credits-per-company": true
      }
    },
    "/v1/deep-estimates/coverage": {
      "get": {
        "operationId": "deep_estimates_coverage",
        "summary": "Deep estimates coverage",
        "description": "Which companies have deep-estimates coverage, how fresh it is, and how deep. Costs 1 credit per call.",
        "tags": [
          "Estimates"
        ],
        "parameters": [
          {
            "name": "include_unmapped",
            "in": "query",
            "required": false,
            "description": "Include source companies not in our universe (ticker_exchange NULL)",
            "schema": {
              "type": "boolean",
              "default": true
            }
          },
          {
            "name": "max_stale_days",
            "in": "query",
            "required": false,
            "description": "Only companies whose consensus is at most this many days old",
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success. X-Credits-Charged and X-Credits-Remaining report the cost."
          },
          "401": {
            "description": "Missing, invalid, revoked or expired key"
          },
          "402": {
            "description": "Out of credits"
          },
          "403": {
            "description": "The key does not include this endpoint's tab"
          },
          "404": {
            "description": "Not an endpoint available to API keys"
          },
          "429": {
            "description": "Rate limit exceeded; see Retry-After"
          }
        },
        "x-credits": 1,
        "x-credits-per-company": false
      }
    },
    "/v1/deep-estimates/summary": {
      "get": {
        "operationId": "deep_estimates_summary",
        "summary": "Target prices",
        "description": "Deep-estimates target price and recommendation split per ticker. Costs 1 credit per company.",
        "tags": [
          "Estimates"
        ],
        "parameters": [
          {
            "name": "tickers",
            "in": "query",
            "required": false,
            "description": "Comma-separated ticker_exchange",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "index",
            "in": "query",
            "required": false,
            "description": "Index name. Alternative to tickers.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success. X-Credits-Charged and X-Credits-Remaining report the cost."
          },
          "401": {
            "description": "Missing, invalid, revoked or expired key"
          },
          "402": {
            "description": "Out of credits"
          },
          "403": {
            "description": "The key does not include this endpoint's tab"
          },
          "404": {
            "description": "Not an endpoint available to API keys"
          },
          "429": {
            "description": "Rate limit exceeded; see Retry-After"
          }
        },
        "x-credits": 1,
        "x-credits-per-company": true
      }
    },
    "/v1/fundamental-kpis/{ticker}": {
      "get": {
        "operationId": "fundamental_kpis_ticker",
        "summary": "Financials",
        "description": "Everything a company reported: statements, ratios and the revenue split. Costs 5 credits per call.",
        "tags": [
          "Reported financials"
        ],
        "parameters": [
          {
            "name": "ticker",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "include",
            "in": "query",
            "required": false,
            "description": "Comma-separated sections: statements, ratios, segments",
            "schema": {
              "type": "string",
              "default": "statements,ratios,segments"
            }
          },
          {
            "name": "period",
            "in": "query",
            "required": false,
            "description": "Q1, Q2, Q3, Q4 or FY",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "year",
            "in": "query",
            "required": false,
            "description": "Fiscal year, e.g. 2025",
            "schema": {
              "type": "integer"
            }
          },
          {
            "name": "statement",
            "in": "query",
            "required": false,
            "description": "income_statement | balance_sheet | cash_flow",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "metric_name",
            "in": "query",
            "required": false,
            "description": "Filter statement lines by metric (partial match)",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "ratio_category",
            "in": "query",
            "required": false,
            "description": "margin | leverage | liquidity",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "segment_metric",
            "in": "query",
            "required": false,
            "description": "Which metric to decompose",
            "schema": {
              "type": "string",
              "default": "revenue"
            }
          },
          {
            "name": "segment_dimension",
            "in": "query",
            "required": false,
            "description": "geography | business_segment | product_service | where",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "include_rollups",
            "in": "query",
            "required": false,
            "description": "Include segment roll-up/alias members. Off by default: summing them double-counts.",
            "schema": {
              "type": "boolean",
              "default": false
            }
          },
          {
            "name": "tags",
            "in": "query",
            "required": false,
            "description": "'canonical' (default): the 25 curated metrics, synonyms resolved and subtotals derived. 'all': every us-gaap concept the filer tagged, in the order and wording of the filing.",
            "schema": {
              "type": "string",
              "default": "canonical"
            }
          },
          {
            "name": "scope",
            "in": "query",
            "required": false,
            "description": "With tags=all: 'face' | 'other' | 'all'",
            "schema": {
              "type": "string",
              "default": "all"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "default": 5000
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success. X-Credits-Charged and X-Credits-Remaining report the cost."
          },
          "401": {
            "description": "Missing, invalid, revoked or expired key"
          },
          "402": {
            "description": "Out of credits"
          },
          "403": {
            "description": "The key does not include this endpoint's tab"
          },
          "404": {
            "description": "Not an endpoint available to API keys"
          },
          "429": {
            "description": "Rate limit exceeded; see Retry-After"
          }
        },
        "x-credits": 5,
        "x-credits-per-company": false
      }
    },
    "/v1/fundamental-kpis/{ticker}/coverage": {
      "get": {
        "operationId": "fundamental_kpis_ticker_coverage",
        "summary": "Financials coverage",
        "description": "What we hold for this company, and over what span — before asking for it. Costs 1 credit per call.",
        "tags": [
          "Reported financials"
        ],
        "parameters": [
          {
            "name": "ticker",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success. X-Credits-Charged and X-Credits-Remaining report the cost."
          },
          "401": {
            "description": "Missing, invalid, revoked or expired key"
          },
          "402": {
            "description": "Out of credits"
          },
          "403": {
            "description": "The key does not include this endpoint's tab"
          },
          "404": {
            "description": "Not an endpoint available to API keys"
          },
          "429": {
            "description": "Rate limit exceeded; see Retry-After"
          }
        },
        "x-credits": 1,
        "x-credits-per-company": false
      }
    },
    "/v1/guidance/{ticker}": {
      "get": {
        "operationId": "guidance_ticker",
        "summary": "Management guidance",
        "description": "All management guidance for ticker, every metric and every period. Costs 1 credit per call.",
        "tags": [
          "Reported financials"
        ],
        "parameters": [
          {
            "name": "ticker",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "metric_key",
            "in": "query",
            "required": false,
            "description": "Filter to a single metric_key",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success. X-Credits-Charged and X-Credits-Remaining report the cost."
          },
          "401": {
            "description": "Missing, invalid, revoked or expired key"
          },
          "402": {
            "description": "Out of credits"
          },
          "403": {
            "description": "The key does not include this endpoint's tab"
          },
          "404": {
            "description": "Not an endpoint available to API keys"
          },
          "429": {
            "description": "Rate limit exceeded; see Retry-After"
          }
        },
        "x-credits": 1,
        "x-credits-per-company": false
      }
    },
    "/v1/market-data/{ticker}": {
      "get": {
        "operationId": "market_data_ticker",
        "summary": "Daily prices",
        "description": "Get market data (daily prices and volume) for a specific ticker. Costs 1 credit per call.",
        "tags": [
          "Prices & risk"
        ],
        "parameters": [
          {
            "name": "ticker",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "start_date",
            "in": "query",
            "required": true,
            "description": "Start date in YYYY-MM-DD format",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "end_date",
            "in": "query",
            "required": true,
            "description": "End date in YYYY-MM-DD format",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "fields",
            "in": "query",
            "required": false,
            "description": "Comma-separated subset of fields to return, e.g. 'date,close_price'. Available: date, close_price, close_price_adjusted, close_volume, currency, market_cap, market_cap_usd, pe_ttm, pe_ratio, forward_pe, ev_ebitda. date is always included. Omit for the default set (everything except forward_pe and ev_ebitda, which are opt-in).",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "resample",
            "in": "query",
            "required": false,
            "description": "Frequency: D (daily, default), W (week-ending close), M (month-end close). Each bucket returns its last observation; the newest bucket is partial.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success. X-Credits-Charged and X-Credits-Remaining report the cost."
          },
          "401": {
            "description": "Missing, invalid, revoked or expired key"
          },
          "402": {
            "description": "Out of credits"
          },
          "403": {
            "description": "The key does not include this endpoint's tab"
          },
          "404": {
            "description": "Not an endpoint available to API keys"
          },
          "429": {
            "description": "Rate limit exceeded; see Retry-After"
          }
        },
        "x-credits": 1,
        "x-credits-per-company": false
      }
    },
    "/v1/news": {
      "get": {
        "operationId": "news",
        "summary": "News",
        "description": "Recent deduped news per company. Costs 1 credit per company.",
        "tags": [
          "Prices & risk"
        ],
        "parameters": [
          {
            "name": "tickers",
            "in": "query",
            "required": true,
            "description": "Comma-separated ticker_exchange values (e.g. VZ@US,HWDN@LN)",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "days_back",
            "in": "query",
            "required": false,
            "description": "Look-back window in days",
            "schema": {
              "type": "integer",
              "default": 30
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Max items per ticker (legacy, non-paginated mode only)",
            "schema": {
              "type": "integer",
              "default": 50
            }
          },
          {
            "name": "canonical_only",
            "in": "query",
            "required": false,
            "description": "Collapse syndicated duplicates to one row per event",
            "schema": {
              "type": "boolean",
              "default": true
            }
          },
          {
            "name": "trusted_only",
            "in": "query",
            "required": false,
            "description": "Only specialised/trade-press (site-scoped) items",
            "schema": {
              "type": "boolean",
              "default": false
            }
          },
          {
            "name": "page",
            "in": "query",
            "required": false,
            "description": "Page number (1-indexed). Enables pagination when provided, returning a flat newest-first feed merged across all tickers.",
            "schema": {
              "type": "integer"
            }
          },
          {
            "name": "page_size",
            "in": "query",
            "required": false,
            "description": "Number of articles per page (max 100). Only used when page is provided.",
            "schema": {
              "type": "integer",
              "default": 20
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success. X-Credits-Charged and X-Credits-Remaining report the cost."
          },
          "401": {
            "description": "Missing, invalid, revoked or expired key"
          },
          "402": {
            "description": "Out of credits"
          },
          "403": {
            "description": "The key does not include this endpoint's tab"
          },
          "404": {
            "description": "Not an endpoint available to API keys"
          },
          "429": {
            "description": "Rate limit exceeded; see Retry-After"
          }
        },
        "x-credits": 1,
        "x-credits-per-company": true
      }
    },
    "/v1/price-returns": {
      "get": {
        "operationId": "price_returns",
        "summary": "Returns",
        "description": "Get price returns for multiple tickers over a given period. Costs 5 credits per company.",
        "tags": [
          "Prices & risk"
        ],
        "parameters": [
          {
            "name": "tickers",
            "in": "query",
            "required": true,
            "description": "Comma-separated ticker_exchange values (e.g. AAPL@US,MSFT@US)",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "period",
            "in": "query",
            "required": false,
            "description": "Return period: 1d, 1w, 1m, 3m, 6m, 1y, wtd, mtd, ytd",
            "schema": {
              "type": "string",
              "default": "ytd"
            }
          },
          {
            "name": "return_type",
            "in": "query",
            "required": false,
            "description": "Return type: total (raw), market_model (stock - benchmark), beta_adjusted (stock - beta*benchmark)",
            "schema": {
              "type": "string",
              "default": "total"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success. X-Credits-Charged and X-Credits-Remaining report the cost."
          },
          "401": {
            "description": "Missing, invalid, revoked or expired key"
          },
          "402": {
            "description": "Out of credits"
          },
          "403": {
            "description": "The key does not include this endpoint's tab"
          },
          "404": {
            "description": "Not an endpoint available to API keys"
          },
          "429": {
            "description": "Rate limit exceeded; see Retry-After"
          }
        },
        "x-credits": 5,
        "x-credits-per-company": true
      }
    },
    "/v1/risk-model/{ticker}": {
      "get": {
        "operationId": "risk_model_ticker",
        "summary": "Return breakdown",
        "description": "Latest market and sector sensitivity, plus the last N days of return decomposition for ticker. Costs 5 credits per call.",
        "tags": [
          "Prices & risk"
        ],
        "parameters": [
          {
            "name": "ticker",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "days",
            "in": "query",
            "required": false,
            "description": "Trading days of decomposition to return",
            "schema": {
              "type": "integer",
              "default": 90
            }
          },
          {
            "name": "summary_only",
            "in": "query",
            "required": false,
            "description": "Return the sensitivities and cumulative contributions only, dropping the per-day array. Same window, ~1/20th the payload.",
            "schema": {
              "type": "boolean",
              "default": false
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success. X-Credits-Charged and X-Credits-Remaining report the cost."
          },
          "401": {
            "description": "Missing, invalid, revoked or expired key"
          },
          "402": {
            "description": "Out of credits"
          },
          "403": {
            "description": "The key does not include this endpoint's tab"
          },
          "404": {
            "description": "Not an endpoint available to API keys"
          },
          "429": {
            "description": "Rate limit exceeded; see Retry-After"
          }
        },
        "x-credits": 5,
        "x-credits-per-company": false
      }
    },
    "/v1/risk-model/{ticker}/exposures": {
      "get": {
        "operationId": "risk_model_ticker_exposures",
        "summary": "Market sensitivity",
        "description": "How sensitive the stock is to the market and its sector over time: beta drift, R² and idiosyncratic volatility, one row per day for charting. Costs 5 credits per call.",
        "tags": [
          "Prices & risk"
        ],
        "parameters": [
          {
            "name": "ticker",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "days",
            "in": "query",
            "required": false,
            "description": "Trading days of history",
            "schema": {
              "type": "integer",
              "default": 365
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success. X-Credits-Charged and X-Credits-Remaining report the cost."
          },
          "401": {
            "description": "Missing, invalid, revoked or expired key"
          },
          "402": {
            "description": "Out of credits"
          },
          "403": {
            "description": "The key does not include this endpoint's tab"
          },
          "404": {
            "description": "Not an endpoint available to API keys"
          },
          "429": {
            "description": "Rate limit exceeded; see Retry-After"
          }
        },
        "x-credits": 5,
        "x-credits-per-company": false
      }
    },
    "/v1/seasonality/{ticker}": {
      "get": {
        "operationId": "seasonality_ticker",
        "summary": "Seasonality",
        "description": "Monthly seasonality profile for one ticker. Costs 5 credits per call.",
        "tags": [
          "Prices & risk"
        ],
        "parameters": [
          {
            "name": "ticker",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "years",
            "in": "query",
            "required": false,
            "description": "Lookback window in years",
            "schema": {
              "type": "integer",
              "default": 15
            }
          },
          {
            "name": "benchmark",
            "in": "query",
            "required": false,
            "description": "Override benchmark ticker_exchange (defaults to the ticker's regional index ETF)",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success. X-Credits-Charged and X-Credits-Remaining report the cost."
          },
          "401": {
            "description": "Missing, invalid, revoked or expired key"
          },
          "402": {
            "description": "Out of credits"
          },
          "403": {
            "description": "The key does not include this endpoint's tab"
          },
          "404": {
            "description": "Not an endpoint available to API keys"
          },
          "429": {
            "description": "Rate limit exceeded; see Retry-After"
          }
        },
        "x-credits": 5,
        "x-credits-per-company": false
      }
    },
    "/v1/sector-returns": {
      "get": {
        "operationId": "sector_returns",
        "summary": "Sector returns",
        "description": "Calculate returns by GICS sector over a date range. Costs 1 credit per company.",
        "tags": [
          "Prices & risk"
        ],
        "parameters": [
          {
            "name": "start_date",
            "in": "query",
            "required": true,
            "description": "Start date in YYYY-MM-DD format",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "end_date",
            "in": "query",
            "required": true,
            "description": "End date in YYYY-MM-DD format",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "exchange",
            "in": "query",
            "required": false,
            "description": "Filter by exchange (e.g., US, LN, GR)",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "index",
            "in": "query",
            "required": false,
            "description": "Filter by index name (e.g., S&P 500, FTSE 100)",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "include_all_tickers",
            "in": "query",
            "required": false,
            "description": "Include all tickers with their returns in each sector (not just top/bottom 3)",
            "schema": {
              "type": "boolean",
              "default": false
            }
          },
          {
            "name": "include_market_cap",
            "in": "query",
            "required": false,
            "description": "Include latest market cap (from end_date) for each ticker",
            "schema": {
              "type": "boolean",
              "default": false
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success. X-Credits-Charged and X-Credits-Remaining report the cost."
          },
          "401": {
            "description": "Missing, invalid, revoked or expired key"
          },
          "402": {
            "description": "Out of credits"
          },
          "403": {
            "description": "The key does not include this endpoint's tab"
          },
          "404": {
            "description": "Not an endpoint available to API keys"
          },
          "429": {
            "description": "Rate limit exceeded; see Retry-After"
          }
        },
        "x-credits": 1,
        "x-credits-per-company": true
      }
    },
    "/v1/insider-transactions": {
      "get": {
        "operationId": "insider_transactions",
        "summary": "Insider trades",
        "description": "Get insider transactions across multiple tickers with filtering options. Costs 1 credit per company.",
        "tags": [
          "Positioning"
        ],
        "parameters": [
          {
            "name": "tickers",
            "in": "query",
            "required": false,
            "description": "Comma-separated ticker_exchange values (e.g., 'AAPL@US,MSFT@US')",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "exchange",
            "in": "query",
            "required": false,
            "description": "Exchange filter (e.g., 'US')",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "index",
            "in": "query",
            "required": false,
            "description": "Index filter (e.g., 'SP500')",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "start_date",
            "in": "query",
            "required": false,
            "description": "Start date (YYYY-MM-DD)",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "end_date",
            "in": "query",
            "required": false,
            "description": "End date (YYYY-MM-DD)",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "transaction_types",
            "in": "query",
            "required": false,
            "description": "Comma-separated transaction types (e.g., 'Buy,Sell')",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "transaction_groups",
            "in": "query",
            "required": false,
            "description": "Comma-separated coarse groups (Buy,Sell,Award,Exercise,Tax,Other)",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Maximum number of results",
            "schema": {
              "type": "integer",
              "default": 100
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success. X-Credits-Charged and X-Credits-Remaining report the cost."
          },
          "401": {
            "description": "Missing, invalid, revoked or expired key"
          },
          "402": {
            "description": "Out of credits"
          },
          "403": {
            "description": "The key does not include this endpoint's tab"
          },
          "404": {
            "description": "Not an endpoint available to API keys"
          },
          "429": {
            "description": "Rate limit exceeded; see Retry-After"
          }
        },
        "x-credits": 1,
        "x-credits-per-company": true
      }
    },
    "/v1/short-interest": {
      "get": {
        "operationId": "short_interest",
        "summary": "Short interest",
        "description": "Latest short interest reading per ticker, for US and UK equities. Costs 1 credit per company.",
        "tags": [
          "Positioning"
        ],
        "parameters": [
          {
            "name": "ticker",
            "in": "query",
            "required": false,
            "description": "One or more tickers, comma-separated (e.g., 'AAPL@US,GME@US')",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "index",
            "in": "query",
            "required": false,
            "description": "Index name (e.g., 'SP500'). Alternative to ticker.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success. X-Credits-Charged and X-Credits-Remaining report the cost."
          },
          "401": {
            "description": "Missing, invalid, revoked or expired key"
          },
          "402": {
            "description": "Out of credits"
          },
          "403": {
            "description": "The key does not include this endpoint's tab"
          },
          "404": {
            "description": "Not an endpoint available to API keys"
          },
          "429": {
            "description": "Rate limit exceeded; see Retry-After"
          }
        },
        "x-credits": 1,
        "x-credits-per-company": true
      }
    },
    "/v1/short-interest/earnings-comparison": {
      "get": {
        "operationId": "short_interest_earnings_comparison",
        "summary": "Shorts into earnings",
        "description": "Compare the latest short interest reading with the reading at the equivalent point (same number of days) before the previous earnings date. Costs 1 credit per call.",
        "tags": [
          "Positioning"
        ],
        "parameters": [
          {
            "name": "ticker",
            "in": "query",
            "required": true,
            "description": "One ticker (US only, e.g. 'AAPL@US')",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success. X-Credits-Charged and X-Credits-Remaining report the cost."
          },
          "401": {
            "description": "Missing, invalid, revoked or expired key"
          },
          "402": {
            "description": "Out of credits"
          },
          "403": {
            "description": "The key does not include this endpoint's tab"
          },
          "404": {
            "description": "Not an endpoint available to API keys"
          },
          "429": {
            "description": "Rate limit exceeded; see Retry-After"
          }
        },
        "x-credits": 1,
        "x-credits-per-company": false
      }
    },
    "/v1/short-interest/history": {
      "get": {
        "operationId": "short_interest_history",
        "summary": "Short interest history",
        "description": "Short interest as a time series for one ticker, oldest first. Costs 1 credit per call.",
        "tags": [
          "Positioning"
        ],
        "parameters": [
          {
            "name": "ticker",
            "in": "query",
            "required": true,
            "description": "One ticker (e.g. 'GME@US' or 'BARC@LN')",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "start_date",
            "in": "query",
            "required": false,
            "description": "Earliest date to return (YYYY-MM-DD)",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "end_date",
            "in": "query",
            "required": false,
            "description": "Latest date to return (YYYY-MM-DD)",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Keep only the N most recent points",
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success. X-Credits-Charged and X-Credits-Remaining report the cost."
          },
          "401": {
            "description": "Missing, invalid, revoked or expired key"
          },
          "402": {
            "description": "Out of credits"
          },
          "403": {
            "description": "The key does not include this endpoint's tab"
          },
          "404": {
            "description": "Not an endpoint available to API keys"
          },
          "429": {
            "description": "Rate limit exceeded; see Retry-After"
          }
        },
        "x-credits": 1,
        "x-credits-per-company": false
      }
    },
    "/v1/macro-events": {
      "get": {
        "operationId": "macro_events",
        "summary": "Macro calendar",
        "description": "Flexible macro-economic events endpoint. Costs 1 credit per call.",
        "tags": [
          "Macro"
        ],
        "parameters": [
          {
            "name": "start_date",
            "in": "query",
            "required": false,
            "description": "Start date YYYY-MM-DD (default: today)",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "end_date",
            "in": "query",
            "required": false,
            "description": "End date YYYY-MM-DD (default: today + 14 days)",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "currency",
            "in": "query",
            "required": false,
            "description": "Comma-separated currency codes (e.g., USD,EUR,GBP)",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "country",
            "in": "query",
            "required": false,
            "description": "Country code mapped to currency (e.g., US, GB, EU, JP)",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "category",
            "in": "query",
            "required": false,
            "description": "Event category (Inflation, Central Bank, Employment, GDP, Manufacturing, Services, Housing, Other)",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "event_name",
            "in": "query",
            "required": false,
            "description": "Exact event name filter (e.g., CPI m/m)",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "include_surprises",
            "in": "query",
            "required": false,
            "description": "Include surprise stats (beat/miss rate) per event",
            "schema": {
              "type": "boolean",
              "default": false
            }
          },
          {
            "name": "include_history",
            "in": "query",
            "required": false,
            "description": "Include last N historical releases per event",
            "schema": {
              "type": "boolean",
              "default": false
            }
          },
          {
            "name": "history_count",
            "in": "query",
            "required": false,
            "description": "Number of past releases when include_history=true",
            "schema": {
              "type": "integer",
              "default": 6
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success. X-Credits-Charged and X-Credits-Remaining report the cost."
          },
          "401": {
            "description": "Missing, invalid, revoked or expired key"
          },
          "402": {
            "description": "Out of credits"
          },
          "403": {
            "description": "The key does not include this endpoint's tab"
          },
          "404": {
            "description": "Not an endpoint available to API keys"
          },
          "429": {
            "description": "Rate limit exceeded; see Retry-After"
          }
        },
        "x-credits": 1,
        "x-credits-per-company": false
      }
    },
    "/v1/macro-sensitivity": {
      "get": {
        "operationId": "macro_sensitivity",
        "summary": "Macro movers",
        "description": "Get stocks most sensitive to surprises in a specific macro event. Costs 5 credits per call.",
        "tags": [
          "Macro"
        ],
        "parameters": [
          {
            "name": "event_name",
            "in": "query",
            "required": true,
            "description": "Macro event name (e.g., 'CPI m/m')",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "currency",
            "in": "query",
            "required": true,
            "description": "Macro event currency (e.g., 'USD')",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "surprise_direction",
            "in": "query",
            "required": false,
            "description": "'above_estimate' (actual > forecast), 'below_estimate' (actual < forecast), or 'both'. Legacy values 'positive'/'negative' still accepted.",
            "schema": {
              "type": "string",
              "default": "both"
            }
          },
          {
            "name": "filtering_mode",
            "in": "query",
            "required": false,
            "description": "Ranking mode. Vanilla: 'top', 'bottom', 'absolute'. Ex-market (excess over benchmark): 'top_ex_market', 'bottom_ex_market', 'absolute_ex_market'",
            "schema": {
              "type": "string",
              "default": "absolute_ex_market"
            }
          },
          {
            "name": "index",
            "in": "query",
            "required": false,
            "description": "Filter by index (SP500, FTSE100, STOXX600, NIFTY50)",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "min_events",
            "in": "query",
            "required": false,
            "description": "Minimum events for inclusion",
            "schema": {
              "type": "integer",
              "default": 5
            }
          },
          {
            "name": "min_coverage",
            "in": "query",
            "required": false,
            "description": "Minimum coverage percentage (0-100). Filters out stocks that weren't present for enough events (e.g. new IPOs). Applied to the relevant direction.",
            "schema": {
              "type": "number"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Max results",
            "schema": {
              "type": "integer",
              "default": 50
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success. X-Credits-Charged and X-Credits-Remaining report the cost."
          },
          "401": {
            "description": "Missing, invalid, revoked or expired key"
          },
          "402": {
            "description": "Out of credits"
          },
          "403": {
            "description": "The key does not include this endpoint's tab"
          },
          "404": {
            "description": "Not an endpoint available to API keys"
          },
          "429": {
            "description": "Rate limit exceeded; see Retry-After"
          }
        },
        "x-credits": 5,
        "x-credits-per-company": false
      }
    },
    "/v1/macro-sensitivity/events": {
      "get": {
        "operationId": "macro_sensitivity_events",
        "summary": "Macro releases",
        "description": "The macro releases the sensitivity screen covers, with each one's currency, category and event count. Pick an event_name and currency here, then call macro-sensitivity with them. Costs 1 credit per call.",
        "tags": [
          "Macro"
        ],
        "parameters": [],
        "responses": {
          "200": {
            "description": "Success. X-Credits-Charged and X-Credits-Remaining report the cost."
          },
          "401": {
            "description": "Missing, invalid, revoked or expired key"
          },
          "402": {
            "description": "Out of credits"
          },
          "403": {
            "description": "The key does not include this endpoint's tab"
          },
          "404": {
            "description": "Not an endpoint available to API keys"
          },
          "429": {
            "description": "Rate limit exceeded; see Retry-After"
          }
        },
        "x-credits": 1,
        "x-credits-per-company": false
      }
    },
    "/v1/macro-indices/series": {
      "get": {
        "operationId": "macro_indices_series",
        "summary": "Macro series",
        "description": "Find macro series. Use this first to discover the code you need, then call /observations with it. Costs 1 credit per call.",
        "tags": [
          "Macro"
        ],
        "parameters": [
          {
            "name": "geo",
            "in": "query",
            "required": false,
            "description": "Comma-separated ISO-2 countries, e.g. DE,FR,GB",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "family",
            "in": "query",
            "required": false,
            "description": "Comma-separated families: price, volume_production, volume_retail, turnover_retail, volume_tourism, volume_travel, employment, lodging_kpi, confidence, weight",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "code",
            "in": "query",
            "required": false,
            "description": "Comma-separated COICOP/NACE codes, e.g. CP0122,C1107",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "search",
            "in": "query",
            "required": false,
            "description": "Case-insensitive substring match on the series label",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "measure",
            "in": "query",
            "required": false,
            "description": "GB price measure: CPI (default), CPIH, or 'all' for both",
            "schema": {
              "type": "string",
              "default": "CPI"
            }
          },
          {
            "name": "classification",
            "in": "query",
            "required": false,
            "description": "Comma-separated code systems: ECOICOP2, NACE2, EU_BCS, ONS_COICOP, ONS_RSI, BLS_CPI, BLS_PPI, BLS_CES, BEA_PCE, TSA, UMICH, STR_US",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Max series to return",
            "schema": {
              "type": "integer",
              "default": 200
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success. X-Credits-Charged and X-Credits-Remaining report the cost."
          },
          "401": {
            "description": "Missing, invalid, revoked or expired key"
          },
          "402": {
            "description": "Out of credits"
          },
          "403": {
            "description": "The key does not include this endpoint's tab"
          },
          "404": {
            "description": "Not an endpoint available to API keys"
          },
          "429": {
            "description": "Rate limit exceeded; see Retry-After"
          }
        },
        "x-credits": 1,
        "x-credits-per-company": false
      }
    },
    "/v1/macro-indices/observations": {
      "get": {
        "operationId": "macro_indices_observations",
        "summary": "Macro data",
        "description": "Observations for the matching series. Levels, not rates — compute YoY yourself, with one documented exception (below). Costs 1 credit per call.",
        "tags": [
          "Macro"
        ],
        "parameters": [
          {
            "name": "code",
            "in": "query",
            "required": false,
            "description": "Comma-separated COICOP/NACE codes, e.g. CP0122,C1107",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "geo",
            "in": "query",
            "required": false,
            "description": "Comma-separated ISO-2 countries, e.g. DE,FR,GB",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "family",
            "in": "query",
            "required": false,
            "description": "Comma-separated families: price, volume_production, volume_retail, turnover_retail, volume_tourism, volume_travel, employment, lodging_kpi, confidence, weight",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "series_key",
            "in": "query",
            "required": false,
            "description": "Exact series_key, overrides the other filters",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "start_period",
            "in": "query",
            "required": false,
            "description": "Earliest period, inclusive. YYYY-MM (monthly), YYYY (annual) or YYYY-MM-DD (daily/weekly)",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "end_period",
            "in": "query",
            "required": false,
            "description": "Latest period, inclusive. Same shapes as start_period",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "measure",
            "in": "query",
            "required": false,
            "description": "GB price measure: CPI (default), CPIH, or 'all' for both",
            "schema": {
              "type": "string",
              "default": "CPI"
            }
          },
          {
            "name": "classification",
            "in": "query",
            "required": false,
            "description": "Comma-separated code systems: ECOICOP2, NACE2, EU_BCS, ONS_COICOP, ONS_RSI, BLS_CPI, BLS_PPI, BLS_CES, BEA_PCE, TSA, UMICH, STR_US",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Max observations to return",
            "schema": {
              "type": "integer",
              "default": 2000
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success. X-Credits-Charged and X-Credits-Remaining report the cost."
          },
          "401": {
            "description": "Missing, invalid, revoked or expired key"
          },
          "402": {
            "description": "Out of credits"
          },
          "403": {
            "description": "The key does not include this endpoint's tab"
          },
          "404": {
            "description": "Not an endpoint available to API keys"
          },
          "429": {
            "description": "Rate limit exceeded; see Retry-After"
          }
        },
        "x-credits": 1,
        "x-credits-per-company": false
      }
    }
  }
}