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 mle.ultimate@gmail.com 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.

Users 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.

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 mle.ultimate@gmail.com 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.