{"openapi":"3.1.0","info":{"title":"yfin Yahoo Finance API","version":"0.1.0","description":"Hosted market data API for quotes, historical prices, options chains, fundamentals, screeners, market calendars, symbol search, and research workflows."},"servers":[{"url":"https://api.yfin.dev"}],"tags":[{"name":"Market Data","description":"Current quotes, market state, and broad market context."},{"name":"Prices","description":"Historical and compact time-series price data."},{"name":"Options","description":"Options expirations and chains."},{"name":"Fundamentals","description":"Company, fund, and financial metric data."},{"name":"Search","description":"Symbol search, lookup, and autocomplete."},{"name":"Discovery","description":"Screeners, sector data, industry data, and trending symbols."},{"name":"Calendar","description":"Date-based market events."},{"name":"Research","description":"Research-oriented symbol context and related instruments."},{"name":"System","description":"Service metadata and advanced endpoints."}],"components":{"schemas":{"ErrorDetail":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable error message."}},"additionalProperties":false},"ErrorResponse":{"type":"object","required":["ok","error"],"properties":{"ok":{"type":"boolean","const":false},"error":{"$ref":"#/components/schemas/ErrorDetail"},"allow":{"type":"array","items":{"type":"string"},"description":"Allowed HTTP methods when the error code is method_not_allowed."},"meta":{"type":"object","additionalProperties":true,"description":"Response metadata when available."}},"additionalProperties":true},"RateLimitResponse":{"type":"object","required":["ok","error","rate_limit"],"properties":{"ok":{"type":"boolean","const":false},"error":{"$ref":"#/components/schemas/ErrorDetail"},"rate_limit":{"type":"object","required":["tier","retry_after_seconds","upgrade"],"properties":{"tier":{"type":"string","enum":["anonymous","contact","key"]},"retry_after_seconds":{"type":"integer","minimum":1},"upgrade":{"type":"string"}},"additionalProperties":false}},"additionalProperties":false}}},"paths":{"/v1/health":{"get":{"tags":["System"],"operationId":"getHealth","summary":"Service health.","description":"Returns basic yfin service status and the number of currently shipped REST endpoints.","responses":{"200":{"description":"Health response.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}}}},"/v1/endpoints":{"get":{"tags":["System"],"operationId":"listEndpoints","summary":"Endpoint Catalog","description":"Returns the machine-readable catalog of supported yfin endpoints. Use this for tool discovery, code generation, and agents that need to inspect available routes programmatically.","responses":{"200":{"description":"Endpoint catalog.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}}}},"/v1/raw/{endpointId}":{"get":{"tags":["System"],"operationId":"getRawEndpoint","summary":"Raw Endpoint By ID","description":"Advanced endpoint for calling a supported yfin endpoint by its catalog ID. Most applications should use the named routes such as quote, history, options, fundamentals, search, or screener.","parameters":[{"name":"endpointId","in":"path","required":true,"schema":{"type":"string"},"description":"Endpoint ID from /v1/endpoints."},{"name":"X-Yfin-Contact","in":"header","required":false,"schema":{"type":"string"},"description":"Stable contact identity for higher free request limits, for example an email address or service name."},{"name":"X-Yfin-Key","in":"header","required":false,"schema":{"type":"string"},"description":"API key for higher-volume access. Authorization: Bearer is also supported."}],"responses":{"200":{"description":"Data returned by the selected endpoint.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request parameters.","headers":{"x-yfin-error-code":{"description":"Stable yfin error code.","schema":{"type":"string"}},"x-yfin-error-message":{"description":"Short human-readable error message.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"bad_request":{"summary":"Invalid request","value":{"ok":false,"error":{"code":"bad_request","message":"Invalid request parameters."}}}}}}},"404":{"description":"Unknown route or endpoint.","headers":{"x-yfin-error-code":{"description":"Stable yfin error code.","schema":{"type":"string"}},"x-yfin-error-message":{"description":"Short human-readable error message.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"not_found":{"summary":"Unknown route","value":{"ok":false,"error":{"code":"not_found","message":"Unknown yfin route."}}},"endpoint_not_found":{"summary":"Unknown endpoint ID","value":{"ok":false,"error":{"code":"endpoint_not_found","message":"Endpoint is not in the endpoint catalog."}}}}}}},"405":{"description":"HTTP method is not allowed for this endpoint.","headers":{"x-yfin-error-code":{"description":"Stable yfin error code.","schema":{"type":"string"}},"x-yfin-error-message":{"description":"Short human-readable error message.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"method_not_allowed":{"summary":"Method not allowed","value":{"ok":false,"error":{"code":"method_not_allowed","message":"POST is not allowed for this endpoint."},"allow":["GET"]}}}}}},"410":{"description":"Endpoint exists in the catalog but is not currently available.","headers":{"x-yfin-error-code":{"description":"Stable yfin error code.","schema":{"type":"string"}},"x-yfin-error-message":{"description":"Short human-readable error message.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"endpoint_not_shipped":{"summary":"Endpoint unavailable","value":{"ok":false,"error":{"code":"endpoint_not_shipped","message":"Endpoint is not currently available."}}}}}}},"429":{"description":"Request limit exceeded. Retry-After is included.","headers":{"x-yfin-error-code":{"description":"Stable yfin error code.","schema":{"type":"string"}},"x-yfin-error-message":{"description":"Short human-readable error message.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer","minimum":1}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitResponse"},"examples":{"rate_limited":{"summary":"Request limit exceeded","value":{"ok":false,"error":{"code":"rate_limited","message":"Request limit exceeded."},"rate_limit":{"tier":"anonymous","retry_after_seconds":42,"upgrade":"Email sam@yfin.dev for an API key."}}}}}}},"502":{"description":"yfin could not complete the upstream data request.","headers":{"x-yfin-error-code":{"description":"Stable yfin error code.","schema":{"type":"string"}},"x-yfin-error-message":{"description":"Short human-readable error message.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"origin_error":{"summary":"Upstream request failed","value":{"ok":false,"meta":{"provider":"yahoo","endpoint":"v7.quote","family":"quote","generated_at":"2026-05-04T19:10:01.075Z","route":"quote"},"error":{"code":"origin_error","message":"The service could not complete the request. Retry shortly."}}}}}}},"503":{"description":"The service is temporarily unavailable or busy.","headers":{"x-yfin-error-code":{"description":"Stable yfin error code.","schema":{"type":"string"}},"x-yfin-error-message":{"description":"Short human-readable error message.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer","minimum":1}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"service_busy":{"summary":"Service busy","value":{"ok":false,"error":{"code":"service_busy","message":"The service is temporarily busy. Retry shortly."}}},"origin_unavailable":{"summary":"Data service unavailable","value":{"ok":false,"meta":{"provider":"yahoo","endpoint":"v7.quote","family":"quote","generated_at":"2026-05-04T19:10:01.073Z","route":"quote"},"error":{"code":"origin_unavailable","message":"The service is temporarily unavailable. Retry shortly."}}}}}}}}}},"/v1/autocomplete":{"get":{"tags":["Search"],"operationId":"getAutocomplete","summary":"Autocomplete Symbols","description":"Returns symbol and company suggestions for a partial query.\n\nUse this for search boxes, command palettes, and agents that need to turn incomplete user text into likely ticker symbols before requesting quotes or history.\n\nTypical output includes matching symbols, company names, exchanges, instrument types, and regions when available.","parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string"},"description":"Search query. Alias: query."},{"name":"X-Yfin-Contact","in":"header","required":false,"schema":{"type":"string"},"description":"Stable contact identity for higher free request limits, for example an email address or service name."},{"name":"X-Yfin-Key","in":"header","required":false,"schema":{"type":"string"},"description":"API key for higher-volume access. Authorization: Bearer is also supported."}],"responses":{"200":{"description":"Autocomplete Symbols response.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request parameters.","headers":{"x-yfin-error-code":{"description":"Stable yfin error code.","schema":{"type":"string"}},"x-yfin-error-message":{"description":"Short human-readable error message.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"bad_request":{"summary":"Invalid request","value":{"ok":false,"error":{"code":"bad_request","message":"autocomplete requires q= or query=."}}}}}}},"404":{"description":"Unknown route or endpoint.","headers":{"x-yfin-error-code":{"description":"Stable yfin error code.","schema":{"type":"string"}},"x-yfin-error-message":{"description":"Short human-readable error message.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"not_found":{"summary":"Unknown route","value":{"ok":false,"error":{"code":"not_found","message":"Unknown yfin route."}}},"endpoint_not_found":{"summary":"Unknown endpoint ID","value":{"ok":false,"error":{"code":"endpoint_not_found","message":"Endpoint is not in the endpoint catalog."}}}}}}},"405":{"description":"HTTP method is not allowed for this endpoint.","headers":{"x-yfin-error-code":{"description":"Stable yfin error code.","schema":{"type":"string"}},"x-yfin-error-message":{"description":"Short human-readable error message.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"method_not_allowed":{"summary":"Method not allowed","value":{"ok":false,"error":{"code":"method_not_allowed","message":"POST is not allowed for this endpoint."},"allow":["GET"]}}}}}},"429":{"description":"Request limit exceeded. Retry-After is included.","headers":{"x-yfin-error-code":{"description":"Stable yfin error code.","schema":{"type":"string"}},"x-yfin-error-message":{"description":"Short human-readable error message.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer","minimum":1}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitResponse"},"examples":{"rate_limited":{"summary":"Request limit exceeded","value":{"ok":false,"error":{"code":"rate_limited","message":"Request limit exceeded."},"rate_limit":{"tier":"anonymous","retry_after_seconds":42,"upgrade":"Email sam@yfin.dev for an API key."}}}}}}},"502":{"description":"yfin could not complete the upstream data request.","headers":{"x-yfin-error-code":{"description":"Stable yfin error code.","schema":{"type":"string"}},"x-yfin-error-message":{"description":"Short human-readable error message.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"origin_error":{"summary":"Upstream request failed","value":{"ok":false,"meta":{"provider":"yahoo","endpoint":"v7.quote","family":"quote","generated_at":"2026-05-04T19:10:01.075Z","route":"quote"},"error":{"code":"origin_error","message":"The service could not complete the request. Retry shortly."}}}}}}},"503":{"description":"The service is temporarily unavailable or busy.","headers":{"x-yfin-error-code":{"description":"Stable yfin error code.","schema":{"type":"string"}},"x-yfin-error-message":{"description":"Short human-readable error message.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer","minimum":1}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"service_busy":{"summary":"Service busy","value":{"ok":false,"error":{"code":"service_busy","message":"The service is temporarily busy. Retry shortly."}}},"origin_unavailable":{"summary":"Data service unavailable","value":{"ok":false,"meta":{"provider":"yahoo","endpoint":"v7.quote","family":"quote","generated_at":"2026-05-04T19:10:01.073Z","route":"quote"},"error":{"code":"origin_unavailable","message":"The service is temporarily unavailable. Retry shortly."}}}}}}}}}},"/v1/calendar":{"get":{"tags":["Calendar"],"operationId":"getCalendar","summary":"Calendar Events","description":"Returns market calendar event datasets such as earnings, dividends, splits, IPOs, and economic events.\n\nUse this for earnings calendars, dividend calendars, event timelines, and agents that need date-based market context.\n\nPass modules and date-window parameters to narrow the event set.","parameters":[{"name":"modules","in":"query","required":false,"schema":{"type":"string"},"description":"Calendar modules to request, for example earnings, dividends, splits, ipo, economicEvents, or price."},{"name":"startDate","in":"query","required":false,"schema":{"type":"string"},"description":"Start of the event window as epoch milliseconds."},{"name":"endDate","in":"query","required":false,"schema":{"type":"string"},"description":"End of the event window as epoch milliseconds."},{"name":"X-Yfin-Contact","in":"header","required":false,"schema":{"type":"string"},"description":"Stable contact identity for higher free request limits, for example an email address or service name."},{"name":"X-Yfin-Key","in":"header","required":false,"schema":{"type":"string"},"description":"API key for higher-volume access. Authorization: Bearer is also supported."}],"responses":{"200":{"description":"Calendar Events response.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request parameters.","headers":{"x-yfin-error-code":{"description":"Stable yfin error code.","schema":{"type":"string"}},"x-yfin-error-message":{"description":"Short human-readable error message.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"bad_request":{"summary":"Invalid request","value":{"ok":false,"error":{"code":"bad_request","message":"Invalid request parameters."}}}}}}},"404":{"description":"Unknown route or endpoint.","headers":{"x-yfin-error-code":{"description":"Stable yfin error code.","schema":{"type":"string"}},"x-yfin-error-message":{"description":"Short human-readable error message.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"not_found":{"summary":"Unknown route","value":{"ok":false,"error":{"code":"not_found","message":"Unknown yfin route."}}},"endpoint_not_found":{"summary":"Unknown endpoint ID","value":{"ok":false,"error":{"code":"endpoint_not_found","message":"Endpoint is not in the endpoint catalog."}}}}}}},"405":{"description":"HTTP method is not allowed for this endpoint.","headers":{"x-yfin-error-code":{"description":"Stable yfin error code.","schema":{"type":"string"}},"x-yfin-error-message":{"description":"Short human-readable error message.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"method_not_allowed":{"summary":"Method not allowed","value":{"ok":false,"error":{"code":"method_not_allowed","message":"POST is not allowed for this endpoint."},"allow":["GET"]}}}}}},"429":{"description":"Request limit exceeded. Retry-After is included.","headers":{"x-yfin-error-code":{"description":"Stable yfin error code.","schema":{"type":"string"}},"x-yfin-error-message":{"description":"Short human-readable error message.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer","minimum":1}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitResponse"},"examples":{"rate_limited":{"summary":"Request limit exceeded","value":{"ok":false,"error":{"code":"rate_limited","message":"Request limit exceeded."},"rate_limit":{"tier":"anonymous","retry_after_seconds":42,"upgrade":"Email sam@yfin.dev for an API key."}}}}}}},"502":{"description":"yfin could not complete the upstream data request.","headers":{"x-yfin-error-code":{"description":"Stable yfin error code.","schema":{"type":"string"}},"x-yfin-error-message":{"description":"Short human-readable error message.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"origin_error":{"summary":"Upstream request failed","value":{"ok":false,"meta":{"provider":"yahoo","endpoint":"v7.quote","family":"quote","generated_at":"2026-05-04T19:10:01.075Z","route":"quote"},"error":{"code":"origin_error","message":"The service could not complete the request. Retry shortly."}}}}}}},"503":{"description":"The service is temporarily unavailable or busy.","headers":{"x-yfin-error-code":{"description":"Stable yfin error code.","schema":{"type":"string"}},"x-yfin-error-message":{"description":"Short human-readable error message.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer","minimum":1}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"service_busy":{"summary":"Service busy","value":{"ok":false,"error":{"code":"service_busy","message":"The service is temporarily busy. Retry shortly."}}},"origin_unavailable":{"summary":"Data service unavailable","value":{"ok":false,"meta":{"provider":"yahoo","endpoint":"v7.quote","family":"quote","generated_at":"2026-05-04T19:10:01.073Z","route":"quote"},"error":{"code":"origin_unavailable","message":"The service is temporarily unavailable. Retry shortly."}}}}}}}}}},"/v1/fundamentals":{"get":{"tags":["Fundamentals"],"operationId":"getFundamentals","summary":"Fundamentals","description":"Returns company, ETF, or fund fundamentals from selected quote summary modules.\n\nUse this for company profiles, valuation screens, financial statement summaries, fund holdings, earnings context, and research agents.\n\nPass modules to choose the data families you need, such as price, summaryDetail, financialData, assetProfile, calendarEvents, incomeStatementHistory, balanceSheetHistory, cashflowStatementHistory, or fundProfile when supported.","parameters":[{"name":"symbol","in":"query","required":true,"schema":{"type":"string"},"description":"Single ticker symbol. Alias: ticker."},{"name":"modules","in":"query","required":false,"schema":{"type":"string"},"description":"Comma-separated quoteSummary modules."},{"name":"X-Yfin-Contact","in":"header","required":false,"schema":{"type":"string"},"description":"Stable contact identity for higher free request limits, for example an email address or service name."},{"name":"X-Yfin-Key","in":"header","required":false,"schema":{"type":"string"},"description":"API key for higher-volume access. Authorization: Bearer is also supported."}],"responses":{"200":{"description":"Fundamentals response.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request parameters.","headers":{"x-yfin-error-code":{"description":"Stable yfin error code.","schema":{"type":"string"}},"x-yfin-error-message":{"description":"Short human-readable error message.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"bad_request":{"summary":"Invalid request","value":{"ok":false,"error":{"code":"bad_request","message":"fundamentals requires symbol=, ticker=, or a /v1/ticker/{symbol}/fundamentals route."}}}}}}},"404":{"description":"Unknown route or endpoint.","headers":{"x-yfin-error-code":{"description":"Stable yfin error code.","schema":{"type":"string"}},"x-yfin-error-message":{"description":"Short human-readable error message.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"not_found":{"summary":"Unknown route","value":{"ok":false,"error":{"code":"not_found","message":"Unknown yfin route."}}},"endpoint_not_found":{"summary":"Unknown endpoint ID","value":{"ok":false,"error":{"code":"endpoint_not_found","message":"Endpoint is not in the endpoint catalog."}}}}}}},"405":{"description":"HTTP method is not allowed for this endpoint.","headers":{"x-yfin-error-code":{"description":"Stable yfin error code.","schema":{"type":"string"}},"x-yfin-error-message":{"description":"Short human-readable error message.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"method_not_allowed":{"summary":"Method not allowed","value":{"ok":false,"error":{"code":"method_not_allowed","message":"POST is not allowed for this endpoint."},"allow":["GET"]}}}}}},"429":{"description":"Request limit exceeded. Retry-After is included.","headers":{"x-yfin-error-code":{"description":"Stable yfin error code.","schema":{"type":"string"}},"x-yfin-error-message":{"description":"Short human-readable error message.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer","minimum":1}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitResponse"},"examples":{"rate_limited":{"summary":"Request limit exceeded","value":{"ok":false,"error":{"code":"rate_limited","message":"Request limit exceeded."},"rate_limit":{"tier":"anonymous","retry_after_seconds":42,"upgrade":"Email sam@yfin.dev for an API key."}}}}}}},"502":{"description":"yfin could not complete the upstream data request.","headers":{"x-yfin-error-code":{"description":"Stable yfin error code.","schema":{"type":"string"}},"x-yfin-error-message":{"description":"Short human-readable error message.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"origin_error":{"summary":"Upstream request failed","value":{"ok":false,"meta":{"provider":"yahoo","endpoint":"v7.quote","family":"quote","generated_at":"2026-05-04T19:10:01.075Z","route":"quote"},"error":{"code":"origin_error","message":"The service could not complete the request. Retry shortly."}}}}}}},"503":{"description":"The service is temporarily unavailable or busy.","headers":{"x-yfin-error-code":{"description":"Stable yfin error code.","schema":{"type":"string"}},"x-yfin-error-message":{"description":"Short human-readable error message.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer","minimum":1}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"service_busy":{"summary":"Service busy","value":{"ok":false,"error":{"code":"service_busy","message":"The service is temporarily busy. Retry shortly."}}},"origin_unavailable":{"summary":"Data service unavailable","value":{"ok":false,"meta":{"provider":"yahoo","endpoint":"v7.quote","family":"quote","generated_at":"2026-05-04T19:10:01.073Z","route":"quote"},"error":{"code":"origin_unavailable","message":"The service is temporarily unavailable. Retry shortly."}}}}}}}}}},"/v1/history":{"get":{"tags":["Prices"],"operationId":"getHistory","summary":"Historical Prices","description":"Returns historical chart data for one symbol, including timestamps, OHLC prices, volume, adjusted close, and optional corporate actions when available.\n\nUse this for price charts, return calculations, backtests, volatility features, technical indicators, and model inputs that need time-series price data.\n\nChoose a range and interval, or pass start and end dates for a custom window.","parameters":[{"name":"symbol","in":"query","required":true,"schema":{"type":"string"},"description":"Single ticker symbol. Alias: ticker."},{"name":"range","in":"query","required":false,"schema":{"type":"string"},"description":"Chart range, for example 1d, 5d, 1mo, 6mo, 1y, 5y, or max. Alias: period."},{"name":"period","in":"query","required":false,"schema":{"type":"string"},"description":"Alias for range, useful when migrating existing yfinance-shaped code."},{"name":"interval","in":"query","required":false,"schema":{"type":"string"},"description":"Candle interval, for example 1d, 1h, 15m, 5m, or 1m."},{"name":"start","in":"query","required":false,"schema":{"type":"string"},"description":"Start date as YYYY-MM-DD or epoch seconds."},{"name":"end","in":"query","required":false,"schema":{"type":"string"},"description":"End date as YYYY-MM-DD or epoch seconds."},{"name":"prepost","in":"query","required":false,"schema":{"type":"boolean"},"description":"Include pre-market and post-market data when available."},{"name":"actions","in":"query","required":false,"schema":{"type":"boolean"},"description":"When true, request dividends, splits, and capital gains events."},{"name":"X-Yfin-Contact","in":"header","required":false,"schema":{"type":"string"},"description":"Stable contact identity for higher free request limits, for example an email address or service name."},{"name":"X-Yfin-Key","in":"header","required":false,"schema":{"type":"string"},"description":"API key for higher-volume access. Authorization: Bearer is also supported."}],"responses":{"200":{"description":"Historical Prices response.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request parameters.","headers":{"x-yfin-error-code":{"description":"Stable yfin error code.","schema":{"type":"string"}},"x-yfin-error-message":{"description":"Short human-readable error message.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"bad_request":{"summary":"Invalid request","value":{"ok":false,"error":{"code":"bad_request","message":"history requires symbol=, ticker=, or a /v1/ticker/{symbol}/history route."}}}}}}},"404":{"description":"Unknown route or endpoint.","headers":{"x-yfin-error-code":{"description":"Stable yfin error code.","schema":{"type":"string"}},"x-yfin-error-message":{"description":"Short human-readable error message.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"not_found":{"summary":"Unknown route","value":{"ok":false,"error":{"code":"not_found","message":"Unknown yfin route."}}},"endpoint_not_found":{"summary":"Unknown endpoint ID","value":{"ok":false,"error":{"code":"endpoint_not_found","message":"Endpoint is not in the endpoint catalog."}}}}}}},"405":{"description":"HTTP method is not allowed for this endpoint.","headers":{"x-yfin-error-code":{"description":"Stable yfin error code.","schema":{"type":"string"}},"x-yfin-error-message":{"description":"Short human-readable error message.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"method_not_allowed":{"summary":"Method not allowed","value":{"ok":false,"error":{"code":"method_not_allowed","message":"POST is not allowed for this endpoint."},"allow":["GET"]}}}}}},"429":{"description":"Request limit exceeded. Retry-After is included.","headers":{"x-yfin-error-code":{"description":"Stable yfin error code.","schema":{"type":"string"}},"x-yfin-error-message":{"description":"Short human-readable error message.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer","minimum":1}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitResponse"},"examples":{"rate_limited":{"summary":"Request limit exceeded","value":{"ok":false,"error":{"code":"rate_limited","message":"Request limit exceeded."},"rate_limit":{"tier":"anonymous","retry_after_seconds":42,"upgrade":"Email sam@yfin.dev for an API key."}}}}}}},"502":{"description":"yfin could not complete the upstream data request.","headers":{"x-yfin-error-code":{"description":"Stable yfin error code.","schema":{"type":"string"}},"x-yfin-error-message":{"description":"Short human-readable error message.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"origin_error":{"summary":"Upstream request failed","value":{"ok":false,"meta":{"provider":"yahoo","endpoint":"v7.quote","family":"quote","generated_at":"2026-05-04T19:10:01.075Z","route":"quote"},"error":{"code":"origin_error","message":"The service could not complete the request. Retry shortly."}}}}}}},"503":{"description":"The service is temporarily unavailable or busy.","headers":{"x-yfin-error-code":{"description":"Stable yfin error code.","schema":{"type":"string"}},"x-yfin-error-message":{"description":"Short human-readable error message.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer","minimum":1}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"service_busy":{"summary":"Service busy","value":{"ok":false,"error":{"code":"service_busy","message":"The service is temporarily busy. Retry shortly."}}},"origin_unavailable":{"summary":"Data service unavailable","value":{"ok":false,"meta":{"provider":"yahoo","endpoint":"v7.quote","family":"quote","generated_at":"2026-05-04T19:10:01.073Z","route":"quote"},"error":{"code":"origin_unavailable","message":"The service is temporarily unavailable. Retry shortly."}}}}}}}}}},"/v1/industries":{"get":{"tags":["Discovery"],"operationId":"getIndustries","summary":"Industry Data","description":"Returns reference and market data for an industry slug.\n\nUse this to build industry pages, compare companies within an industry, and help agents move from a sector theme to a narrower peer group.","parameters":[{"name":"industry","in":"query","required":true,"schema":{"type":"string"},"description":"Industry slug. Alias: slug."},{"name":"X-Yfin-Contact","in":"header","required":false,"schema":{"type":"string"},"description":"Stable contact identity for higher free request limits, for example an email address or service name."},{"name":"X-Yfin-Key","in":"header","required":false,"schema":{"type":"string"},"description":"API key for higher-volume access. Authorization: Bearer is also supported."}],"responses":{"200":{"description":"Industry Data response.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request parameters.","headers":{"x-yfin-error-code":{"description":"Stable yfin error code.","schema":{"type":"string"}},"x-yfin-error-message":{"description":"Short human-readable error message.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"bad_request":{"summary":"Invalid request","value":{"ok":false,"error":{"code":"bad_request","message":"industries requires industry= or slug=."}}}}}}},"404":{"description":"Unknown route or endpoint.","headers":{"x-yfin-error-code":{"description":"Stable yfin error code.","schema":{"type":"string"}},"x-yfin-error-message":{"description":"Short human-readable error message.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"not_found":{"summary":"Unknown route","value":{"ok":false,"error":{"code":"not_found","message":"Unknown yfin route."}}},"endpoint_not_found":{"summary":"Unknown endpoint ID","value":{"ok":false,"error":{"code":"endpoint_not_found","message":"Endpoint is not in the endpoint catalog."}}}}}}},"405":{"description":"HTTP method is not allowed for this endpoint.","headers":{"x-yfin-error-code":{"description":"Stable yfin error code.","schema":{"type":"string"}},"x-yfin-error-message":{"description":"Short human-readable error message.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"method_not_allowed":{"summary":"Method not allowed","value":{"ok":false,"error":{"code":"method_not_allowed","message":"POST is not allowed for this endpoint."},"allow":["GET"]}}}}}},"429":{"description":"Request limit exceeded. Retry-After is included.","headers":{"x-yfin-error-code":{"description":"Stable yfin error code.","schema":{"type":"string"}},"x-yfin-error-message":{"description":"Short human-readable error message.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer","minimum":1}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitResponse"},"examples":{"rate_limited":{"summary":"Request limit exceeded","value":{"ok":false,"error":{"code":"rate_limited","message":"Request limit exceeded."},"rate_limit":{"tier":"anonymous","retry_after_seconds":42,"upgrade":"Email sam@yfin.dev for an API key."}}}}}}},"502":{"description":"yfin could not complete the upstream data request.","headers":{"x-yfin-error-code":{"description":"Stable yfin error code.","schema":{"type":"string"}},"x-yfin-error-message":{"description":"Short human-readable error message.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"origin_error":{"summary":"Upstream request failed","value":{"ok":false,"meta":{"provider":"yahoo","endpoint":"v7.quote","family":"quote","generated_at":"2026-05-04T19:10:01.075Z","route":"quote"},"error":{"code":"origin_error","message":"The service could not complete the request. Retry shortly."}}}}}}},"503":{"description":"The service is temporarily unavailable or busy.","headers":{"x-yfin-error-code":{"description":"Stable yfin error code.","schema":{"type":"string"}},"x-yfin-error-message":{"description":"Short human-readable error message.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer","minimum":1}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"service_busy":{"summary":"Service busy","value":{"ok":false,"error":{"code":"service_busy","message":"The service is temporarily busy. Retry shortly."}}},"origin_unavailable":{"summary":"Data service unavailable","value":{"ok":false,"meta":{"provider":"yahoo","endpoint":"v7.quote","family":"quote","generated_at":"2026-05-04T19:10:01.073Z","route":"quote"},"error":{"code":"origin_unavailable","message":"The service is temporarily unavailable. Retry shortly."}}}}}}}}}},"/v1/insights":{"get":{"tags":["Research"],"operationId":"getInsights","summary":"Symbol Insights","description":"Returns research-oriented insight data for one or more symbols.\n\nUse this when an app or agent needs richer context around a ticker, such as company snapshots, research signals, technical events, valuation context, or related market narrative when available.","parameters":[{"name":"symbols","in":"query","required":true,"schema":{"type":"string"},"description":"Comma-separated ticker symbols. Aliases: symbol, tickers, ticker."},{"name":"X-Yfin-Contact","in":"header","required":false,"schema":{"type":"string"},"description":"Stable contact identity for higher free request limits, for example an email address or service name."},{"name":"X-Yfin-Key","in":"header","required":false,"schema":{"type":"string"},"description":"API key for higher-volume access. Authorization: Bearer is also supported."}],"responses":{"200":{"description":"Symbol Insights response.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request parameters.","headers":{"x-yfin-error-code":{"description":"Stable yfin error code.","schema":{"type":"string"}},"x-yfin-error-message":{"description":"Short human-readable error message.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"bad_request":{"summary":"Invalid request","value":{"ok":false,"error":{"code":"bad_request","message":"insights requires symbols=, symbol=, tickers=, ticker=, or a /v1/ticker/{symbol}/... route."}}}}}}},"404":{"description":"Unknown route or endpoint.","headers":{"x-yfin-error-code":{"description":"Stable yfin error code.","schema":{"type":"string"}},"x-yfin-error-message":{"description":"Short human-readable error message.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"not_found":{"summary":"Unknown route","value":{"ok":false,"error":{"code":"not_found","message":"Unknown yfin route."}}},"endpoint_not_found":{"summary":"Unknown endpoint ID","value":{"ok":false,"error":{"code":"endpoint_not_found","message":"Endpoint is not in the endpoint catalog."}}}}}}},"405":{"description":"HTTP method is not allowed for this endpoint.","headers":{"x-yfin-error-code":{"description":"Stable yfin error code.","schema":{"type":"string"}},"x-yfin-error-message":{"description":"Short human-readable error message.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"method_not_allowed":{"summary":"Method not allowed","value":{"ok":false,"error":{"code":"method_not_allowed","message":"POST is not allowed for this endpoint."},"allow":["GET"]}}}}}},"429":{"description":"Request limit exceeded. Retry-After is included.","headers":{"x-yfin-error-code":{"description":"Stable yfin error code.","schema":{"type":"string"}},"x-yfin-error-message":{"description":"Short human-readable error message.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer","minimum":1}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitResponse"},"examples":{"rate_limited":{"summary":"Request limit exceeded","value":{"ok":false,"error":{"code":"rate_limited","message":"Request limit exceeded."},"rate_limit":{"tier":"anonymous","retry_after_seconds":42,"upgrade":"Email sam@yfin.dev for an API key."}}}}}}},"502":{"description":"yfin could not complete the upstream data request.","headers":{"x-yfin-error-code":{"description":"Stable yfin error code.","schema":{"type":"string"}},"x-yfin-error-message":{"description":"Short human-readable error message.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"origin_error":{"summary":"Upstream request failed","value":{"ok":false,"meta":{"provider":"yahoo","endpoint":"v7.quote","family":"quote","generated_at":"2026-05-04T19:10:01.075Z","route":"quote"},"error":{"code":"origin_error","message":"The service could not complete the request. Retry shortly."}}}}}}},"503":{"description":"The service is temporarily unavailable or busy.","headers":{"x-yfin-error-code":{"description":"Stable yfin error code.","schema":{"type":"string"}},"x-yfin-error-message":{"description":"Short human-readable error message.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer","minimum":1}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"service_busy":{"summary":"Service busy","value":{"ok":false,"error":{"code":"service_busy","message":"The service is temporarily busy. Retry shortly."}}},"origin_unavailable":{"summary":"Data service unavailable","value":{"ok":false,"meta":{"provider":"yahoo","endpoint":"v7.quote","family":"quote","generated_at":"2026-05-04T19:10:01.073Z","route":"quote"},"error":{"code":"origin_unavailable","message":"The service is temporarily unavailable. Retry shortly."}}}}}}}}}},"/v1/lookup":{"get":{"tags":["Search"],"operationId":"getLookup","summary":"Symbol Lookup","description":"Returns symbol lookup results for a company name, fund name, index name, or ticker-like query.\n\nUse this when a user or agent has natural-language text and needs a structured list of candidate instruments with symbol, exchange, and quote type metadata.","parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string"},"description":"Search query. Alias: query."},{"name":"X-Yfin-Contact","in":"header","required":false,"schema":{"type":"string"},"description":"Stable contact identity for higher free request limits, for example an email address or service name."},{"name":"X-Yfin-Key","in":"header","required":false,"schema":{"type":"string"},"description":"API key for higher-volume access. Authorization: Bearer is also supported."}],"responses":{"200":{"description":"Symbol Lookup response.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request parameters.","headers":{"x-yfin-error-code":{"description":"Stable yfin error code.","schema":{"type":"string"}},"x-yfin-error-message":{"description":"Short human-readable error message.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"bad_request":{"summary":"Invalid request","value":{"ok":false,"error":{"code":"bad_request","message":"lookup requires q= or query=."}}}}}}},"404":{"description":"Unknown route or endpoint.","headers":{"x-yfin-error-code":{"description":"Stable yfin error code.","schema":{"type":"string"}},"x-yfin-error-message":{"description":"Short human-readable error message.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"not_found":{"summary":"Unknown route","value":{"ok":false,"error":{"code":"not_found","message":"Unknown yfin route."}}},"endpoint_not_found":{"summary":"Unknown endpoint ID","value":{"ok":false,"error":{"code":"endpoint_not_found","message":"Endpoint is not in the endpoint catalog."}}}}}}},"405":{"description":"HTTP method is not allowed for this endpoint.","headers":{"x-yfin-error-code":{"description":"Stable yfin error code.","schema":{"type":"string"}},"x-yfin-error-message":{"description":"Short human-readable error message.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"method_not_allowed":{"summary":"Method not allowed","value":{"ok":false,"error":{"code":"method_not_allowed","message":"POST is not allowed for this endpoint."},"allow":["GET"]}}}}}},"429":{"description":"Request limit exceeded. Retry-After is included.","headers":{"x-yfin-error-code":{"description":"Stable yfin error code.","schema":{"type":"string"}},"x-yfin-error-message":{"description":"Short human-readable error message.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer","minimum":1}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitResponse"},"examples":{"rate_limited":{"summary":"Request limit exceeded","value":{"ok":false,"error":{"code":"rate_limited","message":"Request limit exceeded."},"rate_limit":{"tier":"anonymous","retry_after_seconds":42,"upgrade":"Email sam@yfin.dev for an API key."}}}}}}},"502":{"description":"yfin could not complete the upstream data request.","headers":{"x-yfin-error-code":{"description":"Stable yfin error code.","schema":{"type":"string"}},"x-yfin-error-message":{"description":"Short human-readable error message.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"origin_error":{"summary":"Upstream request failed","value":{"ok":false,"meta":{"provider":"yahoo","endpoint":"v7.quote","family":"quote","generated_at":"2026-05-04T19:10:01.075Z","route":"quote"},"error":{"code":"origin_error","message":"The service could not complete the request. Retry shortly."}}}}}}},"503":{"description":"The service is temporarily unavailable or busy.","headers":{"x-yfin-error-code":{"description":"Stable yfin error code.","schema":{"type":"string"}},"x-yfin-error-message":{"description":"Short human-readable error message.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer","minimum":1}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"service_busy":{"summary":"Service busy","value":{"ok":false,"error":{"code":"service_busy","message":"The service is temporarily busy. Retry shortly."}}},"origin_unavailable":{"summary":"Data service unavailable","value":{"ok":false,"meta":{"provider":"yahoo","endpoint":"v7.quote","family":"quote","generated_at":"2026-05-04T19:10:01.073Z","route":"quote"},"error":{"code":"origin_unavailable","message":"The service is temporarily unavailable. Retry shortly."}}}}}}}}}},"/v1/market_summary":{"get":{"tags":["Market Data"],"operationId":"getMarketSummary","summary":"Market Summary","description":"Returns broad market snapshot data such as major indexes, futures, currencies, and other regional market movers when available.\n\nUse this for market overview pages, opening dashboards, daily summaries, and agents that need current market context before drilling into individual symbols.","parameters":[{"name":"region","in":"query","required":false,"schema":{"type":"string"},"description":"Region code, for example US."},{"name":"lang","in":"query","required":false,"schema":{"type":"string"},"description":"Locale language, for example en-US."},{"name":"X-Yfin-Contact","in":"header","required":false,"schema":{"type":"string"},"description":"Stable contact identity for higher free request limits, for example an email address or service name."},{"name":"X-Yfin-Key","in":"header","required":false,"schema":{"type":"string"},"description":"API key for higher-volume access. Authorization: Bearer is also supported."}],"responses":{"200":{"description":"Market Summary response.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request parameters.","headers":{"x-yfin-error-code":{"description":"Stable yfin error code.","schema":{"type":"string"}},"x-yfin-error-message":{"description":"Short human-readable error message.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"bad_request":{"summary":"Invalid request","value":{"ok":false,"error":{"code":"bad_request","message":"Invalid request parameters."}}}}}}},"404":{"description":"Unknown route or endpoint.","headers":{"x-yfin-error-code":{"description":"Stable yfin error code.","schema":{"type":"string"}},"x-yfin-error-message":{"description":"Short human-readable error message.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"not_found":{"summary":"Unknown route","value":{"ok":false,"error":{"code":"not_found","message":"Unknown yfin route."}}},"endpoint_not_found":{"summary":"Unknown endpoint ID","value":{"ok":false,"error":{"code":"endpoint_not_found","message":"Endpoint is not in the endpoint catalog."}}}}}}},"405":{"description":"HTTP method is not allowed for this endpoint.","headers":{"x-yfin-error-code":{"description":"Stable yfin error code.","schema":{"type":"string"}},"x-yfin-error-message":{"description":"Short human-readable error message.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"method_not_allowed":{"summary":"Method not allowed","value":{"ok":false,"error":{"code":"method_not_allowed","message":"POST is not allowed for this endpoint."},"allow":["GET"]}}}}}},"429":{"description":"Request limit exceeded. Retry-After is included.","headers":{"x-yfin-error-code":{"description":"Stable yfin error code.","schema":{"type":"string"}},"x-yfin-error-message":{"description":"Short human-readable error message.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer","minimum":1}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitResponse"},"examples":{"rate_limited":{"summary":"Request limit exceeded","value":{"ok":false,"error":{"code":"rate_limited","message":"Request limit exceeded."},"rate_limit":{"tier":"anonymous","retry_after_seconds":42,"upgrade":"Email sam@yfin.dev for an API key."}}}}}}},"502":{"description":"yfin could not complete the upstream data request.","headers":{"x-yfin-error-code":{"description":"Stable yfin error code.","schema":{"type":"string"}},"x-yfin-error-message":{"description":"Short human-readable error message.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"origin_error":{"summary":"Upstream request failed","value":{"ok":false,"meta":{"provider":"yahoo","endpoint":"v7.quote","family":"quote","generated_at":"2026-05-04T19:10:01.075Z","route":"quote"},"error":{"code":"origin_error","message":"The service could not complete the request. Retry shortly."}}}}}}},"503":{"description":"The service is temporarily unavailable or busy.","headers":{"x-yfin-error-code":{"description":"Stable yfin error code.","schema":{"type":"string"}},"x-yfin-error-message":{"description":"Short human-readable error message.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer","minimum":1}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"service_busy":{"summary":"Service busy","value":{"ok":false,"error":{"code":"service_busy","message":"The service is temporarily busy. Retry shortly."}}},"origin_unavailable":{"summary":"Data service unavailable","value":{"ok":false,"meta":{"provider":"yahoo","endpoint":"v7.quote","family":"quote","generated_at":"2026-05-04T19:10:01.073Z","route":"quote"},"error":{"code":"origin_unavailable","message":"The service is temporarily unavailable. Retry shortly."}}}}}}}}}},"/v1/market_time":{"get":{"tags":["Market Data"],"operationId":"getMarketTime","summary":"Market Time","description":"Returns market clock and trading-session metadata.\n\nUse this to determine whether a market is open, closed, pre-market, or post-market, and to align dashboards or agents with the relevant exchange timezone.","parameters":[{"name":"region","in":"query","required":false,"schema":{"type":"string"},"description":"Region code, for example US."},{"name":"lang","in":"query","required":false,"schema":{"type":"string"},"description":"Locale language, for example en-US."},{"name":"X-Yfin-Contact","in":"header","required":false,"schema":{"type":"string"},"description":"Stable contact identity for higher free request limits, for example an email address or service name."},{"name":"X-Yfin-Key","in":"header","required":false,"schema":{"type":"string"},"description":"API key for higher-volume access. Authorization: Bearer is also supported."}],"responses":{"200":{"description":"Market Time response.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request parameters.","headers":{"x-yfin-error-code":{"description":"Stable yfin error code.","schema":{"type":"string"}},"x-yfin-error-message":{"description":"Short human-readable error message.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"bad_request":{"summary":"Invalid request","value":{"ok":false,"error":{"code":"bad_request","message":"Invalid request parameters."}}}}}}},"404":{"description":"Unknown route or endpoint.","headers":{"x-yfin-error-code":{"description":"Stable yfin error code.","schema":{"type":"string"}},"x-yfin-error-message":{"description":"Short human-readable error message.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"not_found":{"summary":"Unknown route","value":{"ok":false,"error":{"code":"not_found","message":"Unknown yfin route."}}},"endpoint_not_found":{"summary":"Unknown endpoint ID","value":{"ok":false,"error":{"code":"endpoint_not_found","message":"Endpoint is not in the endpoint catalog."}}}}}}},"405":{"description":"HTTP method is not allowed for this endpoint.","headers":{"x-yfin-error-code":{"description":"Stable yfin error code.","schema":{"type":"string"}},"x-yfin-error-message":{"description":"Short human-readable error message.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"method_not_allowed":{"summary":"Method not allowed","value":{"ok":false,"error":{"code":"method_not_allowed","message":"POST is not allowed for this endpoint."},"allow":["GET"]}}}}}},"429":{"description":"Request limit exceeded. Retry-After is included.","headers":{"x-yfin-error-code":{"description":"Stable yfin error code.","schema":{"type":"string"}},"x-yfin-error-message":{"description":"Short human-readable error message.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer","minimum":1}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitResponse"},"examples":{"rate_limited":{"summary":"Request limit exceeded","value":{"ok":false,"error":{"code":"rate_limited","message":"Request limit exceeded."},"rate_limit":{"tier":"anonymous","retry_after_seconds":42,"upgrade":"Email sam@yfin.dev for an API key."}}}}}}},"502":{"description":"yfin could not complete the upstream data request.","headers":{"x-yfin-error-code":{"description":"Stable yfin error code.","schema":{"type":"string"}},"x-yfin-error-message":{"description":"Short human-readable error message.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"origin_error":{"summary":"Upstream request failed","value":{"ok":false,"meta":{"provider":"yahoo","endpoint":"v7.quote","family":"quote","generated_at":"2026-05-04T19:10:01.075Z","route":"quote"},"error":{"code":"origin_error","message":"The service could not complete the request. Retry shortly."}}}}}}},"503":{"description":"The service is temporarily unavailable or busy.","headers":{"x-yfin-error-code":{"description":"Stable yfin error code.","schema":{"type":"string"}},"x-yfin-error-message":{"description":"Short human-readable error message.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer","minimum":1}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"service_busy":{"summary":"Service busy","value":{"ok":false,"error":{"code":"service_busy","message":"The service is temporarily busy. Retry shortly."}}},"origin_unavailable":{"summary":"Data service unavailable","value":{"ok":false,"meta":{"provider":"yahoo","endpoint":"v7.quote","family":"quote","generated_at":"2026-05-04T19:10:01.073Z","route":"quote"},"error":{"code":"origin_unavailable","message":"The service is temporarily unavailable. Retry shortly."}}}}}}}}}},"/v1/options":{"get":{"tags":["Options"],"operationId":"getOptions","summary":"Options Chains","description":"Returns option expiration dates and call/put chains for one symbol.\n\nUse this for option-chain tables, expiration pickers, strike selection, implied volatility analysis, open-interest views, and derivatives research agents.\n\nPass date to request a specific expiration.","parameters":[{"name":"symbol","in":"query","required":true,"schema":{"type":"string"},"description":"Single ticker symbol. Alias: ticker."},{"name":"date","in":"query","required":false,"schema":{"type":"string"},"description":"Option expiration date as YYYY-MM-DD or epoch seconds."},{"name":"X-Yfin-Contact","in":"header","required":false,"schema":{"type":"string"},"description":"Stable contact identity for higher free request limits, for example an email address or service name."},{"name":"X-Yfin-Key","in":"header","required":false,"schema":{"type":"string"},"description":"API key for higher-volume access. Authorization: Bearer is also supported."}],"responses":{"200":{"description":"Options Chains response.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request parameters.","headers":{"x-yfin-error-code":{"description":"Stable yfin error code.","schema":{"type":"string"}},"x-yfin-error-message":{"description":"Short human-readable error message.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"bad_request":{"summary":"Invalid request","value":{"ok":false,"error":{"code":"bad_request","message":"options requires symbol=, ticker=, or a /v1/ticker/{symbol}/options route."}}}}}}},"404":{"description":"Unknown route or endpoint.","headers":{"x-yfin-error-code":{"description":"Stable yfin error code.","schema":{"type":"string"}},"x-yfin-error-message":{"description":"Short human-readable error message.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"not_found":{"summary":"Unknown route","value":{"ok":false,"error":{"code":"not_found","message":"Unknown yfin route."}}},"endpoint_not_found":{"summary":"Unknown endpoint ID","value":{"ok":false,"error":{"code":"endpoint_not_found","message":"Endpoint is not in the endpoint catalog."}}}}}}},"405":{"description":"HTTP method is not allowed for this endpoint.","headers":{"x-yfin-error-code":{"description":"Stable yfin error code.","schema":{"type":"string"}},"x-yfin-error-message":{"description":"Short human-readable error message.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"method_not_allowed":{"summary":"Method not allowed","value":{"ok":false,"error":{"code":"method_not_allowed","message":"POST is not allowed for this endpoint."},"allow":["GET"]}}}}}},"429":{"description":"Request limit exceeded. Retry-After is included.","headers":{"x-yfin-error-code":{"description":"Stable yfin error code.","schema":{"type":"string"}},"x-yfin-error-message":{"description":"Short human-readable error message.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer","minimum":1}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitResponse"},"examples":{"rate_limited":{"summary":"Request limit exceeded","value":{"ok":false,"error":{"code":"rate_limited","message":"Request limit exceeded."},"rate_limit":{"tier":"anonymous","retry_after_seconds":42,"upgrade":"Email sam@yfin.dev for an API key."}}}}}}},"502":{"description":"yfin could not complete the upstream data request.","headers":{"x-yfin-error-code":{"description":"Stable yfin error code.","schema":{"type":"string"}},"x-yfin-error-message":{"description":"Short human-readable error message.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"origin_error":{"summary":"Upstream request failed","value":{"ok":false,"meta":{"provider":"yahoo","endpoint":"v7.quote","family":"quote","generated_at":"2026-05-04T19:10:01.075Z","route":"quote"},"error":{"code":"origin_error","message":"The service could not complete the request. Retry shortly."}}}}}}},"503":{"description":"The service is temporarily unavailable or busy.","headers":{"x-yfin-error-code":{"description":"Stable yfin error code.","schema":{"type":"string"}},"x-yfin-error-message":{"description":"Short human-readable error message.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer","minimum":1}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"service_busy":{"summary":"Service busy","value":{"ok":false,"error":{"code":"service_busy","message":"The service is temporarily busy. Retry shortly."}}},"origin_unavailable":{"summary":"Data service unavailable","value":{"ok":false,"meta":{"provider":"yahoo","endpoint":"v7.quote","family":"quote","generated_at":"2026-05-04T19:10:01.073Z","route":"quote"},"error":{"code":"origin_unavailable","message":"The service is temporarily unavailable. Retry shortly."}}}}}}}}}},"/v1/price_insights":{"get":{"tags":["Research"],"operationId":"getPriceInsights","summary":"Price Insights","description":"Returns price-focused insight data for one or more symbols.\n\nUse this for valuation context, price movement summaries, support/resistance-style research, and agents that need a higher-level read on recent price behavior when available.","parameters":[{"name":"symbols","in":"query","required":true,"schema":{"type":"string"},"description":"Comma-separated ticker symbols. Aliases: symbol, tickers, ticker."},{"name":"X-Yfin-Contact","in":"header","required":false,"schema":{"type":"string"},"description":"Stable contact identity for higher free request limits, for example an email address or service name."},{"name":"X-Yfin-Key","in":"header","required":false,"schema":{"type":"string"},"description":"API key for higher-volume access. Authorization: Bearer is also supported."}],"responses":{"200":{"description":"Price Insights response.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request parameters.","headers":{"x-yfin-error-code":{"description":"Stable yfin error code.","schema":{"type":"string"}},"x-yfin-error-message":{"description":"Short human-readable error message.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"bad_request":{"summary":"Invalid request","value":{"ok":false,"error":{"code":"bad_request","message":"price_insights requires symbols=, symbol=, tickers=, ticker=, or a /v1/ticker/{symbol}/... route."}}}}}}},"404":{"description":"Unknown route or endpoint.","headers":{"x-yfin-error-code":{"description":"Stable yfin error code.","schema":{"type":"string"}},"x-yfin-error-message":{"description":"Short human-readable error message.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"not_found":{"summary":"Unknown route","value":{"ok":false,"error":{"code":"not_found","message":"Unknown yfin route."}}},"endpoint_not_found":{"summary":"Unknown endpoint ID","value":{"ok":false,"error":{"code":"endpoint_not_found","message":"Endpoint is not in the endpoint catalog."}}}}}}},"405":{"description":"HTTP method is not allowed for this endpoint.","headers":{"x-yfin-error-code":{"description":"Stable yfin error code.","schema":{"type":"string"}},"x-yfin-error-message":{"description":"Short human-readable error message.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"method_not_allowed":{"summary":"Method not allowed","value":{"ok":false,"error":{"code":"method_not_allowed","message":"POST is not allowed for this endpoint."},"allow":["GET"]}}}}}},"429":{"description":"Request limit exceeded. Retry-After is included.","headers":{"x-yfin-error-code":{"description":"Stable yfin error code.","schema":{"type":"string"}},"x-yfin-error-message":{"description":"Short human-readable error message.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer","minimum":1}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitResponse"},"examples":{"rate_limited":{"summary":"Request limit exceeded","value":{"ok":false,"error":{"code":"rate_limited","message":"Request limit exceeded."},"rate_limit":{"tier":"anonymous","retry_after_seconds":42,"upgrade":"Email sam@yfin.dev for an API key."}}}}}}},"502":{"description":"yfin could not complete the upstream data request.","headers":{"x-yfin-error-code":{"description":"Stable yfin error code.","schema":{"type":"string"}},"x-yfin-error-message":{"description":"Short human-readable error message.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"origin_error":{"summary":"Upstream request failed","value":{"ok":false,"meta":{"provider":"yahoo","endpoint":"v7.quote","family":"quote","generated_at":"2026-05-04T19:10:01.075Z","route":"quote"},"error":{"code":"origin_error","message":"The service could not complete the request. Retry shortly."}}}}}}},"503":{"description":"The service is temporarily unavailable or busy.","headers":{"x-yfin-error-code":{"description":"Stable yfin error code.","schema":{"type":"string"}},"x-yfin-error-message":{"description":"Short human-readable error message.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer","minimum":1}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"service_busy":{"summary":"Service busy","value":{"ok":false,"error":{"code":"service_busy","message":"The service is temporarily busy. Retry shortly."}}},"origin_unavailable":{"summary":"Data service unavailable","value":{"ok":false,"meta":{"provider":"yahoo","endpoint":"v7.quote","family":"quote","generated_at":"2026-05-04T19:10:01.073Z","route":"quote"},"error":{"code":"origin_unavailable","message":"The service is temporarily unavailable. Retry shortly."}}}}}}}}}},"/v1/quote":{"get":{"tags":["Market Data"],"operationId":"getQuote","summary":"Quotes","description":"Returns current quote data for one or more symbols.\n\nUse this for watchlists, symbol snapshots, portfolio views, market dashboards, and agents that need latest price, change, currency, exchange, market state, quote type, and related quote fields when available.","parameters":[{"name":"symbols","in":"query","required":true,"schema":{"type":"string"},"description":"Comma-separated ticker symbols. Aliases: symbol, tickers, ticker."},{"name":"X-Yfin-Contact","in":"header","required":false,"schema":{"type":"string"},"description":"Stable contact identity for higher free request limits, for example an email address or service name."},{"name":"X-Yfin-Key","in":"header","required":false,"schema":{"type":"string"},"description":"API key for higher-volume access. Authorization: Bearer is also supported."}],"responses":{"200":{"description":"Quotes response.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request parameters.","headers":{"x-yfin-error-code":{"description":"Stable yfin error code.","schema":{"type":"string"}},"x-yfin-error-message":{"description":"Short human-readable error message.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"bad_request":{"summary":"Invalid request","value":{"ok":false,"error":{"code":"bad_request","message":"quote requires symbols=, symbol=, tickers=, ticker=, or a /v1/ticker/{symbol}/... route."}}}}}}},"404":{"description":"Unknown route or endpoint.","headers":{"x-yfin-error-code":{"description":"Stable yfin error code.","schema":{"type":"string"}},"x-yfin-error-message":{"description":"Short human-readable error message.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"not_found":{"summary":"Unknown route","value":{"ok":false,"error":{"code":"not_found","message":"Unknown yfin route."}}},"endpoint_not_found":{"summary":"Unknown endpoint ID","value":{"ok":false,"error":{"code":"endpoint_not_found","message":"Endpoint is not in the endpoint catalog."}}}}}}},"405":{"description":"HTTP method is not allowed for this endpoint.","headers":{"x-yfin-error-code":{"description":"Stable yfin error code.","schema":{"type":"string"}},"x-yfin-error-message":{"description":"Short human-readable error message.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"method_not_allowed":{"summary":"Method not allowed","value":{"ok":false,"error":{"code":"method_not_allowed","message":"POST is not allowed for this endpoint."},"allow":["GET"]}}}}}},"429":{"description":"Request limit exceeded. Retry-After is included.","headers":{"x-yfin-error-code":{"description":"Stable yfin error code.","schema":{"type":"string"}},"x-yfin-error-message":{"description":"Short human-readable error message.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer","minimum":1}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitResponse"},"examples":{"rate_limited":{"summary":"Request limit exceeded","value":{"ok":false,"error":{"code":"rate_limited","message":"Request limit exceeded."},"rate_limit":{"tier":"anonymous","retry_after_seconds":42,"upgrade":"Email sam@yfin.dev for an API key."}}}}}}},"502":{"description":"yfin could not complete the upstream data request.","headers":{"x-yfin-error-code":{"description":"Stable yfin error code.","schema":{"type":"string"}},"x-yfin-error-message":{"description":"Short human-readable error message.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"origin_error":{"summary":"Upstream request failed","value":{"ok":false,"meta":{"provider":"yahoo","endpoint":"v7.quote","family":"quote","generated_at":"2026-05-04T19:10:01.075Z","route":"quote"},"error":{"code":"origin_error","message":"The service could not complete the request. Retry shortly."}}}}}}},"503":{"description":"The service is temporarily unavailable or busy.","headers":{"x-yfin-error-code":{"description":"Stable yfin error code.","schema":{"type":"string"}},"x-yfin-error-message":{"description":"Short human-readable error message.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer","minimum":1}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"service_busy":{"summary":"Service busy","value":{"ok":false,"error":{"code":"service_busy","message":"The service is temporarily busy. Retry shortly."}}},"origin_unavailable":{"summary":"Data service unavailable","value":{"ok":false,"meta":{"provider":"yahoo","endpoint":"v7.quote","family":"quote","generated_at":"2026-05-04T19:10:01.073Z","route":"quote"},"error":{"code":"origin_unavailable","message":"The service is temporarily unavailable. Retry shortly."}}}}}}}}}},"/v1/quote_type":{"get":{"tags":["Market Data"],"operationId":"getQuoteType","summary":"Quote Type","description":"Returns instrument classification and exchange metadata for one symbol.\n\nUse this to distinguish equities, ETFs, mutual funds, indexes, currencies, crypto pairs, and other quote types before choosing which downstream endpoint to call.","parameters":[{"name":"symbol","in":"query","required":true,"schema":{"type":"string"},"description":"Single ticker symbol. Alias: ticker."},{"name":"X-Yfin-Contact","in":"header","required":false,"schema":{"type":"string"},"description":"Stable contact identity for higher free request limits, for example an email address or service name."},{"name":"X-Yfin-Key","in":"header","required":false,"schema":{"type":"string"},"description":"API key for higher-volume access. Authorization: Bearer is also supported."}],"responses":{"200":{"description":"Quote Type response.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request parameters.","headers":{"x-yfin-error-code":{"description":"Stable yfin error code.","schema":{"type":"string"}},"x-yfin-error-message":{"description":"Short human-readable error message.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"bad_request":{"summary":"Invalid request","value":{"ok":false,"error":{"code":"bad_request","message":"quote_type requires symbol=, ticker=, or a /v1/ticker/{symbol}/quote_type route."}}}}}}},"404":{"description":"Unknown route or endpoint.","headers":{"x-yfin-error-code":{"description":"Stable yfin error code.","schema":{"type":"string"}},"x-yfin-error-message":{"description":"Short human-readable error message.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"not_found":{"summary":"Unknown route","value":{"ok":false,"error":{"code":"not_found","message":"Unknown yfin route."}}},"endpoint_not_found":{"summary":"Unknown endpoint ID","value":{"ok":false,"error":{"code":"endpoint_not_found","message":"Endpoint is not in the endpoint catalog."}}}}}}},"405":{"description":"HTTP method is not allowed for this endpoint.","headers":{"x-yfin-error-code":{"description":"Stable yfin error code.","schema":{"type":"string"}},"x-yfin-error-message":{"description":"Short human-readable error message.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"method_not_allowed":{"summary":"Method not allowed","value":{"ok":false,"error":{"code":"method_not_allowed","message":"POST is not allowed for this endpoint."},"allow":["GET"]}}}}}},"429":{"description":"Request limit exceeded. Retry-After is included.","headers":{"x-yfin-error-code":{"description":"Stable yfin error code.","schema":{"type":"string"}},"x-yfin-error-message":{"description":"Short human-readable error message.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer","minimum":1}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitResponse"},"examples":{"rate_limited":{"summary":"Request limit exceeded","value":{"ok":false,"error":{"code":"rate_limited","message":"Request limit exceeded."},"rate_limit":{"tier":"anonymous","retry_after_seconds":42,"upgrade":"Email sam@yfin.dev for an API key."}}}}}}},"502":{"description":"yfin could not complete the upstream data request.","headers":{"x-yfin-error-code":{"description":"Stable yfin error code.","schema":{"type":"string"}},"x-yfin-error-message":{"description":"Short human-readable error message.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"origin_error":{"summary":"Upstream request failed","value":{"ok":false,"meta":{"provider":"yahoo","endpoint":"v7.quote","family":"quote","generated_at":"2026-05-04T19:10:01.075Z","route":"quote"},"error":{"code":"origin_error","message":"The service could not complete the request. Retry shortly."}}}}}}},"503":{"description":"The service is temporarily unavailable or busy.","headers":{"x-yfin-error-code":{"description":"Stable yfin error code.","schema":{"type":"string"}},"x-yfin-error-message":{"description":"Short human-readable error message.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer","minimum":1}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"service_busy":{"summary":"Service busy","value":{"ok":false,"error":{"code":"service_busy","message":"The service is temporarily busy. Retry shortly."}}},"origin_unavailable":{"summary":"Data service unavailable","value":{"ok":false,"meta":{"provider":"yahoo","endpoint":"v7.quote","family":"quote","generated_at":"2026-05-04T19:10:01.073Z","route":"quote"},"error":{"code":"origin_unavailable","message":"The service is temporarily unavailable. Retry shortly."}}}}}}}}}},"/v1/ratings":{"get":{"tags":["Research"],"operationId":"getRatings","summary":"Analyst Ratings","description":"Returns analyst-rating-oriented data for one symbol when available.\n\nUse this for research pages, ticker summaries, and agents that need rating context as one input among broader fundamentals and market data.","parameters":[{"name":"symbol","in":"query","required":true,"schema":{"type":"string"},"description":"Single ticker symbol. Alias: ticker."},{"name":"X-Yfin-Contact","in":"header","required":false,"schema":{"type":"string"},"description":"Stable contact identity for higher free request limits, for example an email address or service name."},{"name":"X-Yfin-Key","in":"header","required":false,"schema":{"type":"string"},"description":"API key for higher-volume access. Authorization: Bearer is also supported."}],"responses":{"200":{"description":"Analyst Ratings response.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request parameters.","headers":{"x-yfin-error-code":{"description":"Stable yfin error code.","schema":{"type":"string"}},"x-yfin-error-message":{"description":"Short human-readable error message.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"bad_request":{"summary":"Invalid request","value":{"ok":false,"error":{"code":"bad_request","message":"ratings requires symbol=, ticker=, or a /v1/ticker/{symbol}/ratings route."}}}}}}},"404":{"description":"Unknown route or endpoint.","headers":{"x-yfin-error-code":{"description":"Stable yfin error code.","schema":{"type":"string"}},"x-yfin-error-message":{"description":"Short human-readable error message.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"not_found":{"summary":"Unknown route","value":{"ok":false,"error":{"code":"not_found","message":"Unknown yfin route."}}},"endpoint_not_found":{"summary":"Unknown endpoint ID","value":{"ok":false,"error":{"code":"endpoint_not_found","message":"Endpoint is not in the endpoint catalog."}}}}}}},"405":{"description":"HTTP method is not allowed for this endpoint.","headers":{"x-yfin-error-code":{"description":"Stable yfin error code.","schema":{"type":"string"}},"x-yfin-error-message":{"description":"Short human-readable error message.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"method_not_allowed":{"summary":"Method not allowed","value":{"ok":false,"error":{"code":"method_not_allowed","message":"POST is not allowed for this endpoint."},"allow":["GET"]}}}}}},"429":{"description":"Request limit exceeded. Retry-After is included.","headers":{"x-yfin-error-code":{"description":"Stable yfin error code.","schema":{"type":"string"}},"x-yfin-error-message":{"description":"Short human-readable error message.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer","minimum":1}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitResponse"},"examples":{"rate_limited":{"summary":"Request limit exceeded","value":{"ok":false,"error":{"code":"rate_limited","message":"Request limit exceeded."},"rate_limit":{"tier":"anonymous","retry_after_seconds":42,"upgrade":"Email sam@yfin.dev for an API key."}}}}}}},"502":{"description":"yfin could not complete the upstream data request.","headers":{"x-yfin-error-code":{"description":"Stable yfin error code.","schema":{"type":"string"}},"x-yfin-error-message":{"description":"Short human-readable error message.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"origin_error":{"summary":"Upstream request failed","value":{"ok":false,"meta":{"provider":"yahoo","endpoint":"v7.quote","family":"quote","generated_at":"2026-05-04T19:10:01.075Z","route":"quote"},"error":{"code":"origin_error","message":"The service could not complete the request. Retry shortly."}}}}}}},"503":{"description":"The service is temporarily unavailable or busy.","headers":{"x-yfin-error-code":{"description":"Stable yfin error code.","schema":{"type":"string"}},"x-yfin-error-message":{"description":"Short human-readable error message.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer","minimum":1}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"service_busy":{"summary":"Service busy","value":{"ok":false,"error":{"code":"service_busy","message":"The service is temporarily busy. Retry shortly."}}},"origin_unavailable":{"summary":"Data service unavailable","value":{"ok":false,"meta":{"provider":"yahoo","endpoint":"v7.quote","family":"quote","generated_at":"2026-05-04T19:10:01.073Z","route":"quote"},"error":{"code":"origin_unavailable","message":"The service is temporarily unavailable. Retry shortly."}}}}}}}}}},"/v1/recommendations":{"get":{"tags":["Research"],"operationId":"getRecommendations","summary":"Related Symbols","description":"Returns symbols related to a given ticker.\n\nUse this for peer discovery, comparable-company lists, recommendation widgets, and agents that need to expand from one ticker to nearby instruments.","parameters":[{"name":"symbol","in":"query","required":true,"schema":{"type":"string"},"description":"Single ticker symbol. Alias: ticker."},{"name":"X-Yfin-Contact","in":"header","required":false,"schema":{"type":"string"},"description":"Stable contact identity for higher free request limits, for example an email address or service name."},{"name":"X-Yfin-Key","in":"header","required":false,"schema":{"type":"string"},"description":"API key for higher-volume access. Authorization: Bearer is also supported."}],"responses":{"200":{"description":"Related Symbols response.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request parameters.","headers":{"x-yfin-error-code":{"description":"Stable yfin error code.","schema":{"type":"string"}},"x-yfin-error-message":{"description":"Short human-readable error message.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"bad_request":{"summary":"Invalid request","value":{"ok":false,"error":{"code":"bad_request","message":"recommendations requires symbol=, ticker=, or a /v1/ticker/{symbol}/recommendations route."}}}}}}},"404":{"description":"Unknown route or endpoint.","headers":{"x-yfin-error-code":{"description":"Stable yfin error code.","schema":{"type":"string"}},"x-yfin-error-message":{"description":"Short human-readable error message.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"not_found":{"summary":"Unknown route","value":{"ok":false,"error":{"code":"not_found","message":"Unknown yfin route."}}},"endpoint_not_found":{"summary":"Unknown endpoint ID","value":{"ok":false,"error":{"code":"endpoint_not_found","message":"Endpoint is not in the endpoint catalog."}}}}}}},"405":{"description":"HTTP method is not allowed for this endpoint.","headers":{"x-yfin-error-code":{"description":"Stable yfin error code.","schema":{"type":"string"}},"x-yfin-error-message":{"description":"Short human-readable error message.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"method_not_allowed":{"summary":"Method not allowed","value":{"ok":false,"error":{"code":"method_not_allowed","message":"POST is not allowed for this endpoint."},"allow":["GET"]}}}}}},"429":{"description":"Request limit exceeded. Retry-After is included.","headers":{"x-yfin-error-code":{"description":"Stable yfin error code.","schema":{"type":"string"}},"x-yfin-error-message":{"description":"Short human-readable error message.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer","minimum":1}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitResponse"},"examples":{"rate_limited":{"summary":"Request limit exceeded","value":{"ok":false,"error":{"code":"rate_limited","message":"Request limit exceeded."},"rate_limit":{"tier":"anonymous","retry_after_seconds":42,"upgrade":"Email sam@yfin.dev for an API key."}}}}}}},"502":{"description":"yfin could not complete the upstream data request.","headers":{"x-yfin-error-code":{"description":"Stable yfin error code.","schema":{"type":"string"}},"x-yfin-error-message":{"description":"Short human-readable error message.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"origin_error":{"summary":"Upstream request failed","value":{"ok":false,"meta":{"provider":"yahoo","endpoint":"v7.quote","family":"quote","generated_at":"2026-05-04T19:10:01.075Z","route":"quote"},"error":{"code":"origin_error","message":"The service could not complete the request. Retry shortly."}}}}}}},"503":{"description":"The service is temporarily unavailable or busy.","headers":{"x-yfin-error-code":{"description":"Stable yfin error code.","schema":{"type":"string"}},"x-yfin-error-message":{"description":"Short human-readable error message.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer","minimum":1}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"service_busy":{"summary":"Service busy","value":{"ok":false,"error":{"code":"service_busy","message":"The service is temporarily busy. Retry shortly."}}},"origin_unavailable":{"summary":"Data service unavailable","value":{"ok":false,"meta":{"provider":"yahoo","endpoint":"v7.quote","family":"quote","generated_at":"2026-05-04T19:10:01.073Z","route":"quote"},"error":{"code":"origin_unavailable","message":"The service is temporarily unavailable. Retry shortly."}}}}}}}}}},"/v1/screener":{"get":{"tags":["Discovery"],"operationId":"getScreener","summary":"Screen Securities","description":"Runs a securities screener and returns matching instruments.\n\nUse this for equity, ETF, or fund discovery workflows such as largest market cap, most active, region filters, quote type filters, or custom criteria supplied in a JSON screener body.\n\nGET uses the default screen. POST accepts a screener JSON body for custom filters.","parameters":[{"name":"X-Yfin-Contact","in":"header","required":false,"schema":{"type":"string"},"description":"Stable contact identity for higher free request limits, for example an email address or service name."},{"name":"X-Yfin-Key","in":"header","required":false,"schema":{"type":"string"},"description":"API key for higher-volume access. Authorization: Bearer is also supported."}],"responses":{"200":{"description":"Screen Securities response.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request parameters.","headers":{"x-yfin-error-code":{"description":"Stable yfin error code.","schema":{"type":"string"}},"x-yfin-error-message":{"description":"Short human-readable error message.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"bad_request":{"summary":"Invalid request","value":{"ok":false,"error":{"code":"bad_request","message":"Invalid request parameters."}}}}}}},"404":{"description":"Unknown route or endpoint.","headers":{"x-yfin-error-code":{"description":"Stable yfin error code.","schema":{"type":"string"}},"x-yfin-error-message":{"description":"Short human-readable error message.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"not_found":{"summary":"Unknown route","value":{"ok":false,"error":{"code":"not_found","message":"Unknown yfin route."}}},"endpoint_not_found":{"summary":"Unknown endpoint ID","value":{"ok":false,"error":{"code":"endpoint_not_found","message":"Endpoint is not in the endpoint catalog."}}}}}}},"405":{"description":"HTTP method is not allowed for this endpoint.","headers":{"x-yfin-error-code":{"description":"Stable yfin error code.","schema":{"type":"string"}},"x-yfin-error-message":{"description":"Short human-readable error message.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"method_not_allowed":{"summary":"Method not allowed","value":{"ok":false,"error":{"code":"method_not_allowed","message":"POST is not allowed for this endpoint."},"allow":["GET"]}}}}}},"429":{"description":"Request limit exceeded. Retry-After is included.","headers":{"x-yfin-error-code":{"description":"Stable yfin error code.","schema":{"type":"string"}},"x-yfin-error-message":{"description":"Short human-readable error message.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer","minimum":1}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitResponse"},"examples":{"rate_limited":{"summary":"Request limit exceeded","value":{"ok":false,"error":{"code":"rate_limited","message":"Request limit exceeded."},"rate_limit":{"tier":"anonymous","retry_after_seconds":42,"upgrade":"Email sam@yfin.dev for an API key."}}}}}}},"502":{"description":"yfin could not complete the upstream data request.","headers":{"x-yfin-error-code":{"description":"Stable yfin error code.","schema":{"type":"string"}},"x-yfin-error-message":{"description":"Short human-readable error message.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"origin_error":{"summary":"Upstream request failed","value":{"ok":false,"meta":{"provider":"yahoo","endpoint":"v7.quote","family":"quote","generated_at":"2026-05-04T19:10:01.075Z","route":"quote"},"error":{"code":"origin_error","message":"The service could not complete the request. Retry shortly."}}}}}}},"503":{"description":"The service is temporarily unavailable or busy.","headers":{"x-yfin-error-code":{"description":"Stable yfin error code.","schema":{"type":"string"}},"x-yfin-error-message":{"description":"Short human-readable error message.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer","minimum":1}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"service_busy":{"summary":"Service busy","value":{"ok":false,"error":{"code":"service_busy","message":"The service is temporarily busy. Retry shortly."}}},"origin_unavailable":{"summary":"Data service unavailable","value":{"ok":false,"meta":{"provider":"yahoo","endpoint":"v7.quote","family":"quote","generated_at":"2026-05-04T19:10:01.073Z","route":"quote"},"error":{"code":"origin_unavailable","message":"The service is temporarily unavailable. Retry shortly."}}}}}}}}},"post":{"tags":["Discovery"],"operationId":"postScreener","summary":"Screen Securities","description":"Runs a securities screener and returns matching instruments.\n\nUse this for equity, ETF, or fund discovery workflows such as largest market cap, most active, region filters, quote type filters, or custom criteria supplied in a JSON screener body.\n\nGET uses the default screen. POST accepts a screener JSON body for custom filters.","parameters":[{"name":"X-Yfin-Contact","in":"header","required":false,"schema":{"type":"string"},"description":"Stable contact identity for higher free request limits, for example an email address or service name."},{"name":"X-Yfin-Key","in":"header","required":false,"schema":{"type":"string"},"description":"API key for higher-volume access. Authorization: Bearer is also supported."}],"responses":{"200":{"description":"Screen Securities response.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request parameters.","headers":{"x-yfin-error-code":{"description":"Stable yfin error code.","schema":{"type":"string"}},"x-yfin-error-message":{"description":"Short human-readable error message.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"bad_request":{"summary":"Invalid request","value":{"ok":false,"error":{"code":"bad_request","message":"Invalid request parameters."}}}}}}},"404":{"description":"Unknown route or endpoint.","headers":{"x-yfin-error-code":{"description":"Stable yfin error code.","schema":{"type":"string"}},"x-yfin-error-message":{"description":"Short human-readable error message.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"not_found":{"summary":"Unknown route","value":{"ok":false,"error":{"code":"not_found","message":"Unknown yfin route."}}},"endpoint_not_found":{"summary":"Unknown endpoint ID","value":{"ok":false,"error":{"code":"endpoint_not_found","message":"Endpoint is not in the endpoint catalog."}}}}}}},"405":{"description":"HTTP method is not allowed for this endpoint.","headers":{"x-yfin-error-code":{"description":"Stable yfin error code.","schema":{"type":"string"}},"x-yfin-error-message":{"description":"Short human-readable error message.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"method_not_allowed":{"summary":"Method not allowed","value":{"ok":false,"error":{"code":"method_not_allowed","message":"POST is not allowed for this endpoint."},"allow":["GET"]}}}}}},"429":{"description":"Request limit exceeded. Retry-After is included.","headers":{"x-yfin-error-code":{"description":"Stable yfin error code.","schema":{"type":"string"}},"x-yfin-error-message":{"description":"Short human-readable error message.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer","minimum":1}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitResponse"},"examples":{"rate_limited":{"summary":"Request limit exceeded","value":{"ok":false,"error":{"code":"rate_limited","message":"Request limit exceeded."},"rate_limit":{"tier":"anonymous","retry_after_seconds":42,"upgrade":"Email sam@yfin.dev for an API key."}}}}}}},"502":{"description":"yfin could not complete the upstream data request.","headers":{"x-yfin-error-code":{"description":"Stable yfin error code.","schema":{"type":"string"}},"x-yfin-error-message":{"description":"Short human-readable error message.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"origin_error":{"summary":"Upstream request failed","value":{"ok":false,"meta":{"provider":"yahoo","endpoint":"v7.quote","family":"quote","generated_at":"2026-05-04T19:10:01.075Z","route":"quote"},"error":{"code":"origin_error","message":"The service could not complete the request. Retry shortly."}}}}}}},"503":{"description":"The service is temporarily unavailable or busy.","headers":{"x-yfin-error-code":{"description":"Stable yfin error code.","schema":{"type":"string"}},"x-yfin-error-message":{"description":"Short human-readable error message.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer","minimum":1}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"service_busy":{"summary":"Service busy","value":{"ok":false,"error":{"code":"service_busy","message":"The service is temporarily busy. Retry shortly."}}},"origin_unavailable":{"summary":"Data service unavailable","value":{"ok":false,"meta":{"provider":"yahoo","endpoint":"v7.quote","family":"quote","generated_at":"2026-05-04T19:10:01.073Z","route":"quote"},"error":{"code":"origin_unavailable","message":"The service is temporarily unavailable. Retry shortly."}}}}}}}},"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}},"description":"Optional JSON request body for custom filters or endpoint-specific options."}}},"/v1/screener_discover":{"get":{"tags":["Discovery"],"operationId":"getScreenerDiscover","summary":"Discover Screeners","description":"Returns available screener discovery metadata.\n\nUse this to discover supported screeners and modules before building a custom screener experience or agent workflow.","parameters":[{"name":"region","in":"query","required":false,"schema":{"type":"string"},"description":"Region code, for example US."},{"name":"lang","in":"query","required":false,"schema":{"type":"string"},"description":"Locale language, for example en-US."},{"name":"X-Yfin-Contact","in":"header","required":false,"schema":{"type":"string"},"description":"Stable contact identity for higher free request limits, for example an email address or service name."},{"name":"X-Yfin-Key","in":"header","required":false,"schema":{"type":"string"},"description":"API key for higher-volume access. Authorization: Bearer is also supported."}],"responses":{"200":{"description":"Discover Screeners response.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request parameters.","headers":{"x-yfin-error-code":{"description":"Stable yfin error code.","schema":{"type":"string"}},"x-yfin-error-message":{"description":"Short human-readable error message.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"bad_request":{"summary":"Invalid request","value":{"ok":false,"error":{"code":"bad_request","message":"Invalid request parameters."}}}}}}},"404":{"description":"Unknown route or endpoint.","headers":{"x-yfin-error-code":{"description":"Stable yfin error code.","schema":{"type":"string"}},"x-yfin-error-message":{"description":"Short human-readable error message.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"not_found":{"summary":"Unknown route","value":{"ok":false,"error":{"code":"not_found","message":"Unknown yfin route."}}},"endpoint_not_found":{"summary":"Unknown endpoint ID","value":{"ok":false,"error":{"code":"endpoint_not_found","message":"Endpoint is not in the endpoint catalog."}}}}}}},"405":{"description":"HTTP method is not allowed for this endpoint.","headers":{"x-yfin-error-code":{"description":"Stable yfin error code.","schema":{"type":"string"}},"x-yfin-error-message":{"description":"Short human-readable error message.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"method_not_allowed":{"summary":"Method not allowed","value":{"ok":false,"error":{"code":"method_not_allowed","message":"POST is not allowed for this endpoint."},"allow":["GET"]}}}}}},"429":{"description":"Request limit exceeded. Retry-After is included.","headers":{"x-yfin-error-code":{"description":"Stable yfin error code.","schema":{"type":"string"}},"x-yfin-error-message":{"description":"Short human-readable error message.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer","minimum":1}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitResponse"},"examples":{"rate_limited":{"summary":"Request limit exceeded","value":{"ok":false,"error":{"code":"rate_limited","message":"Request limit exceeded."},"rate_limit":{"tier":"anonymous","retry_after_seconds":42,"upgrade":"Email sam@yfin.dev for an API key."}}}}}}},"502":{"description":"yfin could not complete the upstream data request.","headers":{"x-yfin-error-code":{"description":"Stable yfin error code.","schema":{"type":"string"}},"x-yfin-error-message":{"description":"Short human-readable error message.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"origin_error":{"summary":"Upstream request failed","value":{"ok":false,"meta":{"provider":"yahoo","endpoint":"v7.quote","family":"quote","generated_at":"2026-05-04T19:10:01.075Z","route":"quote"},"error":{"code":"origin_error","message":"The service could not complete the request. Retry shortly."}}}}}}},"503":{"description":"The service is temporarily unavailable or busy.","headers":{"x-yfin-error-code":{"description":"Stable yfin error code.","schema":{"type":"string"}},"x-yfin-error-message":{"description":"Short human-readable error message.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer","minimum":1}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"service_busy":{"summary":"Service busy","value":{"ok":false,"error":{"code":"service_busy","message":"The service is temporarily busy. Retry shortly."}}},"origin_unavailable":{"summary":"Data service unavailable","value":{"ok":false,"meta":{"provider":"yahoo","endpoint":"v7.quote","family":"quote","generated_at":"2026-05-04T19:10:01.073Z","route":"quote"},"error":{"code":"origin_unavailable","message":"The service is temporarily unavailable. Retry shortly."}}}}}}}}}},"/v1/search":{"get":{"tags":["Search"],"operationId":"getSearch","summary":"Search","description":"Returns finance search results for a text query.\n\nUse this for full search experiences where the user may be looking for symbols, companies, funds, quotes, or related finance content.","parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string"},"description":"Search query. Alias: query."},{"name":"X-Yfin-Contact","in":"header","required":false,"schema":{"type":"string"},"description":"Stable contact identity for higher free request limits, for example an email address or service name."},{"name":"X-Yfin-Key","in":"header","required":false,"schema":{"type":"string"},"description":"API key for higher-volume access. Authorization: Bearer is also supported."}],"responses":{"200":{"description":"Search response.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request parameters.","headers":{"x-yfin-error-code":{"description":"Stable yfin error code.","schema":{"type":"string"}},"x-yfin-error-message":{"description":"Short human-readable error message.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"bad_request":{"summary":"Invalid request","value":{"ok":false,"error":{"code":"bad_request","message":"search requires q= or query=."}}}}}}},"404":{"description":"Unknown route or endpoint.","headers":{"x-yfin-error-code":{"description":"Stable yfin error code.","schema":{"type":"string"}},"x-yfin-error-message":{"description":"Short human-readable error message.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"not_found":{"summary":"Unknown route","value":{"ok":false,"error":{"code":"not_found","message":"Unknown yfin route."}}},"endpoint_not_found":{"summary":"Unknown endpoint ID","value":{"ok":false,"error":{"code":"endpoint_not_found","message":"Endpoint is not in the endpoint catalog."}}}}}}},"405":{"description":"HTTP method is not allowed for this endpoint.","headers":{"x-yfin-error-code":{"description":"Stable yfin error code.","schema":{"type":"string"}},"x-yfin-error-message":{"description":"Short human-readable error message.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"method_not_allowed":{"summary":"Method not allowed","value":{"ok":false,"error":{"code":"method_not_allowed","message":"POST is not allowed for this endpoint."},"allow":["GET"]}}}}}},"429":{"description":"Request limit exceeded. Retry-After is included.","headers":{"x-yfin-error-code":{"description":"Stable yfin error code.","schema":{"type":"string"}},"x-yfin-error-message":{"description":"Short human-readable error message.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer","minimum":1}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitResponse"},"examples":{"rate_limited":{"summary":"Request limit exceeded","value":{"ok":false,"error":{"code":"rate_limited","message":"Request limit exceeded."},"rate_limit":{"tier":"anonymous","retry_after_seconds":42,"upgrade":"Email sam@yfin.dev for an API key."}}}}}}},"502":{"description":"yfin could not complete the upstream data request.","headers":{"x-yfin-error-code":{"description":"Stable yfin error code.","schema":{"type":"string"}},"x-yfin-error-message":{"description":"Short human-readable error message.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"origin_error":{"summary":"Upstream request failed","value":{"ok":false,"meta":{"provider":"yahoo","endpoint":"v7.quote","family":"quote","generated_at":"2026-05-04T19:10:01.075Z","route":"quote"},"error":{"code":"origin_error","message":"The service could not complete the request. Retry shortly."}}}}}}},"503":{"description":"The service is temporarily unavailable or busy.","headers":{"x-yfin-error-code":{"description":"Stable yfin error code.","schema":{"type":"string"}},"x-yfin-error-message":{"description":"Short human-readable error message.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer","minimum":1}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"service_busy":{"summary":"Service busy","value":{"ok":false,"error":{"code":"service_busy","message":"The service is temporarily busy. Retry shortly."}}},"origin_unavailable":{"summary":"Data service unavailable","value":{"ok":false,"meta":{"provider":"yahoo","endpoint":"v7.quote","family":"quote","generated_at":"2026-05-04T19:10:01.073Z","route":"quote"},"error":{"code":"origin_unavailable","message":"The service is temporarily unavailable. Retry shortly."}}}}}}}}}},"/v1/sectors":{"get":{"tags":["Discovery"],"operationId":"getSectors","summary":"Sector Data","description":"Returns reference and market data for a sector slug.\n\nUse this to build sector pages, navigate industry groups, compare sector-level activity, or help agents map a broad market theme to investable groups.","parameters":[{"name":"sector","in":"query","required":true,"schema":{"type":"string"},"description":"Sector slug. Alias: slug."},{"name":"X-Yfin-Contact","in":"header","required":false,"schema":{"type":"string"},"description":"Stable contact identity for higher free request limits, for example an email address or service name."},{"name":"X-Yfin-Key","in":"header","required":false,"schema":{"type":"string"},"description":"API key for higher-volume access. Authorization: Bearer is also supported."}],"responses":{"200":{"description":"Sector Data response.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request parameters.","headers":{"x-yfin-error-code":{"description":"Stable yfin error code.","schema":{"type":"string"}},"x-yfin-error-message":{"description":"Short human-readable error message.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"bad_request":{"summary":"Invalid request","value":{"ok":false,"error":{"code":"bad_request","message":"sectors requires sector= or slug=."}}}}}}},"404":{"description":"Unknown route or endpoint.","headers":{"x-yfin-error-code":{"description":"Stable yfin error code.","schema":{"type":"string"}},"x-yfin-error-message":{"description":"Short human-readable error message.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"not_found":{"summary":"Unknown route","value":{"ok":false,"error":{"code":"not_found","message":"Unknown yfin route."}}},"endpoint_not_found":{"summary":"Unknown endpoint ID","value":{"ok":false,"error":{"code":"endpoint_not_found","message":"Endpoint is not in the endpoint catalog."}}}}}}},"405":{"description":"HTTP method is not allowed for this endpoint.","headers":{"x-yfin-error-code":{"description":"Stable yfin error code.","schema":{"type":"string"}},"x-yfin-error-message":{"description":"Short human-readable error message.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"method_not_allowed":{"summary":"Method not allowed","value":{"ok":false,"error":{"code":"method_not_allowed","message":"POST is not allowed for this endpoint."},"allow":["GET"]}}}}}},"429":{"description":"Request limit exceeded. Retry-After is included.","headers":{"x-yfin-error-code":{"description":"Stable yfin error code.","schema":{"type":"string"}},"x-yfin-error-message":{"description":"Short human-readable error message.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer","minimum":1}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitResponse"},"examples":{"rate_limited":{"summary":"Request limit exceeded","value":{"ok":false,"error":{"code":"rate_limited","message":"Request limit exceeded."},"rate_limit":{"tier":"anonymous","retry_after_seconds":42,"upgrade":"Email sam@yfin.dev for an API key."}}}}}}},"502":{"description":"yfin could not complete the upstream data request.","headers":{"x-yfin-error-code":{"description":"Stable yfin error code.","schema":{"type":"string"}},"x-yfin-error-message":{"description":"Short human-readable error message.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"origin_error":{"summary":"Upstream request failed","value":{"ok":false,"meta":{"provider":"yahoo","endpoint":"v7.quote","family":"quote","generated_at":"2026-05-04T19:10:01.075Z","route":"quote"},"error":{"code":"origin_error","message":"The service could not complete the request. Retry shortly."}}}}}}},"503":{"description":"The service is temporarily unavailable or busy.","headers":{"x-yfin-error-code":{"description":"Stable yfin error code.","schema":{"type":"string"}},"x-yfin-error-message":{"description":"Short human-readable error message.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer","minimum":1}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"service_busy":{"summary":"Service busy","value":{"ok":false,"error":{"code":"service_busy","message":"The service is temporarily busy. Retry shortly."}}},"origin_unavailable":{"summary":"Data service unavailable","value":{"ok":false,"meta":{"provider":"yahoo","endpoint":"v7.quote","family":"quote","generated_at":"2026-05-04T19:10:01.073Z","route":"quote"},"error":{"code":"origin_unavailable","message":"The service is temporarily unavailable. Retry shortly."}}}}}}}}}},"/v1/spark":{"get":{"tags":["Prices"],"operationId":"getSpark","summary":"Compact Price Series","description":"Returns lightweight recent price series for one or more symbols.\n\nUse this for small charts, watchlists, overview pages, and agents that need quick price movement data without the full historical chart payload.","parameters":[{"name":"symbols","in":"query","required":true,"schema":{"type":"string"},"description":"Comma-separated ticker symbols. Aliases: symbol, tickers, ticker."},{"name":"X-Yfin-Contact","in":"header","required":false,"schema":{"type":"string"},"description":"Stable contact identity for higher free request limits, for example an email address or service name."},{"name":"X-Yfin-Key","in":"header","required":false,"schema":{"type":"string"},"description":"API key for higher-volume access. Authorization: Bearer is also supported."}],"responses":{"200":{"description":"Compact Price Series response.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request parameters.","headers":{"x-yfin-error-code":{"description":"Stable yfin error code.","schema":{"type":"string"}},"x-yfin-error-message":{"description":"Short human-readable error message.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"bad_request":{"summary":"Invalid request","value":{"ok":false,"error":{"code":"bad_request","message":"spark requires symbols=, symbol=, tickers=, ticker=, or a /v1/ticker/{symbol}/... route."}}}}}}},"404":{"description":"Unknown route or endpoint.","headers":{"x-yfin-error-code":{"description":"Stable yfin error code.","schema":{"type":"string"}},"x-yfin-error-message":{"description":"Short human-readable error message.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"not_found":{"summary":"Unknown route","value":{"ok":false,"error":{"code":"not_found","message":"Unknown yfin route."}}},"endpoint_not_found":{"summary":"Unknown endpoint ID","value":{"ok":false,"error":{"code":"endpoint_not_found","message":"Endpoint is not in the endpoint catalog."}}}}}}},"405":{"description":"HTTP method is not allowed for this endpoint.","headers":{"x-yfin-error-code":{"description":"Stable yfin error code.","schema":{"type":"string"}},"x-yfin-error-message":{"description":"Short human-readable error message.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"method_not_allowed":{"summary":"Method not allowed","value":{"ok":false,"error":{"code":"method_not_allowed","message":"POST is not allowed for this endpoint."},"allow":["GET"]}}}}}},"429":{"description":"Request limit exceeded. Retry-After is included.","headers":{"x-yfin-error-code":{"description":"Stable yfin error code.","schema":{"type":"string"}},"x-yfin-error-message":{"description":"Short human-readable error message.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer","minimum":1}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitResponse"},"examples":{"rate_limited":{"summary":"Request limit exceeded","value":{"ok":false,"error":{"code":"rate_limited","message":"Request limit exceeded."},"rate_limit":{"tier":"anonymous","retry_after_seconds":42,"upgrade":"Email sam@yfin.dev for an API key."}}}}}}},"502":{"description":"yfin could not complete the upstream data request.","headers":{"x-yfin-error-code":{"description":"Stable yfin error code.","schema":{"type":"string"}},"x-yfin-error-message":{"description":"Short human-readable error message.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"origin_error":{"summary":"Upstream request failed","value":{"ok":false,"meta":{"provider":"yahoo","endpoint":"v7.quote","family":"quote","generated_at":"2026-05-04T19:10:01.075Z","route":"quote"},"error":{"code":"origin_error","message":"The service could not complete the request. Retry shortly."}}}}}}},"503":{"description":"The service is temporarily unavailable or busy.","headers":{"x-yfin-error-code":{"description":"Stable yfin error code.","schema":{"type":"string"}},"x-yfin-error-message":{"description":"Short human-readable error message.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer","minimum":1}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"service_busy":{"summary":"Service busy","value":{"ok":false,"error":{"code":"service_busy","message":"The service is temporarily busy. Retry shortly."}}},"origin_unavailable":{"summary":"Data service unavailable","value":{"ok":false,"meta":{"provider":"yahoo","endpoint":"v7.quote","family":"quote","generated_at":"2026-05-04T19:10:01.073Z","route":"quote"},"error":{"code":"origin_unavailable","message":"The service is temporarily unavailable. Retry shortly."}}}}}}}}}},"/v1/timeseries":{"get":{"tags":["Fundamentals"],"operationId":"getTimeseries","summary":"Fundamental Time Series","description":"Returns time-series fundamentals for one symbol.\n\nUse this for historical financial metrics, trend analysis, factor models, and research agents that need fundamentals across reporting periods.","parameters":[{"name":"symbol","in":"query","required":true,"schema":{"type":"string"},"description":"Single ticker symbol. Alias: ticker."},{"name":"X-Yfin-Contact","in":"header","required":false,"schema":{"type":"string"},"description":"Stable contact identity for higher free request limits, for example an email address or service name."},{"name":"X-Yfin-Key","in":"header","required":false,"schema":{"type":"string"},"description":"API key for higher-volume access. Authorization: Bearer is also supported."}],"responses":{"200":{"description":"Fundamental Time Series response.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request parameters.","headers":{"x-yfin-error-code":{"description":"Stable yfin error code.","schema":{"type":"string"}},"x-yfin-error-message":{"description":"Short human-readable error message.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"bad_request":{"summary":"Invalid request","value":{"ok":false,"error":{"code":"bad_request","message":"timeseries requires symbol=, ticker=, or a /v1/ticker/{symbol}/timeseries route."}}}}}}},"404":{"description":"Unknown route or endpoint.","headers":{"x-yfin-error-code":{"description":"Stable yfin error code.","schema":{"type":"string"}},"x-yfin-error-message":{"description":"Short human-readable error message.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"not_found":{"summary":"Unknown route","value":{"ok":false,"error":{"code":"not_found","message":"Unknown yfin route."}}},"endpoint_not_found":{"summary":"Unknown endpoint ID","value":{"ok":false,"error":{"code":"endpoint_not_found","message":"Endpoint is not in the endpoint catalog."}}}}}}},"405":{"description":"HTTP method is not allowed for this endpoint.","headers":{"x-yfin-error-code":{"description":"Stable yfin error code.","schema":{"type":"string"}},"x-yfin-error-message":{"description":"Short human-readable error message.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"method_not_allowed":{"summary":"Method not allowed","value":{"ok":false,"error":{"code":"method_not_allowed","message":"POST is not allowed for this endpoint."},"allow":["GET"]}}}}}},"429":{"description":"Request limit exceeded. Retry-After is included.","headers":{"x-yfin-error-code":{"description":"Stable yfin error code.","schema":{"type":"string"}},"x-yfin-error-message":{"description":"Short human-readable error message.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer","minimum":1}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitResponse"},"examples":{"rate_limited":{"summary":"Request limit exceeded","value":{"ok":false,"error":{"code":"rate_limited","message":"Request limit exceeded."},"rate_limit":{"tier":"anonymous","retry_after_seconds":42,"upgrade":"Email sam@yfin.dev for an API key."}}}}}}},"502":{"description":"yfin could not complete the upstream data request.","headers":{"x-yfin-error-code":{"description":"Stable yfin error code.","schema":{"type":"string"}},"x-yfin-error-message":{"description":"Short human-readable error message.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"origin_error":{"summary":"Upstream request failed","value":{"ok":false,"meta":{"provider":"yahoo","endpoint":"v7.quote","family":"quote","generated_at":"2026-05-04T19:10:01.075Z","route":"quote"},"error":{"code":"origin_error","message":"The service could not complete the request. Retry shortly."}}}}}}},"503":{"description":"The service is temporarily unavailable or busy.","headers":{"x-yfin-error-code":{"description":"Stable yfin error code.","schema":{"type":"string"}},"x-yfin-error-message":{"description":"Short human-readable error message.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer","minimum":1}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"service_busy":{"summary":"Service busy","value":{"ok":false,"error":{"code":"service_busy","message":"The service is temporarily busy. Retry shortly."}}},"origin_unavailable":{"summary":"Data service unavailable","value":{"ok":false,"meta":{"provider":"yahoo","endpoint":"v7.quote","family":"quote","generated_at":"2026-05-04T19:10:01.073Z","route":"quote"},"error":{"code":"origin_unavailable","message":"The service is temporarily unavailable. Retry shortly."}}}}}}}}}},"/v1/trending":{"get":{"tags":["Discovery"],"operationId":"getTrending","summary":"Trending Symbols","description":"Returns symbols currently trending for a region.\n\nUse this for discovery surfaces, market-mover modules, alerting ideas, and agents that need a starting set of active tickers.","parameters":[{"name":"region","in":"query","required":false,"schema":{"type":"string"},"description":"Region code, for example US."},{"name":"X-Yfin-Contact","in":"header","required":false,"schema":{"type":"string"},"description":"Stable contact identity for higher free request limits, for example an email address or service name."},{"name":"X-Yfin-Key","in":"header","required":false,"schema":{"type":"string"},"description":"API key for higher-volume access. Authorization: Bearer is also supported."}],"responses":{"200":{"description":"Trending Symbols response.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Invalid request parameters.","headers":{"x-yfin-error-code":{"description":"Stable yfin error code.","schema":{"type":"string"}},"x-yfin-error-message":{"description":"Short human-readable error message.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"bad_request":{"summary":"Invalid request","value":{"ok":false,"error":{"code":"bad_request","message":"Invalid request parameters."}}}}}}},"404":{"description":"Unknown route or endpoint.","headers":{"x-yfin-error-code":{"description":"Stable yfin error code.","schema":{"type":"string"}},"x-yfin-error-message":{"description":"Short human-readable error message.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"not_found":{"summary":"Unknown route","value":{"ok":false,"error":{"code":"not_found","message":"Unknown yfin route."}}},"endpoint_not_found":{"summary":"Unknown endpoint ID","value":{"ok":false,"error":{"code":"endpoint_not_found","message":"Endpoint is not in the endpoint catalog."}}}}}}},"405":{"description":"HTTP method is not allowed for this endpoint.","headers":{"x-yfin-error-code":{"description":"Stable yfin error code.","schema":{"type":"string"}},"x-yfin-error-message":{"description":"Short human-readable error message.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"method_not_allowed":{"summary":"Method not allowed","value":{"ok":false,"error":{"code":"method_not_allowed","message":"POST is not allowed for this endpoint."},"allow":["GET"]}}}}}},"429":{"description":"Request limit exceeded. Retry-After is included.","headers":{"x-yfin-error-code":{"description":"Stable yfin error code.","schema":{"type":"string"}},"x-yfin-error-message":{"description":"Short human-readable error message.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer","minimum":1}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitResponse"},"examples":{"rate_limited":{"summary":"Request limit exceeded","value":{"ok":false,"error":{"code":"rate_limited","message":"Request limit exceeded."},"rate_limit":{"tier":"anonymous","retry_after_seconds":42,"upgrade":"Email sam@yfin.dev for an API key."}}}}}}},"502":{"description":"yfin could not complete the upstream data request.","headers":{"x-yfin-error-code":{"description":"Stable yfin error code.","schema":{"type":"string"}},"x-yfin-error-message":{"description":"Short human-readable error message.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"origin_error":{"summary":"Upstream request failed","value":{"ok":false,"meta":{"provider":"yahoo","endpoint":"v7.quote","family":"quote","generated_at":"2026-05-04T19:10:01.075Z","route":"quote"},"error":{"code":"origin_error","message":"The service could not complete the request. Retry shortly."}}}}}}},"503":{"description":"The service is temporarily unavailable or busy.","headers":{"x-yfin-error-code":{"description":"Stable yfin error code.","schema":{"type":"string"}},"x-yfin-error-message":{"description":"Short human-readable error message.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer","minimum":1}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"service_busy":{"summary":"Service busy","value":{"ok":false,"error":{"code":"service_busy","message":"The service is temporarily busy. Retry shortly."}}},"origin_unavailable":{"summary":"Data service unavailable","value":{"ok":false,"meta":{"provider":"yahoo","endpoint":"v7.quote","family":"quote","generated_at":"2026-05-04T19:10:01.073Z","route":"quote"},"error":{"code":"origin_unavailable","message":"The service is temporarily unavailable. Retry shortly."}}}}}}}}}}}}