{"openapi":"3.1.0","info":{"title":"FreeOptionScreener read-only connector","version":"1.0.0","description":"Query the latest completed option-data publication. This does not fetch new exchange quotes. Inspect data_as_of and each row's quote timestamps before describing data as current. IV and other native provider fields retain the screener's values; unavailable values remain null. Both tools are read-only and have no trading actions."},"paths":{"/api/connector/options":{"get":{"summary":"Search latest published option contracts","description":"Read-only. Filter option contracts using the screener's native quotes and analytics. Specify symbols (comma-separated, or *), type, DTE, delta, IV, volume and other filters as needed. Defaults select puts with positive bids and spread <=20%. IV inputs and provider_iv are annualized decimals (0.25 means 25%). DTE is measured at the data cutoff, not at the current wall clock. Pages contain at most 100 rows. Compare data_version across pages; restart paging if a new publication becomes available. Check data_as_of and row quote timestamps; latest does not mean real-time.","operationId":"search_latest_options","parameters":[{"name":"provider","in":"query","required":false,"schema":{"type":"string","pattern":"^[a-zA-Z0-9_-]+$","default":"all","title":"Provider"}},{"name":"symbols","in":"query","required":true,"schema":{"type":"string","minLength":1,"maxLength":1000,"title":"Symbols"}},{"name":"rules","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Rules"}},{"name":"type","in":"query","required":false,"schema":{"enum":["all","call","put"],"type":"string","default":"put","title":"Type"}},{"name":"moneyness","in":"query","required":false,"schema":{"enum":["atm","otm","all"],"type":"string","default":"all","title":"Moneyness"}},{"name":"dte_min","in":"query","required":false,"schema":{"anyOf":[{"type":"integer","minimum":0},{"type":"null"}],"title":"Dte Min"}},{"name":"dte_max","in":"query","required":false,"schema":{"anyOf":[{"type":"integer","minimum":0},{"type":"null"}],"title":"Dte Max"}},{"name":"delta_min","in":"query","required":false,"schema":{"anyOf":[{"type":"number","maximum":1,"minimum":-1},{"type":"null"}],"title":"Delta Min"}},{"name":"delta_max","in":"query","required":false,"schema":{"anyOf":[{"type":"number","maximum":1,"minimum":-1},{"type":"null"}],"title":"Delta Max"}},{"name":"absolute_delta","in":"query","required":false,"schema":{"type":"boolean","default":true,"title":"Absolute Delta"}},{"name":"theta_min","in":"query","required":false,"schema":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Theta Min"}},{"name":"theta_max","in":"query","required":false,"schema":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Theta Max"}},{"name":"gamma_min","in":"query","required":false,"schema":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Gamma Min"}},{"name":"gamma_max","in":"query","required":false,"schema":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Gamma Max"}},{"name":"vega_min","in":"query","required":false,"schema":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Vega Min"}},{"name":"vega_max","in":"query","required":false,"schema":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Vega Max"}},{"name":"provider_iv_min","in":"query","required":false,"schema":{"anyOf":[{"type":"number","maximum":1000,"minimum":0},{"type":"null"}],"title":"Provider Iv Min"}},{"name":"provider_iv_max","in":"query","required":false,"schema":{"anyOf":[{"type":"number","maximum":1000,"minimum":0},{"type":"null"}],"title":"Provider Iv Max"}},{"name":"deviation_min","in":"query","required":false,"schema":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Deviation Min"}},{"name":"deviation_max","in":"query","required":false,"schema":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Deviation Max"}},{"name":"strike_min","in":"query","required":false,"schema":{"anyOf":[{"type":"number","minimum":0},{"type":"null"}],"title":"Strike Min"}},{"name":"strike_max","in":"query","required":false,"schema":{"anyOf":[{"type":"number","minimum":0},{"type":"null"}],"title":"Strike Max"}},{"name":"spot_min","in":"query","required":false,"schema":{"anyOf":[{"type":"number","minimum":0},{"type":"null"}],"title":"Spot Min"}},{"name":"spot_max","in":"query","required":false,"schema":{"anyOf":[{"type":"number","minimum":0},{"type":"null"}],"title":"Spot Max"}},{"name":"open_interest_min","in":"query","required":false,"schema":{"anyOf":[{"type":"integer","minimum":0},{"type":"null"}],"title":"Open Interest Min"}},{"name":"open_interest_max","in":"query","required":false,"schema":{"anyOf":[{"type":"integer","minimum":0},{"type":"null"}],"title":"Open Interest Max"}},{"name":"volume_max","in":"query","required":false,"schema":{"anyOf":[{"type":"integer","minimum":0},{"type":"null"}],"title":"Volume Max"}},{"name":"sector","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Sector"}},{"name":"market_cap_min_b","in":"query","required":false,"schema":{"anyOf":[{"type":"number","minimum":0},{"type":"null"}],"title":"Market Cap Min B"}},{"name":"market_cap_max_b","in":"query","required":false,"schema":{"anyOf":[{"type":"number","minimum":0},{"type":"null"}],"title":"Market Cap Max B"}},{"name":"earnings_min","in":"query","required":false,"schema":{"anyOf":[{"type":"integer","minimum":0},{"type":"null"}],"title":"Earnings Min"}},{"name":"earnings_max","in":"query","required":false,"schema":{"anyOf":[{"type":"integer","minimum":0},{"type":"null"}],"title":"Earnings Max"}},{"name":"earnings_unknown","in":"query","required":false,"schema":{"enum":["include","exclude","only"],"type":"string","default":"include","title":"Earnings Unknown"}},{"name":"earnings_before_expiry","in":"query","required":false,"schema":{"enum":["any","yes","no"],"type":"string","default":"any","title":"Earnings Before Expiry"}},{"name":"volume_min","in":"query","required":false,"schema":{"anyOf":[{"type":"integer","minimum":0},{"type":"null"}],"title":"Volume Min"}},{"name":"spread_max","in":"query","required":false,"schema":{"anyOf":[{"type":"number","minimum":0},{"type":"null"}],"default":20,"title":"Spread Max"}},{"name":"bid_min","in":"query","required":false,"schema":{"anyOf":[{"type":"number","minimum":0},{"type":"null"}],"default":0.1,"title":"Bid Min"}},{"name":"valid_quotes_only","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Valid Quotes Only"}},{"name":"verified_spot_only","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Verified Spot Only"}},{"name":"rate","in":"query","required":false,"schema":{"type":"number","maximum":0.5,"minimum":-0.1,"default":0.04,"title":"Rate"}},{"name":"dividend","in":"query","required":false,"schema":{"type":"number","maximum":0.5,"minimum":0,"default":0.0,"title":"Dividend"}},{"name":"sort","in":"query","required":false,"schema":{"enum":["symbol","expiration","strike","type","spot","dte","mid","bid","ask","delta","theta","gamma","vega","iv","provider_iv","deviation_pct","earnings_days","volume","spread_pct","spread_bid_pct","open_interest"],"type":"string","default":"provider_iv","title":"Sort"}},{"name":"direction","in":"query","required":false,"schema":{"enum":["asc","desc"],"type":"string","default":"desc","title":"Direction"}},{"name":"per_symbol_limit","in":"query","required":false,"schema":{"anyOf":[{"type":"integer","minimum":0},{"type":"null"}],"title":"Per Symbol Limit"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer","minimum":1,"default":1,"title":"Page"}},{"name":"page_size","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"default":50,"title":"Page Size"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConnectorOptions"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"401":{"description":"Missing, expired or revoked user authorization."},"403":{"description":"Connector access is read-only."},"503":{"description":"No completed option data is ready."}}}},"/api/connector/status":{"get":{"summary":"Read option-data availability and timestamps","description":"Read-only. Return the latest completed data version, cutoff, publication time, available symbols and providers. Not an on-demand market-data refresh.","operationId":"get_latest_option_data_status","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConnectorStatus"}}}},"401":{"description":"Missing, expired or revoked user authorization."},"403":{"description":"Connector access is read-only."},"503":{"description":"No completed option data is ready."}}}}},"components":{"schemas":{"Authorization":{"properties":{"response_type":{"type":"string","const":"code","title":"Response Type"},"client_id":{"type":"string","maxLength":128,"minLength":1,"title":"Client Id"},"redirect_uri":{"type":"string","maxLength":2048,"minLength":1,"title":"Redirect Uri"},"scope":{"type":"string","const":"options:read","title":"Scope","default":"options:read"},"state":{"type":"string","maxLength":1024,"minLength":1,"title":"State"},"code_challenge":{"type":"string","pattern":"^[A-Za-z0-9_-]{43}$","title":"Code Challenge"},"code_challenge_method":{"type":"string","const":"S256","title":"Code Challenge Method"}},"additionalProperties":false,"type":"object","required":["response_type","client_id","redirect_uri","state","code_challenge","code_challenge_method"],"title":"Authorization","description":"A single read-only authorization-code request with mandatory S256 PKCE."},"ClientEvent":{"properties":{"kind":{"type":"string","enum":["latency","error"],"title":"Kind"},"action":{"type":"string","maxLength":60,"pattern":"^[a-zA-Z0-9_.-]+$","title":"Action"},"content_status":{"type":"string","enum":["matches","confirmed_empty","source_unavailable","failed"],"title":"Content Status"},"duration_ms":{"type":"number","maximum":172800000.0,"minimum":0.0,"title":"Duration Ms"},"contracts":{"type":"integer","maximum":10000000.0,"minimum":0.0,"title":"Contracts","default":0},"cache_state":{"type":"string","enum":["warm","cold","retrying","unknown"],"title":"Cache State","default":"unknown"},"snapshot_id":{"anyOf":[{"type":"string","pattern":"^[a-f0-9]{64}$"},{"type":"null"}],"title":"Snapshot Id"},"message":{"type":"string","maxLength":300,"title":"Message","default":""},"stages":{"items":{"$ref":"#/components/schemas/ClientStage"},"type":"array","maxItems":80,"title":"Stages"},"omitted_stages":{"type":"integer","maximum":1000000.0,"minimum":0.0,"title":"Omitted Stages","default":0},"operation_ids":{"items":{"type":"string","pattern":"^[a-f0-9]{32}$"},"type":"array","maxItems":16,"title":"Operation Ids"},"ttfb_ms":{"anyOf":[{"type":"number","maximum":86400000.0,"minimum":0.0},{"type":"null"}],"title":"Ttfb Ms"},"download_bytes":{"anyOf":[{"type":"integer","maximum":1099511627776.0,"minimum":0.0},{"type":"null"}],"title":"Download Bytes"},"measurement_scope":{"type":"string","enum":["unknown","document","action","auth_journey","reauth_journey"],"title":"Measurement Scope","default":"unknown"},"history_state":{"type":"string","enum":["not_applicable","not_found","included","unavailable","invalid","expired","pending"],"title":"History State","default":"not_applicable"},"origin_action":{"anyOf":[{"type":"string","enum":["navigation","scanner","deep-dive","history","refresh","details","export","deep-symbol","table-sort"]},{"type":"null"}],"title":"Origin Action"},"context":{"$ref":"#/components/schemas/MeasurementContext"}},"additionalProperties":false,"type":"object","required":["kind","action","content_status","duration_ms"],"title":"ClientEvent"},"ClientStage":{"properties":{"name":{"type":"string","maxLength":80,"pattern":"^[a-zA-Z0-9_./-]+$","title":"Name"},"start_ms":{"type":"number","maximum":172800000.0,"minimum":0.0,"title":"Start Ms"},"duration_ms":{"type":"number","maximum":172800000.0,"minimum":0.0,"title":"Duration Ms"},"clock":{"type":"string","enum":["client","server"],"title":"Clock","default":"client"},"operation_id":{"anyOf":[{"type":"string","pattern":"^[a-f0-9]{32}$"},{"type":"null"}],"title":"Operation Id"},"request_id":{"anyOf":[{"type":"string","pattern":"^[a-f0-9]{32}$"},{"type":"null"}],"title":"Request Id"},"status":{"anyOf":[{"type":"integer","maximum":599.0,"minimum":100.0},{"type":"null"}],"title":"Status"}},"additionalProperties":false,"type":"object","required":["name","start_ms","duration_ms"],"title":"ClientStage"},"ConnectorOptions":{"properties":{"data_version":{"type":"string","title":"Data Version"},"data_as_of":{"type":"string","format":"date-time","title":"Data As Of"},"matched_contracts":{"type":"integer","title":"Matched Contracts"},"returned_contracts":{"type":"integer","title":"Returned Contracts"},"page":{"type":"integer","title":"Page"},"page_size":{"type":"integer","title":"Page Size"},"next_page":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Next Page"},"missing_symbols":{"items":{"type":"string"},"type":"array","title":"Missing Symbols"},"rows":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Rows","description":"The screener's contract rows, including identity, bid/ask, quote timestamps and native provider_iv/provider Greeks. The separate iv/model fields are calculated estimates; missing values remain null."}},"type":"object","required":["data_version","data_as_of","matched_contracts","returned_contracts","page","page_size","next_page","missing_symbols","rows"],"title":"ConnectorOptions","description":"One bounded page, retaining the screener's native row values and nulls."},"ConnectorStatus":{"properties":{"data_version":{"type":"string","title":"Data Version"},"data_as_of":{"type":"string","format":"date-time","title":"Data As Of"},"published_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Published At"},"symbols":{"items":{"type":"string"},"type":"array","title":"Symbols"},"providers":{"items":{"type":"string"},"type":"array","title":"Providers"}},"type":"object","required":["data_version","data_as_of","published_at","symbols","providers"],"title":"ConnectorStatus","description":"Describe the ready publication without exposing storage paths or credentials."},"Consent":{"properties":{"authorization":{"$ref":"#/components/schemas/Authorization"},"decision":{"type":"string","enum":["allow","deny"],"title":"Decision"}},"additionalProperties":false,"type":"object","required":["authorization","decision"],"title":"Consent"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"LoginBody":{"properties":{"id_token":{"type":"string","maxLength":20000,"minLength":1,"title":"Id Token"}},"additionalProperties":false,"type":"object","required":["id_token"],"title":"LoginBody"},"MeasurementContext":{"properties":{"browser_family":{"type":"string","enum":["chrome","edge","firefox","safari","other","unknown"],"title":"Browser Family","default":"unknown"},"browser_major":{"anyOf":[{"type":"integer","maximum":1000.0,"minimum":0.0},{"type":"null"}],"title":"Browser Major"},"platform":{"type":"string","enum":["windows","macos","linux","android","ios","other","unknown"],"title":"Platform","default":"unknown"},"viewport_width":{"anyOf":[{"type":"integer","maximum":10000.0,"minimum":0.0},{"type":"null"}],"title":"Viewport Width"},"viewport_height":{"anyOf":[{"type":"integer","maximum":10000.0,"minimum":0.0},{"type":"null"}],"title":"Viewport Height"},"pixel_ratio":{"anyOf":[{"type":"number","maximum":8.0,"minimum":0.5},{"type":"null"}],"title":"Pixel Ratio"},"visibility":{"type":"string","enum":["visible","hidden","prerender","unknown"],"title":"Visibility","default":"unknown"},"network_source":{"type":"string","enum":["network_information","unavailable"],"title":"Network Source","default":"unavailable"},"effective_type":{"type":"string","enum":["slow-2g","2g","3g","4g","unknown"],"title":"Effective Type","default":"unknown"},"rtt_estimate_ms":{"anyOf":[{"type":"integer","maximum":10000.0,"minimum":0.0},{"type":"null"}],"title":"Rtt Estimate Ms"},"downlink_estimate_mbps":{"anyOf":[{"type":"number","maximum":10000.0,"minimum":0.0},{"type":"null"}],"title":"Downlink Estimate Mbps"},"save_data":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Save Data"}},"additionalProperties":false,"type":"object","title":"MeasurementContext","description":"Whitelisted observations at report time, not measured network performance."},"SaveQuery":{"properties":{"name":{"type":"string","maxLength":80,"minLength":1,"pattern":"^[^/\\\\\\x00-\\x1f\\x7f]+$","title":"Name"},"query":{"type":"string","maxLength":20000,"minLength":1,"title":"Query"}},"additionalProperties":false,"type":"object","required":["name","query"],"title":"SaveQuery"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}},"securitySchemes":{"ConnectorOAuth":{"type":"oauth2","flows":{"authorizationCode":{"authorizationUrl":"https://freeoptionscreener.com/oauth/authorize","tokenUrl":"https://freeoptionscreener.com/oauth/token","refreshUrl":"https://freeoptionscreener.com/oauth/token","scopes":{"options:read":"Read the latest published option data."}}}}}},"servers":[{"url":"https://freeoptionscreener.com"}],"security":[{"ConnectorOAuth":["options:read"]}]}