Options API documentation

Connect an app, including Muse

Connection type

Raw API (REST over HTTPS)

API URL

https://freeoptionscreener.com

OpenAPI specification

https://freeoptionscreener.com/connectors/openapi.json

API documentation

https://freeoptionscreener.com/api_docs

OAuth discovery

OAuth server metadata

Before onboarding, send your app name, client ID and exact HTTPS callback URL to [email protected] for registration. Your app must support public OAuth clients with S256 PKCE and no client secret. Unregistered clients and wildcard callbacks are not accepted; dynamic client registration is not supported. Publishing this specification does not mean that Muse registration or approval is complete.

Login and user authorization are required

1. Generate a PKCE verifier, its S256 challenge and a random state value. Open /oauth/authorize with response_type=code, your registered client_id and redirect_uri, scope=options:read, state, code_challenge and code_challenge_method=S256.
2. The user signs in with Google and explicitly approves read-only access. Verify the returned state and issuer at your callback.
3. Exchange the one-use code within five minutes using a URL-encoded POST to /oauth/token. Send grant_type=authorization_code, client_id, the exact redirect_uri, code and code_verifier.
4. Send Authorization: Bearer ACCESS_TOKEN with every data request. A website session cookie or shared API key cannot replace this user token.

Access tokens last 15 minutes. Refresh with a URL-encoded POST to /oauth/token using grant_type=refresh_token, client_id and refresh_token. Store the new access and refresh tokens together: refresh rotates both and invalidates the previous access token. Serialize refreshes. Reusing a spent code or refresh token revokes the connection. Authorization lasts at most 30 days, after which the user must reconnect.

Administrators can revoke access from Connected apps after signing in. Clients can POST token and client_id as a URL-encoded form to /oauth/revoke. Keep tokens private and never put them in URLs or logs. The connector cannot trade, write data, read saved queries or access administrator tools.

Read-only endpoints

GET /api/connector/status

Returns data_version, data_as_of, published_at, symbols and providers for the latest ready publication.

GET /api/connector/options

Specify symbols as comma-separated tickers or * for all available symbols. Use the same filters and ordering as the screener: for example, type (put, call or all), dte_min, dte_max, delta_min, delta_max, absolute_delta, open_interest_min, volume_min, sort and direction. The OpenAPI specification lists all parameters and response fields.

curl --get 'https://freeoptionscreener.com/api/connector/options' \
  --header "Authorization: Bearer $ACCESS_TOKEN" \
  --data-urlencode 'symbols=NVDA' \
  --data-urlencode 'type=put' \
  --data-urlencode 'dte_min=7' \
  --data-urlencode 'dte_max=45' \
  --data-urlencode 'delta_min=0.10' \
  --data-urlencode 'delta_max=0.30' \
  --data-urlencode 'absolute_delta=true' \
  --data-urlencode 'sort=provider_iv' \
  --data-urlencode 'direction=desc' \
  --data-urlencode 'page_size=50'

Defaults select puts with bid at least $0.10 and bid-based spread below 20%, ordered by provider IV descending. IV is an annualized decimal: 0.25 means 25%. With absolute_delta=true, delta bounds compare absolute values. Native provider IV and Greeks retain their provider values; missing values remain null. Separate model fields are estimates.

Results include rows, matched_contracts, returned_contracts, missing_symbols, data_version and data_as_of. These are published data, not streaming quotes or an on-demand provider refresh. Check the data cutoff and each row's quote timestamps. DTE is measured at the data cutoff rather than the current wall-clock time.

Pagination and usage limits

page starts at 1. page_size defaults to 50, with a maximum of 100 rows per page. Follow the returned next_page until it is null; this is a per-page limit, not a 100-contract total limit. Keep filters and ordering unchanged between pages. If data_version changes, restart at page 1 to avoid mixing publications.

There is no separate connector request quota currently. Calls share the website's runtime capacity; use bounded queries and avoid unnecessary polling.

Public screener columns

The public screener accepts /api/scan?symbols=AMD&columns=hv30,iv_rank. Symbol, Type, Expiration, Strike, Bid and Ask are always returned. Optional columns default to underlying price, provider IV and After Earning. Pass a comma-separated columns list to change them; an empty list requests only the six required columns. Unknown names return HTTP 422.

Optional historical fields are hv30, hv90, iv_rankand iv_percentile. HV is an annualized fraction; rank and percentile use 0–100 and describe the underlying IV30 distribution. Missing values are null. Responses include the applied column list, row identity, adjusted exercise terms and small display/grouping helpers. CSV retains the exercise terms alongside selected columns.

annualized_yield is an optional sortable column and numeric rule in percentage points: 10 means 10%. It uses 100 × (bid − intrinsic value) / collateral × 365 / DTE, with strike collateral for puts and stock-price collateral for calls. Missing inputs, invalid quotes, adjusted contracts and nonpositive DTE return null. Zero and negative time-value yields remain unchanged. This is simple annualization, excluding fees, rather than an expected return.

Errors and support

• 401: Missing, invalid, expired or revoked user authorization.
• 403: Attempted write; the connector is read-only.
• 422: Invalid query parameters, including a page size above 100.
• 503: Data, authentication or storage are temporarily unavailable.

OAuth endpoints return standard OAuth error objects. For support, email [email protected] with the endpoint, time and timezone, status code and redacted error. Never send tokens or authorization codes. See our privacy policy and terms of service.