{"openapi":"3.1.0","info":{"title":"gfin Market Data API","version":"0.1.0","description":"Hosted, cached, AI-friendly market data API backed by Google Finance."},"servers":[{"url":"https://api.gfin.dev"}],"tags":[{"name":"System","description":"Health, OpenAPI, and public route catalog."},{"name":"Search","description":"Symbol, company, and finance-entity discovery."},{"name":"Research","description":"Natural-language finance research workflows."},{"name":"Markets","description":"Market summaries, notable stocks, events, and highlights."},{"name":"News","description":"Finance news feeds and story collections."},{"name":"Quotes","description":"Quote summaries, details, history, financials, earnings, related entities, and sentiment."},{"name":"Realtime","description":"Realtime price snapshots and trend lines."},{"name":"User Context","description":"User-context routes that may return empty data for anonymous requests."}],"components":{"schemas":{"GenericSuccessResponse":{"type":"object","properties":{"meta":{"$ref":"#/components/schemas/ResponseMeta"},"data":{"$ref":"#/components/schemas/FinanceData"}},"required":["meta","data"],"additionalProperties":true},"HealthResponse":{"type":"object","properties":{"ok":{"type":"boolean","const":true},"name":{"type":"string","description":"Service name."},"version":{"type":"string","description":"API version."},"data_source":{"type":"string","const":"google_finance","description":"Source used by gfin for this route family."},"route_count":{"type":"integer","description":"Number of currently available public routes."},"cache":{"type":"object","properties":{"cached_reads":{"type":"boolean"},"stale_if_error":{"type":"boolean"},"request_coalescing":{"type":"boolean"}}},"identity":{"type":"object","description":"Public identity and rate-limit policy.","additionalProperties":true}},"required":["ok","name","version","data_source","route_count","cache","identity"]},"RouteCatalogResponse":{"type":"object","properties":{"route_count":{"type":"integer"},"data_source":{"type":"string","const":"google_finance"},"identity_policy":{"type":"object","description":"Public identity and rate-limit policy.","additionalProperties":true},"routes":{"type":"object","description":"Map of public route names to public paths.","additionalProperties":{"$ref":"#/components/schemas/RouteCatalogRoute"}}},"required":["route_count","data_source","identity_policy","routes"]},"RouteCatalogRoute":{"type":"object","properties":{"path":{"type":"string","description":"Public gfin path."},"summary":{"type":"string","description":"Short route label."},"description":{"type":"string","description":"Finance-domain route description."}},"required":["path","summary","description"]},"AuthOtpRequest":{"type":"object","properties":{"email":{"type":"string","format":"email"}},"required":["email"],"additionalProperties":false},"AuthVerifyRequest":{"type":"object","properties":{"email":{"type":"string","format":"email"},"code":{"type":"string","pattern":"^\\d{6}$"},"create_key":{"type":"boolean","default":true},"label":{"type":"string"},"expires_in_days":{"type":"integer","minimum":1,"maximum":365}},"required":["email","code"],"additionalProperties":false},"AuthLimitRequest":{"type":"object","properties":{"requested_rps":{"type":"number","minimum":0},"requested_origin_rps":{"type":"number","minimum":0},"use_case":{"type":"string"},"message":{"type":"string"}},"additionalProperties":false},"ResponseMeta":{"type":"object","properties":{"provider":{"type":"string","const":"google_finance"},"route":{"type":"string","description":"Public gfin route name."},"cache":{"type":"string","description":"Cache state for this response."},"ttl_seconds":{"type":"integer","minimum":0},"stale_seconds":{"type":"integer","minimum":0},"generated_at":{"type":"string","format":"date-time"},"request_id":{"type":"string"},"identity_tier":{"type":"string","description":"Rate-limit identity tier used for this request."}},"required":["provider","route","cache","ttl_seconds","stale_seconds","generated_at","request_id","identity_tier"],"additionalProperties":true},"FinanceData":{"description":"Route-specific finance data. Common quote, news, search, earnings, and price-series routes are projected into named fields; less structured route families return finance records without backend transport identifiers.","anyOf":[{"type":"object","additionalProperties":true},{"type":"array","items":{}},{"type":"string"},{"type":"number"},{"type":"integer"},{"type":"boolean"},{"type":"null"}]},"ErrorDetail":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable error message."},"next_action":{"type":"string","description":"Recommended client action."},"request_id":{"type":"string","description":"Request ID for logs and support."}},"required":["code","message","next_action","request_id"],"additionalProperties":true},"ErrorResponse":{"type":"object","properties":{"error":{"$ref":"#/components/schemas/ErrorDetail"},"meta":{"type":"object","description":"Response metadata when available.","additionalProperties":true},"rate_limit":{"type":"object","description":"Rate-limit detail when available.","additionalProperties":true}},"required":["error"],"additionalProperties":true},"RateLimitResponse":{"type":"object","properties":{"error":{"$ref":"#/components/schemas/ErrorDetail"},"rate_limit":{"type":"object","properties":{"scope":{"type":"string","enum":["request","source_fetch","origin","research","auth","limit_request"]},"tier":{"type":"string","enum":["anonymous","contact","key","auth"]},"reason":{"type":"string"},"retry_after_seconds":{"type":"integer","minimum":1},"limit":{"anyOf":[{"type":"integer"},{"type":"null"}]},"remaining":{"type":"integer","minimum":0},"reset_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"upgrade":{"type":"string"}},"required":["scope","tier","reason","retry_after_seconds","limit","remaining","reset_at","upgrade"],"additionalProperties":true}},"required":["error","rate_limit"],"additionalProperties":false},"SymbolsSearchData":{"description":"Search results with symbol, exchange, name, quote snapshot, and instrument identifiers when available.","anyOf":[{"type":"object","additionalProperties":true},{"type":"array","items":{}},{"type":"string"},{"type":"number"},{"type":"integer"},{"type":"boolean"},{"type":"null"}]},"SymbolsSearchResponse":{"type":"object","properties":{"meta":{"$ref":"#/components/schemas/ResponseMeta"},"data":{"$ref":"#/components/schemas/SymbolsSearchData"}},"required":["meta","data"],"additionalProperties":true},"ResearchData":{"description":"Research result for the requested natural-language finance query, including answer text and citations when available.","anyOf":[{"type":"object","additionalProperties":true},{"type":"array","items":{}},{"type":"string"},{"type":"number"},{"type":"integer"},{"type":"boolean"},{"type":"null"}]},"ResearchResponse":{"type":"object","properties":{"meta":{"$ref":"#/components/schemas/ResponseMeta"},"data":{"$ref":"#/components/schemas/ResearchData"}},"required":["meta","data"],"additionalProperties":true},"MarketSummaryData":{"description":"Market themes, summaries, related stories, and current market context.","anyOf":[{"type":"object","additionalProperties":true},{"type":"array","items":{}},{"type":"string"},{"type":"number"},{"type":"integer"},{"type":"boolean"},{"type":"null"}]},"MarketSummaryResponse":{"type":"object","properties":{"meta":{"$ref":"#/components/schemas/ResponseMeta"},"data":{"$ref":"#/components/schemas/MarketSummaryData"}},"required":["meta","data"],"additionalProperties":true},"MarketMoversData":{"description":"Notable instruments, quote snapshots, and supporting discovery context.","anyOf":[{"type":"object","additionalProperties":true},{"type":"array","items":{}},{"type":"string"},{"type":"number"},{"type":"integer"},{"type":"boolean"},{"type":"null"}]},"MarketMoversResponse":{"type":"object","properties":{"meta":{"$ref":"#/components/schemas/ResponseMeta"},"data":{"$ref":"#/components/schemas/MarketMoversData"}},"required":["meta","data"],"additionalProperties":true},"MarketEventsData":{"description":"Finance events, dates, event categories, and related symbols when available.","anyOf":[{"type":"object","additionalProperties":true},{"type":"array","items":{}},{"type":"string"},{"type":"number"},{"type":"integer"},{"type":"boolean"},{"type":"null"}]},"MarketEventsResponse":{"type":"object","properties":{"meta":{"$ref":"#/components/schemas/ResponseMeta"},"data":{"$ref":"#/components/schemas/MarketEventsData"}},"required":["meta","data"],"additionalProperties":true},"NewsData":{"description":"Finance news stories with URLs, titles, publishers, timestamps, related instruments, and snippets when available.","anyOf":[{"type":"object","additionalProperties":true},{"type":"array","items":{}},{"type":"string"},{"type":"number"},{"type":"integer"},{"type":"boolean"},{"type":"null"}]},"NewsResponse":{"type":"object","properties":{"meta":{"$ref":"#/components/schemas/ResponseMeta"},"data":{"$ref":"#/components/schemas/NewsData"}},"required":["meta","data"],"additionalProperties":true},"NewsCollectionsData":{"description":"Finance story collections with story groups and related metadata when available.","anyOf":[{"type":"object","additionalProperties":true},{"type":"array","items":{}},{"type":"string"},{"type":"number"},{"type":"integer"},{"type":"boolean"},{"type":"null"}]},"NewsCollectionsResponse":{"type":"object","properties":{"meta":{"$ref":"#/components/schemas/ResponseMeta"},"data":{"$ref":"#/components/schemas/NewsCollectionsData"}},"required":["meta","data"],"additionalProperties":true},"MarketHighlightsData":{"description":"Featured market highlights and supporting finance context.","anyOf":[{"type":"object","additionalProperties":true},{"type":"array","items":{}},{"type":"string"},{"type":"number"},{"type":"integer"},{"type":"boolean"},{"type":"null"}]},"MarketHighlightsResponse":{"type":"object","properties":{"meta":{"$ref":"#/components/schemas/ResponseMeta"},"data":{"$ref":"#/components/schemas/MarketHighlightsData"}},"required":["meta","data"],"additionalProperties":true},"QuoteData":{"description":"Compact quote snapshot for the requested symbol.","anyOf":[{"type":"object","additionalProperties":true},{"type":"array","items":{}},{"type":"string"},{"type":"number"},{"type":"integer"},{"type":"boolean"},{"type":"null"}]},"QuoteResponse":{"type":"object","properties":{"meta":{"$ref":"#/components/schemas/ResponseMeta"},"data":{"$ref":"#/components/schemas/QuoteData"}},"required":["meta","data"],"additionalProperties":true},"QuoteDetailsData":{"description":"Expanded quote details for the requested symbol.","anyOf":[{"type":"object","additionalProperties":true},{"type":"array","items":{}},{"type":"string"},{"type":"number"},{"type":"integer"},{"type":"boolean"},{"type":"null"}]},"QuoteDetailsResponse":{"type":"object","properties":{"meta":{"$ref":"#/components/schemas/ResponseMeta"},"data":{"$ref":"#/components/schemas/QuoteDetailsData"}},"required":["meta","data"],"additionalProperties":true},"QuoteProfileData":{"description":"Company or instrument profile data for the requested symbol.","anyOf":[{"type":"object","additionalProperties":true},{"type":"array","items":{}},{"type":"string"},{"type":"number"},{"type":"integer"},{"type":"boolean"},{"type":"null"}]},"QuoteProfileResponse":{"type":"object","properties":{"meta":{"$ref":"#/components/schemas/ResponseMeta"},"data":{"$ref":"#/components/schemas/QuoteProfileData"}},"required":["meta","data"],"additionalProperties":true},"PricesHistoryData":{"description":"Historical price observations for the requested symbol.","anyOf":[{"type":"object","additionalProperties":true},{"type":"array","items":{}},{"type":"string"},{"type":"number"},{"type":"integer"},{"type":"boolean"},{"type":"null"}]},"PricesHistoryResponse":{"type":"object","properties":{"meta":{"$ref":"#/components/schemas/ResponseMeta"},"data":{"$ref":"#/components/schemas/PricesHistoryData"}},"required":["meta","data"],"additionalProperties":true},"FinancialsData":{"description":"Financial statement and metric data for the requested symbol when available.","anyOf":[{"type":"object","additionalProperties":true},{"type":"array","items":{}},{"type":"string"},{"type":"number"},{"type":"integer"},{"type":"boolean"},{"type":"null"}]},"FinancialsResponse":{"type":"object","properties":{"meta":{"$ref":"#/components/schemas/ResponseMeta"},"data":{"$ref":"#/components/schemas/FinancialsData"}},"required":["meta","data"],"additionalProperties":true},"EarningsData":{"description":"Earnings history and expectations for the requested symbol when available.","anyOf":[{"type":"object","additionalProperties":true},{"type":"array","items":{}},{"type":"string"},{"type":"number"},{"type":"integer"},{"type":"boolean"},{"type":"null"}]},"EarningsResponse":{"type":"object","properties":{"meta":{"$ref":"#/components/schemas/ResponseMeta"},"data":{"$ref":"#/components/schemas/EarningsData"}},"required":["meta","data"],"additionalProperties":true},"RelatedAssetsData":{"description":"Related instruments, peers, and comparable entities for the requested symbol.","anyOf":[{"type":"object","additionalProperties":true},{"type":"array","items":{}},{"type":"string"},{"type":"number"},{"type":"integer"},{"type":"boolean"},{"type":"null"}]},"RelatedAssetsResponse":{"type":"object","properties":{"meta":{"$ref":"#/components/schemas/ResponseMeta"},"data":{"$ref":"#/components/schemas/RelatedAssetsData"}},"required":["meta","data"],"additionalProperties":true},"SentimentData":{"description":"Sentiment-oriented data for the requested symbol when available.","anyOf":[{"type":"object","additionalProperties":true},{"type":"array","items":{}},{"type":"string"},{"type":"number"},{"type":"integer"},{"type":"boolean"},{"type":"null"}]},"SentimentResponse":{"type":"object","properties":{"meta":{"$ref":"#/components/schemas/ResponseMeta"},"data":{"$ref":"#/components/schemas/SentimentData"}},"required":["meta","data"],"additionalProperties":true},"RealtimeQuotesData":{"description":"Realtime quote snapshots for the requested finance entities.","anyOf":[{"type":"object","additionalProperties":true},{"type":"array","items":{}},{"type":"string"},{"type":"number"},{"type":"integer"},{"type":"boolean"},{"type":"null"}]},"RealtimeQuotesResponse":{"type":"object","properties":{"meta":{"$ref":"#/components/schemas/ResponseMeta"},"data":{"$ref":"#/components/schemas/RealtimeQuotesData"}},"required":["meta","data"],"additionalProperties":true},"RealtimeTrendsData":{"description":"Realtime trend-line observations for the requested finance entities.","anyOf":[{"type":"object","additionalProperties":true},{"type":"array","items":{}},{"type":"string"},{"type":"number"},{"type":"integer"},{"type":"boolean"},{"type":"null"}]},"RealtimeTrendsResponse":{"type":"object","properties":{"meta":{"$ref":"#/components/schemas/ResponseMeta"},"data":{"$ref":"#/components/schemas/RealtimeTrendsData"}},"required":["meta","data"],"additionalProperties":true},"WatchlistsData":{"description":"Watchlist data available to the request context.","anyOf":[{"type":"object","additionalProperties":true},{"type":"array","items":{}},{"type":"string"},{"type":"number"},{"type":"integer"},{"type":"boolean"},{"type":"null"}]},"WatchlistsResponse":{"type":"object","properties":{"meta":{"$ref":"#/components/schemas/ResponseMeta"},"data":{"$ref":"#/components/schemas/WatchlistsData"}},"required":["meta","data"],"additionalProperties":true}}},"paths":{"/v1/health":{"get":{"tags":["System"],"operationId":"getHealth","summary":"Service health.","description":"Returns basic gfin service status, cache policy, identity policy, and the number of currently shipped public routes.","responses":{"200":{"description":"Health response.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HealthResponse"},"examples":{"success":{"summary":"Success","value":{"ok":true,"name":"gfin","version":"0.1.0","data_source":"google_finance","route_count":19,"cache":{"cached_reads":true,"stale_if_error":true,"request_coalescing":true},"identity":{"anonymous":"Works without setup with IP-based request limits.","contact":"Send X-Gfin-Contact or SDK contact= for higher no-key limits and support metadata.","auth":"Create API keys by requesting an email code at /v1/auth/otp and verifying it at /v1/auth/verify.","key":"Send Authorization: Bearer <api_key> or X-Gfin-Key for higher free limits.","limits":"When key-tier limits are too low, email sam@gfin.dev or POST /v1/auth/limits/requests. Programmatic requests are limited to 1 per minute per API key.","research":"Natural-language research is constrained separately; default public research budget is 1 request per minute per identity."}}}}}}}}}},"/v1/endpoints":{"get":{"tags":["System"],"operationId":"listRoutesLegacy","summary":"Route Catalog","description":"Returns the machine-readable catalog of supported public gfin routes. This legacy path is kept as an alias for /v1/routes.","parameters":[],"responses":{"200":{"description":"Route catalog.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RouteCatalogResponse"},"examples":{"success":{"summary":"Success","value":{"route_count":19,"data_source":"google_finance","identity_policy":{"anonymous":"Works without setup with IP-based request limits.","contact":"Send X-Gfin-Contact or SDK contact= for higher no-key limits and support metadata.","auth":"Create API keys by requesting an email code at /v1/auth/otp and verifying it at /v1/auth/verify.","key":"Send Authorization: Bearer <api_key> or X-Gfin-Key for higher free limits.","limits":"When key-tier limits are too low, email sam@gfin.dev or POST /v1/auth/limits/requests. Programmatic requests are limited to 1 per minute per API key.","research":"Natural-language research is constrained separately; default public research budget is 1 request per minute per identity."},"routes":{"symbols_search":{"path":"/v1/symbols/search","summary":"Symbol Search","description":"Returns symbol and instrument search results for text input."},"quote":{"path":"/v1/quotes/{symbol}","summary":"Quote","description":"Returns a compact quote snapshot for one symbol."},"research":{"path":"/v1/research","summary":"Research","description":"Runs a natural-language finance research query and returns an answer-oriented finance research result."}}}}}}}}}}},"/v1/routes":{"get":{"tags":["System"],"operationId":"listRoutes","summary":"Route Catalog","description":"Returns the machine-readable catalog of supported public gfin routes. Use this for tool discovery, code generation, and agents that need to inspect available finance data routes programmatically.","parameters":[],"responses":{"200":{"description":"Route catalog.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RouteCatalogResponse"},"examples":{"success":{"summary":"Success","value":{"route_count":19,"data_source":"google_finance","identity_policy":{"anonymous":"Works without setup with IP-based request limits.","contact":"Send X-Gfin-Contact or SDK contact= for higher no-key limits and support metadata.","auth":"Create API keys by requesting an email code at /v1/auth/otp and verifying it at /v1/auth/verify.","key":"Send Authorization: Bearer <api_key> or X-Gfin-Key for higher free limits.","limits":"When key-tier limits are too low, email sam@gfin.dev or POST /v1/auth/limits/requests. Programmatic requests are limited to 1 per minute per API key.","research":"Natural-language research is constrained separately; default public research budget is 1 request per minute per identity."},"routes":{"symbols_search":{"path":"/v1/symbols/search","summary":"Symbol Search","description":"Returns symbol and instrument search results for text input."},"quote":{"path":"/v1/quotes/{symbol}","summary":"Quote","description":"Returns a compact quote snapshot for one symbol."},"research":{"path":"/v1/research","summary":"Research","description":"Runs a natural-language finance research query and returns an answer-oriented finance research result."}}}}}}}}}}},"/v1/auth/otp":{"post":{"tags":["System"],"operationId":"requestAuthOtp","summary":"Request email verification code.","description":"Sends a short-lived email verification code used to create or manage gfin API keys.","requestBody":{"required":true,"description":"Email verification request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthOtpRequest"},"examples":{"request":{"summary":"Request","value":{"email":"you@example.com"}}}}}},"responses":{"202":{"description":"Verification code accepted for delivery.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericSuccessResponse"},"examples":{"success":{"summary":"Success","value":{"ok":true,"data":{"email":"you@example.com","expires_in_seconds":600,"delivery":"email"}}}}}}},"400":{"description":"Invalid email or JSON body.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"bad_request":{"summary":"Bad Request","value":{"error":{"code":"bad_request","message":"A valid email is required.","next_action":"fix_auth","request_id":"req_example"}}}}}}},"503":{"description":"Auth storage or email delivery is unavailable.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"auth_not_configured":{"summary":"Auth Not Configured","value":{"error":{"code":"auth_not_configured","message":"API key authentication is not configured.","next_action":"fix_auth","request_id":"req_example"}}}}}}}}}},"/v1/auth/verify":{"post":{"tags":["System"],"operationId":"verifyAuthOtp","summary":"Verify email code.","description":"Verifies an email code, returns a short-lived management token, and creates an API key by default.","requestBody":{"required":true,"description":"Email code verification request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthVerifyRequest"},"examples":{"request":{"summary":"Request","value":{"email":"you@example.com","code":"123456"}}}}}},"responses":{"200":{"description":"Email verified.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericSuccessResponse"},"examples":{"success":{"summary":"Success","value":{"ok":true,"data":{"email":"you@example.com","management_token":"gfin_mgmt_...","token_type":"Bearer","management_expires_in_seconds":900,"api_key":"gfin_live_...","key":{"id":"0123456789abcdef01234567","email":"you@example.com","label":"default","requests_per_minute":30000,"origin_per_minute":3000}}}}}}}},"400":{"description":"Invalid or expired code.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"invalid_code":{"summary":"Invalid Code","value":{"error":{"code":"invalid_code","message":"Verification code is invalid or expired.","next_action":"fix_auth","request_id":"req_example"}}}}}}},"503":{"description":"Auth storage is unavailable.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"auth_not_configured":{"summary":"Auth Not Configured","value":{"error":{"code":"auth_not_configured","message":"API key authentication is not configured.","next_action":"fix_auth","request_id":"req_example"}}}}}}}}}},"/v1/auth/limits/requests":{"post":{"tags":["System"],"operationId":"requestLimitIncrease","summary":"Request custom rate limits.","description":"Submits a custom rate-limit request for the authenticated API key. This route is limited to 1 request per minute per API key.","parameters":[{"name":"X-Gfin-Key","in":"header","required":false,"schema":{"type":"string"},"description":"API key for higher-volume access. Authorization: Bearer is also supported."}],"requestBody":{"required":true,"description":"Requested custom rate limits and use case.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthLimitRequest"},"examples":{"request":{"summary":"Request","value":{"requested_rps":100,"use_case":"production agent workload"}}}}}},"responses":{"202":{"description":"Custom rate-limit request received.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericSuccessResponse"},"examples":{"success":{"summary":"Success","value":{"ok":true,"data":{"id":"req_example","email":"you@example.com","status":"received","notification":{"mode":"email"},"message":"Custom rate-limit request received. You can also email sam@gfin.dev."}}}}}}},"401":{"description":"API key is required.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"api_key_required":{"summary":"Api Key Required","value":{"error":{"code":"api_key_required","message":"API key is required to request custom rate limits.","next_action":"fix_auth","request_id":"req_example"}}}}}}},"429":{"description":"Request limit exceeded. Retry-After is included.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","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":{"error":{"code":"rate_limited","message":"Request budget exhausted.","next_action":"retry_after","request_id":"req_example"},"rate_limit":{"scope":"request","tier":"anonymous","reason":"rate_limited","retry_after_seconds":42,"limit":1200,"remaining":0,"reset_at":"2026-05-05T18:33:00.000Z","upgrade":"Send X-Gfin-Contact for higher no-key limits; email sam@gfin.dev for an API key."}}}}}}}}}},"/v1/symbols/search":{"get":{"tags":["Search"],"operationId":"getSymbolsSearch","summary":"Symbol Search","description":"Returns symbol and instrument search results for text input.\n\nUse this for search boxes, ticker resolution, company lookup, and agents that need to turn user text into finance entities.","parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string"},"description":"Search text such as a company name, fund name, index name, or partial ticker. Aliases: query, term."},{"name":"X-Gfin-Contact","in":"header","required":false,"schema":{"type":"string"},"description":"Stable contact identity for higher public request limits, for example an email address or service name."},{"name":"X-Gfin-Key","in":"header","required":false,"schema":{"type":"string"},"description":"API key for higher-volume access. Authorization: Bearer is also supported."}],"responses":{"200":{"description":"Symbol Search response.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}},"x-gfin-cache":{"description":"Cache state for this response.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SymbolsSearchResponse"},"examples":{"success":{"summary":"Symbols Search success","value":{"meta":{"provider":"google_finance","route":"symbols_search","cache":"kv","ttl_seconds":300,"stale_seconds":3600,"generated_at":"2026-05-05T18:32:52.359Z","request_id":"req_example","identity_tier":"anonymous"},"data":{"resource":"search_results","query":"apple","results":[{"entity_id":"%2Fm%2F07zmbvf","symbol":"AAPL","exchange":"NASDAQ","name":"Apple Inc","type":"instrument","match_text":"Apple Inc","quote":{"entity_id":"%2Fm%2F07zmbvf","symbol":"AAPL","exchange":"NASDAQ","name":"Apple Inc","currency":"USD","country":"US","timezone":"America/New_York","quote":{"price":198.53,"change":1.24,"change_percent":0.63,"previous_close":197.29,"last_trade_time":"2026-05-05T18:32:00.000Z"},"extended_hours_quote":null}}]}}}}}}},"400":{"description":"Invalid request parameters.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"bad_request":{"summary":"Invalid request","value":{"error":{"code":"bad_request","message":"Search requires q= with a company name, instrument name, or ticker.","next_action":"fix_request","request_id":"req_example"}}}}}}},"401":{"description":"The supplied API key is invalid.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"invalid_api_key":{"summary":"Invalid API key","value":{"error":{"code":"invalid_api_key","message":"The supplied gfin API key is not valid.","next_action":"fix_auth","request_id":"req_example"}}}}}}},"404":{"description":"Unknown route.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"not_found":{"summary":"Unknown route","value":{"error":{"code":"not_found","message":"Unknown gfin route. Use /v1/routes or /v1/openapi.json to inspect supported routes.","next_action":"inspect_error","request_id":"req_example"}}},"route_not_found":{"summary":"Unknown route","value":{"error":{"code":"route_not_found","message":"This gfin route is not available.","next_action":"choose_supported_route","request_id":"req_example"}}}}}}},"405":{"description":"HTTP method is not allowed for this route.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"method_not_allowed":{"summary":"Method not allowed","value":{"error":{"code":"method_not_allowed","message":"gfin v1 exposes read-only GET routes.","next_action":"inspect_error","request_id":"req_example"}}}}}}},"429":{"description":"Request limit exceeded. Retry-After is included.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","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":{"error":{"code":"rate_limited","message":"Request budget exhausted.","next_action":"retry_after","request_id":"req_example"},"rate_limit":{"scope":"request","tier":"anonymous","reason":"rate_limited","retry_after_seconds":42,"limit":1200,"remaining":0,"reset_at":"2026-05-05T18:33:00.000Z","upgrade":"Send X-Gfin-Contact for higher no-key limits; email sam@gfin.dev for an API key."}}}}}}},"502":{"description":"The data request could not be completed.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"data_source_response_error":{"summary":"Data source response error","value":{"meta":{"provider":"google_finance","route":"symbols_search","cache":"kv","ttl_seconds":300,"stale_seconds":3600,"generated_at":"2026-05-05T18:32:52.359Z","request_id":"req_example","identity_tier":"anonymous"},"error":{"code":"data_source_response_error","message":"The data source returned an unusable response for this finance data request.","next_action":"retry_or_use_cached_response","request_id":"req_example"}}},"response_too_large":{"summary":"Response too large","value":{"error":{"code":"response_too_large","message":"The finance data response exceeded gfin's configured response-size cap.","next_action":"narrow_request","request_id":"req_example"}}}}}}},"504":{"description":"The data source timed out or could not be reached.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"data_source_unavailable":{"summary":"Data source unavailable","value":{"error":{"code":"data_source_unavailable","message":"The data source could not be reached in time.","next_action":"retry_with_backoff","request_id":"req_example"}}}}}}}}}},"/v1/research":{"get":{"tags":["Research"],"operationId":"getResearch","summary":"Research","description":"Runs a natural-language finance research query and returns an answer-oriented result.\n\nThis route is intentionally more constrained than ordinary market-data routes because it can invoke a scarce upstream inference resource.","parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string"},"description":"Natural-language finance research query. Aliases: query, term."},{"name":"X-Gfin-Contact","in":"header","required":false,"schema":{"type":"string"},"description":"Stable contact identity for higher public request limits, for example an email address or service name."},{"name":"X-Gfin-Key","in":"header","required":false,"schema":{"type":"string"},"description":"API key for higher-volume access. Authorization: Bearer is also supported."}],"responses":{"200":{"description":"Research response.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}},"x-gfin-cache":{"description":"Cache state for this response.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResearchResponse"},"examples":{"success":{"summary":"Research success","value":{"meta":{"provider":"google_finance","route":"research","cache":"kv","ttl_seconds":300,"stale_seconds":3600,"generated_at":"2026-05-05T18:32:52.359Z","request_id":"req_example","identity_tier":"anonymous"},"data":{"resource":"research_answer","query":"Why is AAPL moving today?","answer":"AAPL moved with technology-sector earnings, market sentiment, and company-specific news.","citations":[{"title":"Market update","publisher":"Example Finance","url":"https://example.com/markets"}],"status":"available"}}}}}}},"400":{"description":"Invalid request parameters.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"bad_request":{"summary":"Invalid request","value":{"error":{"code":"bad_request","message":"Research requires q= with a natural-language finance question.","next_action":"fix_request","request_id":"req_example"}}}}}}},"401":{"description":"The supplied API key is invalid.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"invalid_api_key":{"summary":"Invalid API key","value":{"error":{"code":"invalid_api_key","message":"The supplied gfin API key is not valid.","next_action":"fix_auth","request_id":"req_example"}}}}}}},"404":{"description":"Unknown route.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"not_found":{"summary":"Unknown route","value":{"error":{"code":"not_found","message":"Unknown gfin route. Use /v1/routes or /v1/openapi.json to inspect supported routes.","next_action":"inspect_error","request_id":"req_example"}}},"route_not_found":{"summary":"Unknown route","value":{"error":{"code":"route_not_found","message":"This gfin route is not available.","next_action":"choose_supported_route","request_id":"req_example"}}}}}}},"405":{"description":"HTTP method is not allowed for this route.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"method_not_allowed":{"summary":"Method not allowed","value":{"error":{"code":"method_not_allowed","message":"gfin v1 exposes read-only GET routes.","next_action":"inspect_error","request_id":"req_example"}}}}}}},"429":{"description":"Request limit exceeded. Retry-After is included.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","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":{"error":{"code":"rate_limited","message":"Request budget exhausted.","next_action":"retry_after","request_id":"req_example"},"rate_limit":{"scope":"request","tier":"anonymous","reason":"rate_limited","retry_after_seconds":42,"limit":1200,"remaining":0,"reset_at":"2026-05-05T18:33:00.000Z","upgrade":"Send X-Gfin-Contact for higher no-key limits; email sam@gfin.dev for an API key."}}}}}}},"502":{"description":"The data request could not be completed.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"data_source_response_error":{"summary":"Data source response error","value":{"meta":{"provider":"google_finance","route":"research","cache":"kv","ttl_seconds":300,"stale_seconds":3600,"generated_at":"2026-05-05T18:32:52.359Z","request_id":"req_example","identity_tier":"anonymous"},"error":{"code":"data_source_response_error","message":"The data source returned an unusable response for this finance data request.","next_action":"retry_or_use_cached_response","request_id":"req_example"}}},"response_too_large":{"summary":"Response too large","value":{"error":{"code":"response_too_large","message":"The finance data response exceeded gfin's configured response-size cap.","next_action":"narrow_request","request_id":"req_example"}}}}}}},"504":{"description":"The data source timed out or could not be reached.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"data_source_unavailable":{"summary":"Data source unavailable","value":{"error":{"code":"data_source_unavailable","message":"The data source could not be reached in time.","next_action":"retry_with_backoff","request_id":"req_example"}}}}}}}}}},"/v1/markets/summary":{"get":{"tags":["Markets"],"operationId":"getMarketSummary","summary":"Market Summary","description":"Returns broad market summary data and narrative market context.\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":"X-Gfin-Contact","in":"header","required":false,"schema":{"type":"string"},"description":"Stable contact identity for higher public request limits, for example an email address or service name."},{"name":"X-Gfin-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.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}},"x-gfin-cache":{"description":"Cache state for this response.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketSummaryResponse"},"examples":{"success":{"summary":"Market Summary success","value":{"meta":{"provider":"google_finance","route":"market_summary","cache":"kv","ttl_seconds":300,"stale_seconds":3600,"generated_at":"2026-05-05T18:32:52.359Z","request_id":"req_example","identity_tier":"anonymous"},"data":{"resource":"market_summary","themes":[{"title":"Technology shares lead major indexes","summary":"Major U.S. equity indexes rose as investors focused on earnings and lower volatility.","stories":[{"url":"https://example.com/story","title":"Technology shares rise after earnings","publisher":"Example Finance","image_url":null,"published_at":"2026-05-05T18:31:15.000Z","favicon_url":null,"related_instruments":[{"entity_id":"%2Fm%2F07zmbvf","symbol":"AAPL","exchange":"NASDAQ","name":"Apple Inc","currency":"USD","country":"US","timezone":"America/New_York","quote":{"price":198.53,"change":1.24,"change_percent":0.63,"previous_close":197.29,"last_trade_time":"2026-05-05T18:32:00.000Z"},"extended_hours_quote":null}],"snippet":"Large technology shares rose after earnings."}]}]}}}}}}},"400":{"description":"Invalid request parameters.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"bad_request":{"summary":"Invalid request","value":{"error":{"code":"bad_request","message":"Invalid request parameters.","next_action":"fix_request","request_id":"req_example"}}}}}}},"401":{"description":"The supplied API key is invalid.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"invalid_api_key":{"summary":"Invalid API key","value":{"error":{"code":"invalid_api_key","message":"The supplied gfin API key is not valid.","next_action":"fix_auth","request_id":"req_example"}}}}}}},"404":{"description":"Unknown route.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"not_found":{"summary":"Unknown route","value":{"error":{"code":"not_found","message":"Unknown gfin route. Use /v1/routes or /v1/openapi.json to inspect supported routes.","next_action":"inspect_error","request_id":"req_example"}}},"route_not_found":{"summary":"Unknown route","value":{"error":{"code":"route_not_found","message":"This gfin route is not available.","next_action":"choose_supported_route","request_id":"req_example"}}}}}}},"405":{"description":"HTTP method is not allowed for this route.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"method_not_allowed":{"summary":"Method not allowed","value":{"error":{"code":"method_not_allowed","message":"gfin v1 exposes read-only GET routes.","next_action":"inspect_error","request_id":"req_example"}}}}}}},"429":{"description":"Request limit exceeded. Retry-After is included.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","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":{"error":{"code":"rate_limited","message":"Request budget exhausted.","next_action":"retry_after","request_id":"req_example"},"rate_limit":{"scope":"request","tier":"anonymous","reason":"rate_limited","retry_after_seconds":42,"limit":1200,"remaining":0,"reset_at":"2026-05-05T18:33:00.000Z","upgrade":"Send X-Gfin-Contact for higher no-key limits; email sam@gfin.dev for an API key."}}}}}}},"502":{"description":"The data request could not be completed.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"data_source_response_error":{"summary":"Data source response error","value":{"meta":{"provider":"google_finance","route":"market_summary","cache":"kv","ttl_seconds":300,"stale_seconds":3600,"generated_at":"2026-05-05T18:32:52.359Z","request_id":"req_example","identity_tier":"anonymous"},"error":{"code":"data_source_response_error","message":"The data source returned an unusable response for this finance data request.","next_action":"retry_or_use_cached_response","request_id":"req_example"}}},"response_too_large":{"summary":"Response too large","value":{"error":{"code":"response_too_large","message":"The finance data response exceeded gfin's configured response-size cap.","next_action":"narrow_request","request_id":"req_example"}}}}}}},"504":{"description":"The data source timed out or could not be reached.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"data_source_unavailable":{"summary":"Data source unavailable","value":{"error":{"code":"data_source_unavailable","message":"The data source could not be reached in time.","next_action":"retry_with_backoff","request_id":"req_example"}}}}}}}}}},"/v1/markets/movers":{"get":{"tags":["Markets"],"operationId":"getMarketMovers","summary":"Market Movers","description":"Returns notable instruments and market-discovery groups.\n\nUse this for mover lists, discovery modules, market overview pages, and agents looking for securities worth further inspection.","parameters":[{"name":"X-Gfin-Contact","in":"header","required":false,"schema":{"type":"string"},"description":"Stable contact identity for higher public request limits, for example an email address or service name."},{"name":"X-Gfin-Key","in":"header","required":false,"schema":{"type":"string"},"description":"API key for higher-volume access. Authorization: Bearer is also supported."}],"responses":{"200":{"description":"Market Movers response.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}},"x-gfin-cache":{"description":"Cache state for this response.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketMoversResponse"},"examples":{"success":{"summary":"Market Movers success","value":{"meta":{"provider":"google_finance","route":"market_movers","cache":"kv","ttl_seconds":300,"stale_seconds":3600,"generated_at":"2026-05-05T18:32:52.359Z","request_id":"req_example","identity_tier":"anonymous"},"data":{"resource":"market_movers","instruments":[{"entity_id":"%2Fm%2F07zmbvf","symbol":"AAPL","exchange":"NASDAQ","name":"Apple Inc","currency":"USD","country":"US","timezone":"America/New_York","quote":{"price":198.53,"change":1.24,"change_percent":0.63,"previous_close":197.29,"last_trade_time":"2026-05-05T18:32:00.000Z"},"extended_hours_quote":null}]}}}}}}},"400":{"description":"Invalid request parameters.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"bad_request":{"summary":"Invalid request","value":{"error":{"code":"bad_request","message":"Invalid request parameters.","next_action":"fix_request","request_id":"req_example"}}}}}}},"401":{"description":"The supplied API key is invalid.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"invalid_api_key":{"summary":"Invalid API key","value":{"error":{"code":"invalid_api_key","message":"The supplied gfin API key is not valid.","next_action":"fix_auth","request_id":"req_example"}}}}}}},"404":{"description":"Unknown route.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"not_found":{"summary":"Unknown route","value":{"error":{"code":"not_found","message":"Unknown gfin route. Use /v1/routes or /v1/openapi.json to inspect supported routes.","next_action":"inspect_error","request_id":"req_example"}}},"route_not_found":{"summary":"Unknown route","value":{"error":{"code":"route_not_found","message":"This gfin route is not available.","next_action":"choose_supported_route","request_id":"req_example"}}}}}}},"405":{"description":"HTTP method is not allowed for this route.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"method_not_allowed":{"summary":"Method not allowed","value":{"error":{"code":"method_not_allowed","message":"gfin v1 exposes read-only GET routes.","next_action":"inspect_error","request_id":"req_example"}}}}}}},"429":{"description":"Request limit exceeded. Retry-After is included.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","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":{"error":{"code":"rate_limited","message":"Request budget exhausted.","next_action":"retry_after","request_id":"req_example"},"rate_limit":{"scope":"request","tier":"anonymous","reason":"rate_limited","retry_after_seconds":42,"limit":1200,"remaining":0,"reset_at":"2026-05-05T18:33:00.000Z","upgrade":"Send X-Gfin-Contact for higher no-key limits; email sam@gfin.dev for an API key."}}}}}}},"502":{"description":"The data request could not be completed.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"data_source_response_error":{"summary":"Data source response error","value":{"meta":{"provider":"google_finance","route":"market_movers","cache":"kv","ttl_seconds":300,"stale_seconds":3600,"generated_at":"2026-05-05T18:32:52.359Z","request_id":"req_example","identity_tier":"anonymous"},"error":{"code":"data_source_response_error","message":"The data source returned an unusable response for this finance data request.","next_action":"retry_or_use_cached_response","request_id":"req_example"}}},"response_too_large":{"summary":"Response too large","value":{"error":{"code":"response_too_large","message":"The finance data response exceeded gfin's configured response-size cap.","next_action":"narrow_request","request_id":"req_example"}}}}}}},"504":{"description":"The data source timed out or could not be reached.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"data_source_unavailable":{"summary":"Data source unavailable","value":{"error":{"code":"data_source_unavailable","message":"The data source could not be reached in time.","next_action":"retry_with_backoff","request_id":"req_example"}}}}}}}}}},"/v1/markets/events":{"get":{"tags":["Markets"],"operationId":"getMarketEvents","summary":"Market Events","description":"Returns finance event data when available.\n\nUse this for event timelines, market calendars, earnings context, and agents that need date-based finance context.","parameters":[{"name":"X-Gfin-Contact","in":"header","required":false,"schema":{"type":"string"},"description":"Stable contact identity for higher public request limits, for example an email address or service name."},{"name":"X-Gfin-Key","in":"header","required":false,"schema":{"type":"string"},"description":"API key for higher-volume access. Authorization: Bearer is also supported."}],"responses":{"200":{"description":"Market Events response.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}},"x-gfin-cache":{"description":"Cache state for this response.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketEventsResponse"},"examples":{"success":{"summary":"Market Events success","value":{"meta":{"provider":"google_finance","route":"market_events","cache":"kv","ttl_seconds":300,"stale_seconds":3600,"generated_at":"2026-05-05T18:32:52.359Z","request_id":"req_example","identity_tier":"anonymous"},"data":{"resource":"market_events","records":[{"type":"earnings","symbol":"AAPL","name":"Apple Inc","date":"2026-05-05"}]}}}}}}},"400":{"description":"Invalid request parameters.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"bad_request":{"summary":"Invalid request","value":{"error":{"code":"bad_request","message":"Invalid request parameters.","next_action":"fix_request","request_id":"req_example"}}}}}}},"401":{"description":"The supplied API key is invalid.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"invalid_api_key":{"summary":"Invalid API key","value":{"error":{"code":"invalid_api_key","message":"The supplied gfin API key is not valid.","next_action":"fix_auth","request_id":"req_example"}}}}}}},"404":{"description":"Unknown route.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"not_found":{"summary":"Unknown route","value":{"error":{"code":"not_found","message":"Unknown gfin route. Use /v1/routes or /v1/openapi.json to inspect supported routes.","next_action":"inspect_error","request_id":"req_example"}}},"route_not_found":{"summary":"Unknown route","value":{"error":{"code":"route_not_found","message":"This gfin route is not available.","next_action":"choose_supported_route","request_id":"req_example"}}}}}}},"405":{"description":"HTTP method is not allowed for this route.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"method_not_allowed":{"summary":"Method not allowed","value":{"error":{"code":"method_not_allowed","message":"gfin v1 exposes read-only GET routes.","next_action":"inspect_error","request_id":"req_example"}}}}}}},"429":{"description":"Request limit exceeded. Retry-After is included.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","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":{"error":{"code":"rate_limited","message":"Request budget exhausted.","next_action":"retry_after","request_id":"req_example"},"rate_limit":{"scope":"request","tier":"anonymous","reason":"rate_limited","retry_after_seconds":42,"limit":1200,"remaining":0,"reset_at":"2026-05-05T18:33:00.000Z","upgrade":"Send X-Gfin-Contact for higher no-key limits; email sam@gfin.dev for an API key."}}}}}}},"502":{"description":"The data request could not be completed.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"data_source_response_error":{"summary":"Data source response error","value":{"meta":{"provider":"google_finance","route":"market_events","cache":"kv","ttl_seconds":300,"stale_seconds":3600,"generated_at":"2026-05-05T18:32:52.359Z","request_id":"req_example","identity_tier":"anonymous"},"error":{"code":"data_source_response_error","message":"The data source returned an unusable response for this finance data request.","next_action":"retry_or_use_cached_response","request_id":"req_example"}}},"response_too_large":{"summary":"Response too large","value":{"error":{"code":"response_too_large","message":"The finance data response exceeded gfin's configured response-size cap.","next_action":"narrow_request","request_id":"req_example"}}}}}}},"504":{"description":"The data source timed out or could not be reached.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"data_source_unavailable":{"summary":"Data source unavailable","value":{"error":{"code":"data_source_unavailable","message":"The data source could not be reached in time.","next_action":"retry_with_backoff","request_id":"req_example"}}}}}}}}}},"/v1/news":{"get":{"tags":["News"],"operationId":"getNews","summary":"News","description":"Returns a finance news feed.\n\nUse this for market-news modules, ticker-adjacent news, research workflows, and agents that need recent finance headlines.","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":50,"default":20},"description":"Maximum number of news items or stories to request. Alias: count."},{"name":"X-Gfin-Contact","in":"header","required":false,"schema":{"type":"string"},"description":"Stable contact identity for higher public request limits, for example an email address or service name."},{"name":"X-Gfin-Key","in":"header","required":false,"schema":{"type":"string"},"description":"API key for higher-volume access. Authorization: Bearer is also supported."}],"responses":{"200":{"description":"News response.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}},"x-gfin-cache":{"description":"Cache state for this response.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NewsResponse"},"examples":{"success":{"summary":"News success","value":{"meta":{"provider":"google_finance","route":"news","cache":"kv","ttl_seconds":300,"stale_seconds":3600,"generated_at":"2026-05-05T18:32:52.359Z","request_id":"req_example","identity_tier":"anonymous"},"data":{"resource":"news","stories":[{"url":"https://example.com/story","title":"Technology shares rise after earnings","publisher":"Example Finance","image_url":null,"published_at":"2026-05-05T18:31:15.000Z","favicon_url":null,"related_instruments":[{"entity_id":"%2Fm%2F07zmbvf","symbol":"AAPL","exchange":"NASDAQ","name":"Apple Inc","currency":"USD","country":"US","timezone":"America/New_York","quote":{"price":198.53,"change":1.24,"change_percent":0.63,"previous_close":197.29,"last_trade_time":"2026-05-05T18:32:00.000Z"},"extended_hours_quote":null}],"snippet":"Large technology shares rose after earnings."}]}}}}}}},"400":{"description":"Invalid request parameters.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"bad_request":{"summary":"Invalid request","value":{"error":{"code":"bad_request","message":"Invalid request parameters.","next_action":"fix_request","request_id":"req_example"}}}}}}},"401":{"description":"The supplied API key is invalid.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"invalid_api_key":{"summary":"Invalid API key","value":{"error":{"code":"invalid_api_key","message":"The supplied gfin API key is not valid.","next_action":"fix_auth","request_id":"req_example"}}}}}}},"404":{"description":"Unknown route.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"not_found":{"summary":"Unknown route","value":{"error":{"code":"not_found","message":"Unknown gfin route. Use /v1/routes or /v1/openapi.json to inspect supported routes.","next_action":"inspect_error","request_id":"req_example"}}},"route_not_found":{"summary":"Unknown route","value":{"error":{"code":"route_not_found","message":"This gfin route is not available.","next_action":"choose_supported_route","request_id":"req_example"}}}}}}},"405":{"description":"HTTP method is not allowed for this route.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"method_not_allowed":{"summary":"Method not allowed","value":{"error":{"code":"method_not_allowed","message":"gfin v1 exposes read-only GET routes.","next_action":"inspect_error","request_id":"req_example"}}}}}}},"429":{"description":"Request limit exceeded. Retry-After is included.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","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":{"error":{"code":"rate_limited","message":"Request budget exhausted.","next_action":"retry_after","request_id":"req_example"},"rate_limit":{"scope":"request","tier":"anonymous","reason":"rate_limited","retry_after_seconds":42,"limit":1200,"remaining":0,"reset_at":"2026-05-05T18:33:00.000Z","upgrade":"Send X-Gfin-Contact for higher no-key limits; email sam@gfin.dev for an API key."}}}}}}},"502":{"description":"The data request could not be completed.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"data_source_response_error":{"summary":"Data source response error","value":{"meta":{"provider":"google_finance","route":"news","cache":"kv","ttl_seconds":300,"stale_seconds":3600,"generated_at":"2026-05-05T18:32:52.359Z","request_id":"req_example","identity_tier":"anonymous"},"error":{"code":"data_source_response_error","message":"The data source returned an unusable response for this finance data request.","next_action":"retry_or_use_cached_response","request_id":"req_example"}}},"response_too_large":{"summary":"Response too large","value":{"error":{"code":"response_too_large","message":"The finance data response exceeded gfin's configured response-size cap.","next_action":"narrow_request","request_id":"req_example"}}}}}}},"504":{"description":"The data source timed out or could not be reached.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"data_source_unavailable":{"summary":"Data source unavailable","value":{"error":{"code":"data_source_unavailable","message":"The data source could not be reached in time.","next_action":"retry_with_backoff","request_id":"req_example"}}}}}}}}}},"/v1/news/collections":{"get":{"tags":["News"],"operationId":"getNewsCollections","summary":"News Collections","description":"Returns finance story collections.\n\nUse this for story feeds, news cards, market-research context, and agents that need a compact set of current finance stories.","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":50,"default":8},"description":"Maximum number of news items or stories to request. Alias: count."},{"name":"X-Gfin-Contact","in":"header","required":false,"schema":{"type":"string"},"description":"Stable contact identity for higher public request limits, for example an email address or service name."},{"name":"X-Gfin-Key","in":"header","required":false,"schema":{"type":"string"},"description":"API key for higher-volume access. Authorization: Bearer is also supported."}],"responses":{"200":{"description":"News Collections response.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}},"x-gfin-cache":{"description":"Cache state for this response.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NewsCollectionsResponse"},"examples":{"success":{"summary":"News Collections success","value":{"meta":{"provider":"google_finance","route":"news_collections","cache":"kv","ttl_seconds":300,"stale_seconds":3600,"generated_at":"2026-05-05T18:32:52.359Z","request_id":"req_example","identity_tier":"anonymous"},"data":{"resource":"story_collections","collections":[{"title":"Top market stories","summary":null,"stories":[{"url":"https://example.com/story","title":"Technology shares rise after earnings","publisher":"Example Finance","image_url":null,"published_at":"2026-05-05T18:31:15.000Z","favicon_url":null,"related_instruments":[{"entity_id":"%2Fm%2F07zmbvf","symbol":"AAPL","exchange":"NASDAQ","name":"Apple Inc","currency":"USD","country":"US","timezone":"America/New_York","quote":{"price":198.53,"change":1.24,"change_percent":0.63,"previous_close":197.29,"last_trade_time":"2026-05-05T18:32:00.000Z"},"extended_hours_quote":null}],"snippet":"Large technology shares rose after earnings."}]}]}}}}}}},"400":{"description":"Invalid request parameters.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"bad_request":{"summary":"Invalid request","value":{"error":{"code":"bad_request","message":"Invalid request parameters.","next_action":"fix_request","request_id":"req_example"}}}}}}},"401":{"description":"The supplied API key is invalid.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"invalid_api_key":{"summary":"Invalid API key","value":{"error":{"code":"invalid_api_key","message":"The supplied gfin API key is not valid.","next_action":"fix_auth","request_id":"req_example"}}}}}}},"404":{"description":"Unknown route.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"not_found":{"summary":"Unknown route","value":{"error":{"code":"not_found","message":"Unknown gfin route. Use /v1/routes or /v1/openapi.json to inspect supported routes.","next_action":"inspect_error","request_id":"req_example"}}},"route_not_found":{"summary":"Unknown route","value":{"error":{"code":"route_not_found","message":"This gfin route is not available.","next_action":"choose_supported_route","request_id":"req_example"}}}}}}},"405":{"description":"HTTP method is not allowed for this route.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"method_not_allowed":{"summary":"Method not allowed","value":{"error":{"code":"method_not_allowed","message":"gfin v1 exposes read-only GET routes.","next_action":"inspect_error","request_id":"req_example"}}}}}}},"429":{"description":"Request limit exceeded. Retry-After is included.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","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":{"error":{"code":"rate_limited","message":"Request budget exhausted.","next_action":"retry_after","request_id":"req_example"},"rate_limit":{"scope":"request","tier":"anonymous","reason":"rate_limited","retry_after_seconds":42,"limit":1200,"remaining":0,"reset_at":"2026-05-05T18:33:00.000Z","upgrade":"Send X-Gfin-Contact for higher no-key limits; email sam@gfin.dev for an API key."}}}}}}},"502":{"description":"The data request could not be completed.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"data_source_response_error":{"summary":"Data source response error","value":{"meta":{"provider":"google_finance","route":"news_collections","cache":"kv","ttl_seconds":300,"stale_seconds":3600,"generated_at":"2026-05-05T18:32:52.359Z","request_id":"req_example","identity_tier":"anonymous"},"error":{"code":"data_source_response_error","message":"The data source returned an unusable response for this finance data request.","next_action":"retry_or_use_cached_response","request_id":"req_example"}}},"response_too_large":{"summary":"Response too large","value":{"error":{"code":"response_too_large","message":"The finance data response exceeded gfin's configured response-size cap.","next_action":"narrow_request","request_id":"req_example"}}}}}}},"504":{"description":"The data source timed out or could not be reached.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"data_source_unavailable":{"summary":"Data source unavailable","value":{"error":{"code":"data_source_unavailable","message":"The data source could not be reached in time.","next_action":"retry_with_backoff","request_id":"req_example"}}}}}}}}}},"/v1/markets/highlights":{"get":{"tags":["Markets"],"operationId":"getMarketHighlights","summary":"Market Highlights","description":"Returns featured market highlights and high-level market context.\n\nUse this for overview screens and agents that need a broad current-market entry point.","parameters":[{"name":"X-Gfin-Contact","in":"header","required":false,"schema":{"type":"string"},"description":"Stable contact identity for higher public request limits, for example an email address or service name."},{"name":"X-Gfin-Key","in":"header","required":false,"schema":{"type":"string"},"description":"API key for higher-volume access. Authorization: Bearer is also supported."}],"responses":{"200":{"description":"Market Highlights response.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}},"x-gfin-cache":{"description":"Cache state for this response.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketHighlightsResponse"},"examples":{"success":{"summary":"Market Highlights success","value":{"meta":{"provider":"google_finance","route":"market_highlights","cache":"kv","ttl_seconds":300,"stale_seconds":3600,"generated_at":"2026-05-05T18:32:52.359Z","request_id":"req_example","identity_tier":"anonymous"},"data":{"resource":"market_highlights","instruments":[{"entity_id":"%2Fm%2F07zmbvf","symbol":"AAPL","exchange":"NASDAQ","name":"Apple Inc","currency":"USD","country":"US","timezone":"America/New_York","quote":{"price":198.53,"change":1.24,"change_percent":0.63,"previous_close":197.29,"last_trade_time":"2026-05-05T18:32:00.000Z"},"extended_hours_quote":null}]}}}}}}},"400":{"description":"Invalid request parameters.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"bad_request":{"summary":"Invalid request","value":{"error":{"code":"bad_request","message":"Invalid request parameters.","next_action":"fix_request","request_id":"req_example"}}}}}}},"401":{"description":"The supplied API key is invalid.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"invalid_api_key":{"summary":"Invalid API key","value":{"error":{"code":"invalid_api_key","message":"The supplied gfin API key is not valid.","next_action":"fix_auth","request_id":"req_example"}}}}}}},"404":{"description":"Unknown route.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"not_found":{"summary":"Unknown route","value":{"error":{"code":"not_found","message":"Unknown gfin route. Use /v1/routes or /v1/openapi.json to inspect supported routes.","next_action":"inspect_error","request_id":"req_example"}}},"route_not_found":{"summary":"Unknown route","value":{"error":{"code":"route_not_found","message":"This gfin route is not available.","next_action":"choose_supported_route","request_id":"req_example"}}}}}}},"405":{"description":"HTTP method is not allowed for this route.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"method_not_allowed":{"summary":"Method not allowed","value":{"error":{"code":"method_not_allowed","message":"gfin v1 exposes read-only GET routes.","next_action":"inspect_error","request_id":"req_example"}}}}}}},"429":{"description":"Request limit exceeded. Retry-After is included.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","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":{"error":{"code":"rate_limited","message":"Request budget exhausted.","next_action":"retry_after","request_id":"req_example"},"rate_limit":{"scope":"request","tier":"anonymous","reason":"rate_limited","retry_after_seconds":42,"limit":1200,"remaining":0,"reset_at":"2026-05-05T18:33:00.000Z","upgrade":"Send X-Gfin-Contact for higher no-key limits; email sam@gfin.dev for an API key."}}}}}}},"502":{"description":"The data request could not be completed.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"data_source_response_error":{"summary":"Data source response error","value":{"meta":{"provider":"google_finance","route":"market_highlights","cache":"kv","ttl_seconds":300,"stale_seconds":3600,"generated_at":"2026-05-05T18:32:52.359Z","request_id":"req_example","identity_tier":"anonymous"},"error":{"code":"data_source_response_error","message":"The data source returned an unusable response for this finance data request.","next_action":"retry_or_use_cached_response","request_id":"req_example"}}},"response_too_large":{"summary":"Response too large","value":{"error":{"code":"response_too_large","message":"The finance data response exceeded gfin's configured response-size cap.","next_action":"narrow_request","request_id":"req_example"}}}}}}},"504":{"description":"The data source timed out or could not be reached.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"data_source_unavailable":{"summary":"Data source unavailable","value":{"error":{"code":"data_source_unavailable","message":"The data source could not be reached in time.","next_action":"retry_with_backoff","request_id":"req_example"}}}}}}}}}},"/v1/quotes/{symbol}":{"get":{"tags":["Quotes"],"operationId":"getQuote","summary":"Quote","description":"Returns a compact quote summary for one symbol.\n\nUse this for watchlists, symbol snapshots, portfolio rows, and agents that need current price, change, currency, exchange, and market-session context when available.","parameters":[{"name":"symbol","in":"path","required":true,"schema":{"type":"string"},"description":"Ticker or finance symbol path segment, for example AAPL."},{"name":"exchange","in":"query","required":false,"schema":{"type":"string","default":"NASDAQ"},"description":"Exchange hint used with the symbol when the ticker is ambiguous, for example NASDAQ, NYSE, or INDEXNASDAQ."},{"name":"X-Gfin-Contact","in":"header","required":false,"schema":{"type":"string"},"description":"Stable contact identity for higher public request limits, for example an email address or service name."},{"name":"X-Gfin-Key","in":"header","required":false,"schema":{"type":"string"},"description":"API key for higher-volume access. Authorization: Bearer is also supported."}],"responses":{"200":{"description":"Quote response.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}},"x-gfin-cache":{"description":"Cache state for this response.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/QuoteResponse"},"examples":{"success":{"summary":"Quote success","value":{"meta":{"provider":"google_finance","route":"quote","cache":"kv","ttl_seconds":300,"stale_seconds":3600,"generated_at":"2026-05-05T18:32:52.359Z","request_id":"req_example","identity_tier":"anonymous"},"data":{"resource":"quote","instrument":{"entity_id":"%2Fm%2F07zmbvf","symbol":"AAPL","exchange":"NASDAQ","name":"Apple Inc","currency":"USD","country":"US","timezone":"America/New_York","quote":{"price":198.53,"change":1.24,"change_percent":0.63,"previous_close":197.29,"last_trade_time":"2026-05-05T18:32:00.000Z"},"extended_hours_quote":null},"instruments":[{"entity_id":"%2Fm%2F07zmbvf","symbol":"AAPL","exchange":"NASDAQ","name":"Apple Inc","currency":"USD","country":"US","timezone":"America/New_York","quote":{"price":198.53,"change":1.24,"change_percent":0.63,"previous_close":197.29,"last_trade_time":"2026-05-05T18:32:00.000Z"},"extended_hours_quote":null}]}}}}}}},"400":{"description":"Invalid request parameters.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"bad_request":{"summary":"Invalid request","value":{"error":{"code":"bad_request","message":"Symbol routes require a symbol path segment, for example /v1/quotes/AAPL.","next_action":"fix_request","request_id":"req_example"}}}}}}},"401":{"description":"The supplied API key is invalid.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"invalid_api_key":{"summary":"Invalid API key","value":{"error":{"code":"invalid_api_key","message":"The supplied gfin API key is not valid.","next_action":"fix_auth","request_id":"req_example"}}}}}}},"404":{"description":"Unknown route.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"not_found":{"summary":"Unknown route","value":{"error":{"code":"not_found","message":"Unknown gfin route. Use /v1/routes or /v1/openapi.json to inspect supported routes.","next_action":"inspect_error","request_id":"req_example"}}},"route_not_found":{"summary":"Unknown route","value":{"error":{"code":"route_not_found","message":"This gfin route is not available.","next_action":"choose_supported_route","request_id":"req_example"}}}}}}},"405":{"description":"HTTP method is not allowed for this route.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"method_not_allowed":{"summary":"Method not allowed","value":{"error":{"code":"method_not_allowed","message":"gfin v1 exposes read-only GET routes.","next_action":"inspect_error","request_id":"req_example"}}}}}}},"429":{"description":"Request limit exceeded. Retry-After is included.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","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":{"error":{"code":"rate_limited","message":"Request budget exhausted.","next_action":"retry_after","request_id":"req_example"},"rate_limit":{"scope":"request","tier":"anonymous","reason":"rate_limited","retry_after_seconds":42,"limit":1200,"remaining":0,"reset_at":"2026-05-05T18:33:00.000Z","upgrade":"Send X-Gfin-Contact for higher no-key limits; email sam@gfin.dev for an API key."}}}}}}},"502":{"description":"The data request could not be completed.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"data_source_response_error":{"summary":"Data source response error","value":{"meta":{"provider":"google_finance","route":"quote","cache":"kv","ttl_seconds":300,"stale_seconds":3600,"generated_at":"2026-05-05T18:32:52.359Z","request_id":"req_example","identity_tier":"anonymous"},"error":{"code":"data_source_response_error","message":"The data source returned an unusable response for this finance data request.","next_action":"retry_or_use_cached_response","request_id":"req_example"}}},"response_too_large":{"summary":"Response too large","value":{"error":{"code":"response_too_large","message":"The finance data response exceeded gfin's configured response-size cap.","next_action":"narrow_request","request_id":"req_example"}}}}}}},"504":{"description":"The data source timed out or could not be reached.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"data_source_unavailable":{"summary":"Data source unavailable","value":{"error":{"code":"data_source_unavailable","message":"The data source could not be reached in time.","next_action":"retry_with_backoff","request_id":"req_example"}}}}}}}}}},"/v1/quotes/{symbol}/details":{"get":{"tags":["Quotes"],"operationId":"getQuoteDetails","summary":"Quote Details","description":"Returns expanded quote details for one symbol.\n\nUse this for quote pages, instrument drilldowns, richer dashboards, and agents that need more detail than the compact quote summary.","parameters":[{"name":"symbol","in":"path","required":true,"schema":{"type":"string"},"description":"Ticker or finance symbol path segment, for example AAPL."},{"name":"exchange","in":"query","required":false,"schema":{"type":"string","default":"NASDAQ"},"description":"Exchange hint used with the symbol when the ticker is ambiguous, for example NASDAQ, NYSE, or INDEXNASDAQ."},{"name":"X-Gfin-Contact","in":"header","required":false,"schema":{"type":"string"},"description":"Stable contact identity for higher public request limits, for example an email address or service name."},{"name":"X-Gfin-Key","in":"header","required":false,"schema":{"type":"string"},"description":"API key for higher-volume access. Authorization: Bearer is also supported."}],"responses":{"200":{"description":"Quote Details response.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}},"x-gfin-cache":{"description":"Cache state for this response.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/QuoteDetailsResponse"},"examples":{"success":{"summary":"Quote Details success","value":{"meta":{"provider":"google_finance","route":"quote_details","cache":"kv","ttl_seconds":300,"stale_seconds":3600,"generated_at":"2026-05-05T18:32:52.359Z","request_id":"req_example","identity_tier":"anonymous"},"data":{"resource":"quote_details","instrument":{"entity_id":"%2Fm%2F07zmbvf","symbol":"AAPL","exchange":"NASDAQ","name":"Apple Inc","currency":"USD","country":"US","timezone":"America/New_York","quote":{"price":198.53,"change":1.24,"change_percent":0.63,"previous_close":197.29,"last_trade_time":"2026-05-05T18:32:00.000Z"},"extended_hours_quote":null},"instruments":[{"entity_id":"%2Fm%2F07zmbvf","symbol":"AAPL","exchange":"NASDAQ","name":"Apple Inc","currency":"USD","country":"US","timezone":"America/New_York","quote":{"price":198.53,"change":1.24,"change_percent":0.63,"previous_close":197.29,"last_trade_time":"2026-05-05T18:32:00.000Z"},"extended_hours_quote":null}]}}}}}}},"400":{"description":"Invalid request parameters.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"bad_request":{"summary":"Invalid request","value":{"error":{"code":"bad_request","message":"Symbol routes require a symbol path segment, for example /v1/quotes/AAPL.","next_action":"fix_request","request_id":"req_example"}}}}}}},"401":{"description":"The supplied API key is invalid.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"invalid_api_key":{"summary":"Invalid API key","value":{"error":{"code":"invalid_api_key","message":"The supplied gfin API key is not valid.","next_action":"fix_auth","request_id":"req_example"}}}}}}},"404":{"description":"Unknown route.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"not_found":{"summary":"Unknown route","value":{"error":{"code":"not_found","message":"Unknown gfin route. Use /v1/routes or /v1/openapi.json to inspect supported routes.","next_action":"inspect_error","request_id":"req_example"}}},"route_not_found":{"summary":"Unknown route","value":{"error":{"code":"route_not_found","message":"This gfin route is not available.","next_action":"choose_supported_route","request_id":"req_example"}}}}}}},"405":{"description":"HTTP method is not allowed for this route.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"method_not_allowed":{"summary":"Method not allowed","value":{"error":{"code":"method_not_allowed","message":"gfin v1 exposes read-only GET routes.","next_action":"inspect_error","request_id":"req_example"}}}}}}},"429":{"description":"Request limit exceeded. Retry-After is included.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","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":{"error":{"code":"rate_limited","message":"Request budget exhausted.","next_action":"retry_after","request_id":"req_example"},"rate_limit":{"scope":"request","tier":"anonymous","reason":"rate_limited","retry_after_seconds":42,"limit":1200,"remaining":0,"reset_at":"2026-05-05T18:33:00.000Z","upgrade":"Send X-Gfin-Contact for higher no-key limits; email sam@gfin.dev for an API key."}}}}}}},"502":{"description":"The data request could not be completed.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"data_source_response_error":{"summary":"Data source response error","value":{"meta":{"provider":"google_finance","route":"quote_details","cache":"kv","ttl_seconds":300,"stale_seconds":3600,"generated_at":"2026-05-05T18:32:52.359Z","request_id":"req_example","identity_tier":"anonymous"},"error":{"code":"data_source_response_error","message":"The data source returned an unusable response for this finance data request.","next_action":"retry_or_use_cached_response","request_id":"req_example"}}},"response_too_large":{"summary":"Response too large","value":{"error":{"code":"response_too_large","message":"The finance data response exceeded gfin's configured response-size cap.","next_action":"narrow_request","request_id":"req_example"}}}}}}},"504":{"description":"The data source timed out or could not be reached.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"data_source_unavailable":{"summary":"Data source unavailable","value":{"error":{"code":"data_source_unavailable","message":"The data source could not be reached in time.","next_action":"retry_with_backoff","request_id":"req_example"}}}}}}}}}},"/v1/quotes/{symbol}/profile":{"get":{"tags":["Quotes"],"operationId":"getQuoteProfile","summary":"Instrument Profile","description":"Returns entity-level detail for one quote symbol.\n\nUse this for company or instrument profile sections and workflows that need metadata around a finance entity.","parameters":[{"name":"symbol","in":"path","required":true,"schema":{"type":"string"},"description":"Ticker or finance symbol path segment, for example AAPL."},{"name":"exchange","in":"query","required":false,"schema":{"type":"string","default":"NASDAQ"},"description":"Exchange hint used with the symbol when the ticker is ambiguous, for example NASDAQ, NYSE, or INDEXNASDAQ."},{"name":"X-Gfin-Contact","in":"header","required":false,"schema":{"type":"string"},"description":"Stable contact identity for higher public request limits, for example an email address or service name."},{"name":"X-Gfin-Key","in":"header","required":false,"schema":{"type":"string"},"description":"API key for higher-volume access. Authorization: Bearer is also supported."}],"responses":{"200":{"description":"Instrument Profile response.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}},"x-gfin-cache":{"description":"Cache state for this response.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/QuoteProfileResponse"},"examples":{"success":{"summary":"Quote Profile success","value":{"meta":{"provider":"google_finance","route":"quote_profile","cache":"kv","ttl_seconds":300,"stale_seconds":3600,"generated_at":"2026-05-05T18:32:52.359Z","request_id":"req_example","identity_tier":"anonymous"},"data":{"resource":"quote_profile","instrument":{"entity_id":"%2Fm%2F07zmbvf","symbol":"AAPL","exchange":"NASDAQ","name":"Apple Inc","currency":"USD","country":"US","timezone":"America/New_York","quote":{"price":198.53,"change":1.24,"change_percent":0.63,"previous_close":197.29,"last_trade_time":"2026-05-05T18:32:00.000Z"},"extended_hours_quote":null},"instruments":[{"entity_id":"%2Fm%2F07zmbvf","symbol":"AAPL","exchange":"NASDAQ","name":"Apple Inc","currency":"USD","country":"US","timezone":"America/New_York","quote":{"price":198.53,"change":1.24,"change_percent":0.63,"previous_close":197.29,"last_trade_time":"2026-05-05T18:32:00.000Z"},"extended_hours_quote":null}]}}}}}}},"400":{"description":"Invalid request parameters.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"bad_request":{"summary":"Invalid request","value":{"error":{"code":"bad_request","message":"Symbol routes require a symbol path segment, for example /v1/quotes/AAPL.","next_action":"fix_request","request_id":"req_example"}}}}}}},"401":{"description":"The supplied API key is invalid.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"invalid_api_key":{"summary":"Invalid API key","value":{"error":{"code":"invalid_api_key","message":"The supplied gfin API key is not valid.","next_action":"fix_auth","request_id":"req_example"}}}}}}},"404":{"description":"Unknown route.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"not_found":{"summary":"Unknown route","value":{"error":{"code":"not_found","message":"Unknown gfin route. Use /v1/routes or /v1/openapi.json to inspect supported routes.","next_action":"inspect_error","request_id":"req_example"}}},"route_not_found":{"summary":"Unknown route","value":{"error":{"code":"route_not_found","message":"This gfin route is not available.","next_action":"choose_supported_route","request_id":"req_example"}}}}}}},"405":{"description":"HTTP method is not allowed for this route.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"method_not_allowed":{"summary":"Method not allowed","value":{"error":{"code":"method_not_allowed","message":"gfin v1 exposes read-only GET routes.","next_action":"inspect_error","request_id":"req_example"}}}}}}},"429":{"description":"Request limit exceeded. Retry-After is included.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","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":{"error":{"code":"rate_limited","message":"Request budget exhausted.","next_action":"retry_after","request_id":"req_example"},"rate_limit":{"scope":"request","tier":"anonymous","reason":"rate_limited","retry_after_seconds":42,"limit":1200,"remaining":0,"reset_at":"2026-05-05T18:33:00.000Z","upgrade":"Send X-Gfin-Contact for higher no-key limits; email sam@gfin.dev for an API key."}}}}}}},"502":{"description":"The data request could not be completed.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"data_source_response_error":{"summary":"Data source response error","value":{"meta":{"provider":"google_finance","route":"quote_profile","cache":"kv","ttl_seconds":300,"stale_seconds":3600,"generated_at":"2026-05-05T18:32:52.359Z","request_id":"req_example","identity_tier":"anonymous"},"error":{"code":"data_source_response_error","message":"The data source returned an unusable response for this finance data request.","next_action":"retry_or_use_cached_response","request_id":"req_example"}}},"response_too_large":{"summary":"Response too large","value":{"error":{"code":"response_too_large","message":"The finance data response exceeded gfin's configured response-size cap.","next_action":"narrow_request","request_id":"req_example"}}}}}}},"504":{"description":"The data source timed out or could not be reached.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"data_source_unavailable":{"summary":"Data source unavailable","value":{"error":{"code":"data_source_unavailable","message":"The data source could not be reached in time.","next_action":"retry_with_backoff","request_id":"req_example"}}}}}}}}}},"/v1/prices/{symbol}/history":{"get":{"tags":["Quotes"],"operationId":"getPricesHistory","summary":"Price History","description":"Returns historical pricing data for one symbol.\n\nUse this for charts, trend views, return calculations, and agents that need recent or historical price movement context.","parameters":[{"name":"symbol","in":"path","required":true,"schema":{"type":"string"},"description":"Ticker or finance symbol path segment, for example AAPL."},{"name":"exchange","in":"query","required":false,"schema":{"type":"string","default":"NASDAQ"},"description":"Exchange hint used with the symbol when the ticker is ambiguous, for example NASDAQ, NYSE, or INDEXNASDAQ."},{"name":"X-Gfin-Contact","in":"header","required":false,"schema":{"type":"string"},"description":"Stable contact identity for higher public request limits, for example an email address or service name."},{"name":"X-Gfin-Key","in":"header","required":false,"schema":{"type":"string"},"description":"API key for higher-volume access. Authorization: Bearer is also supported."}],"responses":{"200":{"description":"Price History response.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}},"x-gfin-cache":{"description":"Cache state for this response.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PricesHistoryResponse"},"examples":{"success":{"summary":"Prices History success","value":{"meta":{"provider":"google_finance","route":"prices_history","cache":"kv","ttl_seconds":300,"stale_seconds":3600,"generated_at":"2026-05-05T18:32:52.359Z","request_id":"req_example","identity_tier":"anonymous"},"data":{"resource":"prices_history","instrument":{"symbol":"AAPL","exchange":"NASDAQ","entity_id":"%2Fm%2F07zmbvf","name":"Apple Inc"},"currency":"USD","timezone_offset_seconds":-14400,"previous_close":197.29,"prices":[{"timestamp":"2026-05-05","price":198.53,"change":1.24,"change_percent":0.63,"volume":51234567}]}}}}}}},"400":{"description":"Invalid request parameters.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"bad_request":{"summary":"Invalid request","value":{"error":{"code":"bad_request","message":"Symbol routes require a symbol path segment, for example /v1/quotes/AAPL.","next_action":"fix_request","request_id":"req_example"}}}}}}},"401":{"description":"The supplied API key is invalid.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"invalid_api_key":{"summary":"Invalid API key","value":{"error":{"code":"invalid_api_key","message":"The supplied gfin API key is not valid.","next_action":"fix_auth","request_id":"req_example"}}}}}}},"404":{"description":"Unknown route.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"not_found":{"summary":"Unknown route","value":{"error":{"code":"not_found","message":"Unknown gfin route. Use /v1/routes or /v1/openapi.json to inspect supported routes.","next_action":"inspect_error","request_id":"req_example"}}},"route_not_found":{"summary":"Unknown route","value":{"error":{"code":"route_not_found","message":"This gfin route is not available.","next_action":"choose_supported_route","request_id":"req_example"}}}}}}},"405":{"description":"HTTP method is not allowed for this route.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"method_not_allowed":{"summary":"Method not allowed","value":{"error":{"code":"method_not_allowed","message":"gfin v1 exposes read-only GET routes.","next_action":"inspect_error","request_id":"req_example"}}}}}}},"429":{"description":"Request limit exceeded. Retry-After is included.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","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":{"error":{"code":"rate_limited","message":"Request budget exhausted.","next_action":"retry_after","request_id":"req_example"},"rate_limit":{"scope":"request","tier":"anonymous","reason":"rate_limited","retry_after_seconds":42,"limit":1200,"remaining":0,"reset_at":"2026-05-05T18:33:00.000Z","upgrade":"Send X-Gfin-Contact for higher no-key limits; email sam@gfin.dev for an API key."}}}}}}},"502":{"description":"The data request could not be completed.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"data_source_response_error":{"summary":"Data source response error","value":{"meta":{"provider":"google_finance","route":"prices_history","cache":"kv","ttl_seconds":300,"stale_seconds":3600,"generated_at":"2026-05-05T18:32:52.359Z","request_id":"req_example","identity_tier":"anonymous"},"error":{"code":"data_source_response_error","message":"The data source returned an unusable response for this finance data request.","next_action":"retry_or_use_cached_response","request_id":"req_example"}}},"response_too_large":{"summary":"Response too large","value":{"error":{"code":"response_too_large","message":"The finance data response exceeded gfin's configured response-size cap.","next_action":"narrow_request","request_id":"req_example"}}}}}}},"504":{"description":"The data source timed out or could not be reached.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"data_source_unavailable":{"summary":"Data source unavailable","value":{"error":{"code":"data_source_unavailable","message":"The data source could not be reached in time.","next_action":"retry_with_backoff","request_id":"req_example"}}}}}}}}}},"/v1/financials/{symbol}":{"get":{"tags":["Quotes"],"operationId":"getFinancials","summary":"Financials","description":"Returns financial data for one symbol when available.\n\nUse this for company financial sections, valuation workflows, screening inputs, and research agents.","parameters":[{"name":"symbol","in":"path","required":true,"schema":{"type":"string"},"description":"Ticker or finance symbol path segment, for example AAPL."},{"name":"exchange","in":"query","required":false,"schema":{"type":"string","default":"NASDAQ"},"description":"Exchange hint used with the symbol when the ticker is ambiguous, for example NASDAQ, NYSE, or INDEXNASDAQ."},{"name":"X-Gfin-Contact","in":"header","required":false,"schema":{"type":"string"},"description":"Stable contact identity for higher public request limits, for example an email address or service name."},{"name":"X-Gfin-Key","in":"header","required":false,"schema":{"type":"string"},"description":"API key for higher-volume access. Authorization: Bearer is also supported."}],"responses":{"200":{"description":"Financials response.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}},"x-gfin-cache":{"description":"Cache state for this response.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FinancialsResponse"},"examples":{"success":{"summary":"Financials success","value":{"meta":{"provider":"google_finance","route":"financials","cache":"kv","ttl_seconds":300,"stale_seconds":3600,"generated_at":"2026-05-05T18:32:52.359Z","request_id":"req_example","identity_tier":"anonymous"},"data":{"resource":"financials","instrument":{"entity_id":"%2Fm%2F07zmbvf","symbol":"AAPL","exchange":"NASDAQ","name":"Apple Inc","currency":"USD","country":"US","timezone":"America/New_York","quote":{"price":198.53,"change":1.24,"change_percent":0.63,"previous_close":197.29,"last_trade_time":"2026-05-05T18:32:00.000Z"},"extended_hours_quote":null},"statements":[{"metric":"revenue","value":391035000000,"currency":"USD"}]}}}}}}},"400":{"description":"Invalid request parameters.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"bad_request":{"summary":"Invalid request","value":{"error":{"code":"bad_request","message":"Symbol routes require a symbol path segment, for example /v1/quotes/AAPL.","next_action":"fix_request","request_id":"req_example"}}}}}}},"401":{"description":"The supplied API key is invalid.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"invalid_api_key":{"summary":"Invalid API key","value":{"error":{"code":"invalid_api_key","message":"The supplied gfin API key is not valid.","next_action":"fix_auth","request_id":"req_example"}}}}}}},"404":{"description":"Unknown route.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"not_found":{"summary":"Unknown route","value":{"error":{"code":"not_found","message":"Unknown gfin route. Use /v1/routes or /v1/openapi.json to inspect supported routes.","next_action":"inspect_error","request_id":"req_example"}}},"route_not_found":{"summary":"Unknown route","value":{"error":{"code":"route_not_found","message":"This gfin route is not available.","next_action":"choose_supported_route","request_id":"req_example"}}}}}}},"405":{"description":"HTTP method is not allowed for this route.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"method_not_allowed":{"summary":"Method not allowed","value":{"error":{"code":"method_not_allowed","message":"gfin v1 exposes read-only GET routes.","next_action":"inspect_error","request_id":"req_example"}}}}}}},"429":{"description":"Request limit exceeded. Retry-After is included.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","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":{"error":{"code":"rate_limited","message":"Request budget exhausted.","next_action":"retry_after","request_id":"req_example"},"rate_limit":{"scope":"request","tier":"anonymous","reason":"rate_limited","retry_after_seconds":42,"limit":1200,"remaining":0,"reset_at":"2026-05-05T18:33:00.000Z","upgrade":"Send X-Gfin-Contact for higher no-key limits; email sam@gfin.dev for an API key."}}}}}}},"502":{"description":"The data request could not be completed.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"data_source_response_error":{"summary":"Data source response error","value":{"meta":{"provider":"google_finance","route":"financials","cache":"kv","ttl_seconds":300,"stale_seconds":3600,"generated_at":"2026-05-05T18:32:52.359Z","request_id":"req_example","identity_tier":"anonymous"},"error":{"code":"data_source_response_error","message":"The data source returned an unusable response for this finance data request.","next_action":"retry_or_use_cached_response","request_id":"req_example"}}},"response_too_large":{"summary":"Response too large","value":{"error":{"code":"response_too_large","message":"The finance data response exceeded gfin's configured response-size cap.","next_action":"narrow_request","request_id":"req_example"}}}}}}},"504":{"description":"The data source timed out or could not be reached.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"data_source_unavailable":{"summary":"Data source unavailable","value":{"error":{"code":"data_source_unavailable","message":"The data source could not be reached in time.","next_action":"retry_with_backoff","request_id":"req_example"}}}}}}}}}},"/v1/earnings/{symbol}":{"get":{"tags":["Quotes"],"operationId":"getEarnings","summary":"Earnings","description":"Returns earnings data for one symbol when available.\n\nUse this for earnings sections, upcoming/reporting context, and agents that need earnings history or expectations.","parameters":[{"name":"symbol","in":"path","required":true,"schema":{"type":"string"},"description":"Ticker or finance symbol path segment, for example AAPL."},{"name":"exchange","in":"query","required":false,"schema":{"type":"string","default":"NASDAQ"},"description":"Exchange hint used with the symbol when the ticker is ambiguous, for example NASDAQ, NYSE, or INDEXNASDAQ."},{"name":"X-Gfin-Contact","in":"header","required":false,"schema":{"type":"string"},"description":"Stable contact identity for higher public request limits, for example an email address or service name."},{"name":"X-Gfin-Key","in":"header","required":false,"schema":{"type":"string"},"description":"API key for higher-volume access. Authorization: Bearer is also supported."}],"responses":{"200":{"description":"Earnings response.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}},"x-gfin-cache":{"description":"Cache state for this response.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EarningsResponse"},"examples":{"success":{"summary":"Earnings success","value":{"meta":{"provider":"google_finance","route":"earnings","cache":"kv","ttl_seconds":300,"stale_seconds":3600,"generated_at":"2026-05-05T18:32:52.359Z","request_id":"req_example","identity_tier":"anonymous"},"data":{"resource":"earnings","instrument":{"entity_id":"%2Fm%2F07zmbvf","symbol":"AAPL","exchange":"NASDAQ","name":"Apple Inc"},"earnings":[{"fiscal_year":2026,"fiscal_quarter":1,"eps":1.52,"eps_estimate":1.49,"currency":"USD"}]}}}}}}},"400":{"description":"Invalid request parameters.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"bad_request":{"summary":"Invalid request","value":{"error":{"code":"bad_request","message":"Symbol routes require a symbol path segment, for example /v1/quotes/AAPL.","next_action":"fix_request","request_id":"req_example"}}}}}}},"401":{"description":"The supplied API key is invalid.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"invalid_api_key":{"summary":"Invalid API key","value":{"error":{"code":"invalid_api_key","message":"The supplied gfin API key is not valid.","next_action":"fix_auth","request_id":"req_example"}}}}}}},"404":{"description":"Unknown route.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"not_found":{"summary":"Unknown route","value":{"error":{"code":"not_found","message":"Unknown gfin route. Use /v1/routes or /v1/openapi.json to inspect supported routes.","next_action":"inspect_error","request_id":"req_example"}}},"route_not_found":{"summary":"Unknown route","value":{"error":{"code":"route_not_found","message":"This gfin route is not available.","next_action":"choose_supported_route","request_id":"req_example"}}}}}}},"405":{"description":"HTTP method is not allowed for this route.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"method_not_allowed":{"summary":"Method not allowed","value":{"error":{"code":"method_not_allowed","message":"gfin v1 exposes read-only GET routes.","next_action":"inspect_error","request_id":"req_example"}}}}}}},"429":{"description":"Request limit exceeded. Retry-After is included.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","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":{"error":{"code":"rate_limited","message":"Request budget exhausted.","next_action":"retry_after","request_id":"req_example"},"rate_limit":{"scope":"request","tier":"anonymous","reason":"rate_limited","retry_after_seconds":42,"limit":1200,"remaining":0,"reset_at":"2026-05-05T18:33:00.000Z","upgrade":"Send X-Gfin-Contact for higher no-key limits; email sam@gfin.dev for an API key."}}}}}}},"502":{"description":"The data request could not be completed.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"data_source_response_error":{"summary":"Data source response error","value":{"meta":{"provider":"google_finance","route":"earnings","cache":"kv","ttl_seconds":300,"stale_seconds":3600,"generated_at":"2026-05-05T18:32:52.359Z","request_id":"req_example","identity_tier":"anonymous"},"error":{"code":"data_source_response_error","message":"The data source returned an unusable response for this finance data request.","next_action":"retry_or_use_cached_response","request_id":"req_example"}}},"response_too_large":{"summary":"Response too large","value":{"error":{"code":"response_too_large","message":"The finance data response exceeded gfin's configured response-size cap.","next_action":"narrow_request","request_id":"req_example"}}}}}}},"504":{"description":"The data source timed out or could not be reached.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"data_source_unavailable":{"summary":"Data source unavailable","value":{"error":{"code":"data_source_unavailable","message":"The data source could not be reached in time.","next_action":"retry_with_backoff","request_id":"req_example"}}}}}}}}}},"/v1/related/{symbol}":{"get":{"tags":["Quotes"],"operationId":"getRelatedAssets","summary":"Related Assets","description":"Returns entities related to one symbol.\n\nUse this for peer discovery, comparable-company lists, related-instrument widgets, and agents expanding from one ticker to nearby instruments.","parameters":[{"name":"symbol","in":"path","required":true,"schema":{"type":"string"},"description":"Ticker or finance symbol path segment, for example AAPL."},{"name":"exchange","in":"query","required":false,"schema":{"type":"string","default":"NASDAQ"},"description":"Exchange hint used with the symbol when the ticker is ambiguous, for example NASDAQ, NYSE, or INDEXNASDAQ."},{"name":"X-Gfin-Contact","in":"header","required":false,"schema":{"type":"string"},"description":"Stable contact identity for higher public request limits, for example an email address or service name."},{"name":"X-Gfin-Key","in":"header","required":false,"schema":{"type":"string"},"description":"API key for higher-volume access. Authorization: Bearer is also supported."}],"responses":{"200":{"description":"Related Assets response.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}},"x-gfin-cache":{"description":"Cache state for this response.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RelatedAssetsResponse"},"examples":{"success":{"summary":"Related Assets success","value":{"meta":{"provider":"google_finance","route":"related_assets","cache":"kv","ttl_seconds":300,"stale_seconds":3600,"generated_at":"2026-05-05T18:32:52.359Z","request_id":"req_example","identity_tier":"anonymous"},"data":{"resource":"related_assets","instrument":{"entity_id":"%2Fm%2F07zmbvf","symbol":"AAPL","exchange":"NASDAQ","name":"Apple Inc","currency":"USD","country":"US","timezone":"America/New_York","quote":{"price":198.53,"change":1.24,"change_percent":0.63,"previous_close":197.29,"last_trade_time":"2026-05-05T18:32:00.000Z"},"extended_hours_quote":null},"instruments":[{"entity_id":"%2Fm%2F07zmbvf","symbol":"AAPL","exchange":"NASDAQ","name":"Apple Inc","currency":"USD","country":"US","timezone":"America/New_York","quote":{"price":198.53,"change":1.24,"change_percent":0.63,"previous_close":197.29,"last_trade_time":"2026-05-05T18:32:00.000Z"},"extended_hours_quote":null}]}}}}}}},"400":{"description":"Invalid request parameters.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"bad_request":{"summary":"Invalid request","value":{"error":{"code":"bad_request","message":"Symbol routes require a symbol path segment, for example /v1/quotes/AAPL.","next_action":"fix_request","request_id":"req_example"}}}}}}},"401":{"description":"The supplied API key is invalid.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"invalid_api_key":{"summary":"Invalid API key","value":{"error":{"code":"invalid_api_key","message":"The supplied gfin API key is not valid.","next_action":"fix_auth","request_id":"req_example"}}}}}}},"404":{"description":"Unknown route.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"not_found":{"summary":"Unknown route","value":{"error":{"code":"not_found","message":"Unknown gfin route. Use /v1/routes or /v1/openapi.json to inspect supported routes.","next_action":"inspect_error","request_id":"req_example"}}},"route_not_found":{"summary":"Unknown route","value":{"error":{"code":"route_not_found","message":"This gfin route is not available.","next_action":"choose_supported_route","request_id":"req_example"}}}}}}},"405":{"description":"HTTP method is not allowed for this route.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"method_not_allowed":{"summary":"Method not allowed","value":{"error":{"code":"method_not_allowed","message":"gfin v1 exposes read-only GET routes.","next_action":"inspect_error","request_id":"req_example"}}}}}}},"429":{"description":"Request limit exceeded. Retry-After is included.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","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":{"error":{"code":"rate_limited","message":"Request budget exhausted.","next_action":"retry_after","request_id":"req_example"},"rate_limit":{"scope":"request","tier":"anonymous","reason":"rate_limited","retry_after_seconds":42,"limit":1200,"remaining":0,"reset_at":"2026-05-05T18:33:00.000Z","upgrade":"Send X-Gfin-Contact for higher no-key limits; email sam@gfin.dev for an API key."}}}}}}},"502":{"description":"The data request could not be completed.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"data_source_response_error":{"summary":"Data source response error","value":{"meta":{"provider":"google_finance","route":"related_assets","cache":"kv","ttl_seconds":300,"stale_seconds":3600,"generated_at":"2026-05-05T18:32:52.359Z","request_id":"req_example","identity_tier":"anonymous"},"error":{"code":"data_source_response_error","message":"The data source returned an unusable response for this finance data request.","next_action":"retry_or_use_cached_response","request_id":"req_example"}}},"response_too_large":{"summary":"Response too large","value":{"error":{"code":"response_too_large","message":"The finance data response exceeded gfin's configured response-size cap.","next_action":"narrow_request","request_id":"req_example"}}}}}}},"504":{"description":"The data source timed out or could not be reached.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"data_source_unavailable":{"summary":"Data source unavailable","value":{"error":{"code":"data_source_unavailable","message":"The data source could not be reached in time.","next_action":"retry_with_backoff","request_id":"req_example"}}}}}}}}}},"/v1/sentiment/{symbol}":{"get":{"tags":["Quotes"],"operationId":"getSentiment","summary":"Sentiment","description":"Returns sentiment-oriented data for one symbol when available.\n\nUse this as one input to research pages, ticker summaries, and agents that combine sentiment with price, news, and fundamentals.","parameters":[{"name":"symbol","in":"path","required":true,"schema":{"type":"string"},"description":"Ticker or finance symbol path segment, for example AAPL."},{"name":"exchange","in":"query","required":false,"schema":{"type":"string","default":"NASDAQ"},"description":"Exchange hint used with the symbol when the ticker is ambiguous, for example NASDAQ, NYSE, or INDEXNASDAQ."},{"name":"X-Gfin-Contact","in":"header","required":false,"schema":{"type":"string"},"description":"Stable contact identity for higher public request limits, for example an email address or service name."},{"name":"X-Gfin-Key","in":"header","required":false,"schema":{"type":"string"},"description":"API key for higher-volume access. Authorization: Bearer is also supported."}],"responses":{"200":{"description":"Sentiment response.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}},"x-gfin-cache":{"description":"Cache state for this response.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SentimentResponse"},"examples":{"success":{"summary":"Sentiment success","value":{"meta":{"provider":"google_finance","route":"sentiment","cache":"kv","ttl_seconds":300,"stale_seconds":3600,"generated_at":"2026-05-05T18:32:52.359Z","request_id":"req_example","identity_tier":"anonymous"},"data":{"resource":"sentiment","instrument":{"entity_id":"%2Fm%2F07zmbvf","symbol":"AAPL","exchange":"NASDAQ","name":"Apple Inc","currency":"USD","country":"US","timezone":"America/New_York","quote":{"price":198.53,"change":1.24,"change_percent":0.63,"previous_close":197.29,"last_trade_time":"2026-05-05T18:32:00.000Z"},"extended_hours_quote":null},"instruments":[{"entity_id":"%2Fm%2F07zmbvf","symbol":"AAPL","exchange":"NASDAQ","name":"Apple Inc","currency":"USD","country":"US","timezone":"America/New_York","quote":{"price":198.53,"change":1.24,"change_percent":0.63,"previous_close":197.29,"last_trade_time":"2026-05-05T18:32:00.000Z"},"extended_hours_quote":null}]}}}}}}},"400":{"description":"Invalid request parameters.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"bad_request":{"summary":"Invalid request","value":{"error":{"code":"bad_request","message":"Symbol routes require a symbol path segment, for example /v1/quotes/AAPL.","next_action":"fix_request","request_id":"req_example"}}}}}}},"401":{"description":"The supplied API key is invalid.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"invalid_api_key":{"summary":"Invalid API key","value":{"error":{"code":"invalid_api_key","message":"The supplied gfin API key is not valid.","next_action":"fix_auth","request_id":"req_example"}}}}}}},"404":{"description":"Unknown route.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"not_found":{"summary":"Unknown route","value":{"error":{"code":"not_found","message":"Unknown gfin route. Use /v1/routes or /v1/openapi.json to inspect supported routes.","next_action":"inspect_error","request_id":"req_example"}}},"route_not_found":{"summary":"Unknown route","value":{"error":{"code":"route_not_found","message":"This gfin route is not available.","next_action":"choose_supported_route","request_id":"req_example"}}}}}}},"405":{"description":"HTTP method is not allowed for this route.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"method_not_allowed":{"summary":"Method not allowed","value":{"error":{"code":"method_not_allowed","message":"gfin v1 exposes read-only GET routes.","next_action":"inspect_error","request_id":"req_example"}}}}}}},"429":{"description":"Request limit exceeded. Retry-After is included.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","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":{"error":{"code":"rate_limited","message":"Request budget exhausted.","next_action":"retry_after","request_id":"req_example"},"rate_limit":{"scope":"request","tier":"anonymous","reason":"rate_limited","retry_after_seconds":42,"limit":1200,"remaining":0,"reset_at":"2026-05-05T18:33:00.000Z","upgrade":"Send X-Gfin-Contact for higher no-key limits; email sam@gfin.dev for an API key."}}}}}}},"502":{"description":"The data request could not be completed.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"data_source_response_error":{"summary":"Data source response error","value":{"meta":{"provider":"google_finance","route":"sentiment","cache":"kv","ttl_seconds":300,"stale_seconds":3600,"generated_at":"2026-05-05T18:32:52.359Z","request_id":"req_example","identity_tier":"anonymous"},"error":{"code":"data_source_response_error","message":"The data source returned an unusable response for this finance data request.","next_action":"retry_or_use_cached_response","request_id":"req_example"}}},"response_too_large":{"summary":"Response too large","value":{"error":{"code":"response_too_large","message":"The finance data response exceeded gfin's configured response-size cap.","next_action":"narrow_request","request_id":"req_example"}}}}}}},"504":{"description":"The data source timed out or could not be reached.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"data_source_unavailable":{"summary":"Data source unavailable","value":{"error":{"code":"data_source_unavailable","message":"The data source could not be reached in time.","next_action":"retry_with_backoff","request_id":"req_example"}}}}}}}}}},"/v1/realtime/quotes":{"get":{"tags":["Realtime"],"operationId":"getRealtimeQuotes","summary":"Realtime Quotes","description":"Returns realtime price snapshots for finance entities.\n\nUse this for live tiles, compact price boards, monitoring screens, and agents that need current entity snapshots.","parameters":[{"name":"entity_ids","in":"query","required":false,"schema":{"type":"string"},"description":"Comma-separated finance entity IDs. Omit to use the default market pair."},{"name":"X-Gfin-Contact","in":"header","required":false,"schema":{"type":"string"},"description":"Stable contact identity for higher public request limits, for example an email address or service name."},{"name":"X-Gfin-Key","in":"header","required":false,"schema":{"type":"string"},"description":"API key for higher-volume access. Authorization: Bearer is also supported."}],"responses":{"200":{"description":"Realtime Quotes response.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}},"x-gfin-cache":{"description":"Cache state for this response.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RealtimeQuotesResponse"},"examples":{"success":{"summary":"Realtime Quotes success","value":{"meta":{"provider":"google_finance","route":"realtime_quotes","cache":"kv","ttl_seconds":300,"stale_seconds":3600,"generated_at":"2026-05-05T18:32:52.359Z","request_id":"req_example","identity_tier":"anonymous"},"data":{"resource":"realtime_quotes","instrument":{"entity_id":"%2Fm%2F07zmbvf","symbol":"AAPL","exchange":"NASDAQ","name":"Apple Inc","currency":"USD","country":"US","timezone":"America/New_York","quote":{"price":198.53,"change":1.24,"change_percent":0.63,"previous_close":197.29,"last_trade_time":"2026-05-05T18:32:00.000Z"},"extended_hours_quote":null},"instruments":[{"entity_id":"%2Fm%2F07zmbvf","symbol":"AAPL","exchange":"NASDAQ","name":"Apple Inc","currency":"USD","country":"US","timezone":"America/New_York","quote":{"price":198.53,"change":1.24,"change_percent":0.63,"previous_close":197.29,"last_trade_time":"2026-05-05T18:32:00.000Z"},"extended_hours_quote":null}]}}}}}}},"400":{"description":"Invalid request parameters.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"bad_request":{"summary":"Invalid request","value":{"error":{"code":"bad_request","message":"Invalid request parameters.","next_action":"fix_request","request_id":"req_example"}}}}}}},"401":{"description":"The supplied API key is invalid.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"invalid_api_key":{"summary":"Invalid API key","value":{"error":{"code":"invalid_api_key","message":"The supplied gfin API key is not valid.","next_action":"fix_auth","request_id":"req_example"}}}}}}},"404":{"description":"Unknown route.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"not_found":{"summary":"Unknown route","value":{"error":{"code":"not_found","message":"Unknown gfin route. Use /v1/routes or /v1/openapi.json to inspect supported routes.","next_action":"inspect_error","request_id":"req_example"}}},"route_not_found":{"summary":"Unknown route","value":{"error":{"code":"route_not_found","message":"This gfin route is not available.","next_action":"choose_supported_route","request_id":"req_example"}}}}}}},"405":{"description":"HTTP method is not allowed for this route.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"method_not_allowed":{"summary":"Method not allowed","value":{"error":{"code":"method_not_allowed","message":"gfin v1 exposes read-only GET routes.","next_action":"inspect_error","request_id":"req_example"}}}}}}},"429":{"description":"Request limit exceeded. Retry-After is included.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","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":{"error":{"code":"rate_limited","message":"Request budget exhausted.","next_action":"retry_after","request_id":"req_example"},"rate_limit":{"scope":"request","tier":"anonymous","reason":"rate_limited","retry_after_seconds":42,"limit":1200,"remaining":0,"reset_at":"2026-05-05T18:33:00.000Z","upgrade":"Send X-Gfin-Contact for higher no-key limits; email sam@gfin.dev for an API key."}}}}}}},"502":{"description":"The data request could not be completed.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"data_source_response_error":{"summary":"Data source response error","value":{"meta":{"provider":"google_finance","route":"realtime_quotes","cache":"kv","ttl_seconds":300,"stale_seconds":3600,"generated_at":"2026-05-05T18:32:52.359Z","request_id":"req_example","identity_tier":"anonymous"},"error":{"code":"data_source_response_error","message":"The data source returned an unusable response for this finance data request.","next_action":"retry_or_use_cached_response","request_id":"req_example"}}},"response_too_large":{"summary":"Response too large","value":{"error":{"code":"response_too_large","message":"The finance data response exceeded gfin's configured response-size cap.","next_action":"narrow_request","request_id":"req_example"}}}}}}},"504":{"description":"The data source timed out or could not be reached.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"data_source_unavailable":{"summary":"Data source unavailable","value":{"error":{"code":"data_source_unavailable","message":"The data source could not be reached in time.","next_action":"retry_with_backoff","request_id":"req_example"}}}}}}}}}},"/v1/realtime/trends":{"get":{"tags":["Realtime"],"operationId":"getRealtimeTrends","summary":"Realtime Trends","description":"Returns realtime trend-line data for finance entities.\n\nUse this for small live charts, intraday movement modules, and agents that need compact trend context.","parameters":[{"name":"entity_ids","in":"query","required":false,"schema":{"type":"string"},"description":"Comma-separated finance entity IDs. Omit to use the default market pair."},{"name":"X-Gfin-Contact","in":"header","required":false,"schema":{"type":"string"},"description":"Stable contact identity for higher public request limits, for example an email address or service name."},{"name":"X-Gfin-Key","in":"header","required":false,"schema":{"type":"string"},"description":"API key for higher-volume access. Authorization: Bearer is also supported."}],"responses":{"200":{"description":"Realtime Trends response.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}},"x-gfin-cache":{"description":"Cache state for this response.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RealtimeTrendsResponse"},"examples":{"success":{"summary":"Realtime Trends success","value":{"meta":{"provider":"google_finance","route":"realtime_trends","cache":"kv","ttl_seconds":300,"stale_seconds":3600,"generated_at":"2026-05-05T18:32:52.359Z","request_id":"req_example","identity_tier":"anonymous"},"data":{"resource":"realtime_trends","instrument":{"symbol":"AAPL","exchange":"NASDAQ","entity_id":"%2Fm%2F07zmbvf","name":"Apple Inc"},"currency":"USD","timezone_offset_seconds":-14400,"previous_close":197.29,"prices":[{"timestamp":"2026-05-05","price":198.53,"change":1.24,"change_percent":0.63,"volume":51234567}]}}}}}}},"400":{"description":"Invalid request parameters.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"bad_request":{"summary":"Invalid request","value":{"error":{"code":"bad_request","message":"Invalid request parameters.","next_action":"fix_request","request_id":"req_example"}}}}}}},"401":{"description":"The supplied API key is invalid.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"invalid_api_key":{"summary":"Invalid API key","value":{"error":{"code":"invalid_api_key","message":"The supplied gfin API key is not valid.","next_action":"fix_auth","request_id":"req_example"}}}}}}},"404":{"description":"Unknown route.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"not_found":{"summary":"Unknown route","value":{"error":{"code":"not_found","message":"Unknown gfin route. Use /v1/routes or /v1/openapi.json to inspect supported routes.","next_action":"inspect_error","request_id":"req_example"}}},"route_not_found":{"summary":"Unknown route","value":{"error":{"code":"route_not_found","message":"This gfin route is not available.","next_action":"choose_supported_route","request_id":"req_example"}}}}}}},"405":{"description":"HTTP method is not allowed for this route.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"method_not_allowed":{"summary":"Method not allowed","value":{"error":{"code":"method_not_allowed","message":"gfin v1 exposes read-only GET routes.","next_action":"inspect_error","request_id":"req_example"}}}}}}},"429":{"description":"Request limit exceeded. Retry-After is included.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","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":{"error":{"code":"rate_limited","message":"Request budget exhausted.","next_action":"retry_after","request_id":"req_example"},"rate_limit":{"scope":"request","tier":"anonymous","reason":"rate_limited","retry_after_seconds":42,"limit":1200,"remaining":0,"reset_at":"2026-05-05T18:33:00.000Z","upgrade":"Send X-Gfin-Contact for higher no-key limits; email sam@gfin.dev for an API key."}}}}}}},"502":{"description":"The data request could not be completed.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"data_source_response_error":{"summary":"Data source response error","value":{"meta":{"provider":"google_finance","route":"realtime_trends","cache":"kv","ttl_seconds":300,"stale_seconds":3600,"generated_at":"2026-05-05T18:32:52.359Z","request_id":"req_example","identity_tier":"anonymous"},"error":{"code":"data_source_response_error","message":"The data source returned an unusable response for this finance data request.","next_action":"retry_or_use_cached_response","request_id":"req_example"}}},"response_too_large":{"summary":"Response too large","value":{"error":{"code":"response_too_large","message":"The finance data response exceeded gfin's configured response-size cap.","next_action":"narrow_request","request_id":"req_example"}}}}}}},"504":{"description":"The data source timed out or could not be reached.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"data_source_unavailable":{"summary":"Data source unavailable","value":{"error":{"code":"data_source_unavailable","message":"The data source could not be reached in time.","next_action":"retry_with_backoff","request_id":"req_example"}}}}}}}}}},"/v1/watchlists":{"get":{"tags":["User Context"],"operationId":"getWatchlists","summary":"Watchlists","description":"Returns watchlist-context data when available for the request context.\n\nAnonymous requests may return empty or limited data. Use this only when a workflow can tolerate account-context availability differences.","parameters":[{"name":"X-Gfin-Contact","in":"header","required":false,"schema":{"type":"string"},"description":"Stable contact identity for higher public request limits, for example an email address or service name."},{"name":"X-Gfin-Key","in":"header","required":false,"schema":{"type":"string"},"description":"API key for higher-volume access. Authorization: Bearer is also supported."}],"responses":{"200":{"description":"Watchlists response.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}},"x-gfin-cache":{"description":"Cache state for this response.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WatchlistsResponse"},"examples":{"success":{"summary":"Watchlists success","value":{"meta":{"provider":"google_finance","route":"watchlists","cache":"kv","ttl_seconds":300,"stale_seconds":3600,"generated_at":"2026-05-05T18:32:52.359Z","request_id":"req_example","identity_tier":"anonymous"},"data":{"resource":"watchlists","records":[]}}}}}}},"400":{"description":"Invalid request parameters.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"bad_request":{"summary":"Invalid request","value":{"error":{"code":"bad_request","message":"Invalid request parameters.","next_action":"fix_request","request_id":"req_example"}}}}}}},"401":{"description":"The supplied API key is invalid.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"invalid_api_key":{"summary":"Invalid API key","value":{"error":{"code":"invalid_api_key","message":"The supplied gfin API key is not valid.","next_action":"fix_auth","request_id":"req_example"}}}}}}},"404":{"description":"Unknown route.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"not_found":{"summary":"Unknown route","value":{"error":{"code":"not_found","message":"Unknown gfin route. Use /v1/routes or /v1/openapi.json to inspect supported routes.","next_action":"inspect_error","request_id":"req_example"}}},"route_not_found":{"summary":"Unknown route","value":{"error":{"code":"route_not_found","message":"This gfin route is not available.","next_action":"choose_supported_route","request_id":"req_example"}}}}}}},"405":{"description":"HTTP method is not allowed for this route.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"method_not_allowed":{"summary":"Method not allowed","value":{"error":{"code":"method_not_allowed","message":"gfin v1 exposes read-only GET routes.","next_action":"inspect_error","request_id":"req_example"}}}}}}},"429":{"description":"Request limit exceeded. Retry-After is included.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","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":{"error":{"code":"rate_limited","message":"Request budget exhausted.","next_action":"retry_after","request_id":"req_example"},"rate_limit":{"scope":"request","tier":"anonymous","reason":"rate_limited","retry_after_seconds":42,"limit":1200,"remaining":0,"reset_at":"2026-05-05T18:33:00.000Z","upgrade":"Send X-Gfin-Contact for higher no-key limits; email sam@gfin.dev for an API key."}}}}}}},"502":{"description":"The data request could not be completed.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"data_source_response_error":{"summary":"Data source response error","value":{"meta":{"provider":"google_finance","route":"watchlists","cache":"kv","ttl_seconds":300,"stale_seconds":3600,"generated_at":"2026-05-05T18:32:52.359Z","request_id":"req_example","identity_tier":"anonymous"},"error":{"code":"data_source_response_error","message":"The data source returned an unusable response for this finance data request.","next_action":"retry_or_use_cached_response","request_id":"req_example"}}},"response_too_large":{"summary":"Response too large","value":{"error":{"code":"response_too_large","message":"The finance data response exceeded gfin's configured response-size cap.","next_action":"narrow_request","request_id":"req_example"}}}}}}},"504":{"description":"The data source timed out or could not be reached.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"data_source_unavailable":{"summary":"Data source unavailable","value":{"error":{"code":"data_source_unavailable","message":"The data source could not be reached in time.","next_action":"retry_with_backoff","request_id":"req_example"}}}}}}}}}}}}