Introduction

The PublicOptions API is a REST interface to historical price data for US equity options. All responses are JSON. All endpoints are versioned under /v1.

Servers

All traffic goes through a single production base URL.

Quickstart

Create an API key in your dashboard, then pull a year of daily quotes for AAPL Jan-2026 $180 calls.

curl https://api.czar28.com/v1/options/quote/eod \
  -H "Authorization: Bearer sopk_live_..." \
  -G --data-urlencode "root=AAPL" \
      --data-urlencode "exp=20250117" \
      --data-urlencode "strike=180" \
      --data-urlencode "right=C" \
      --data-urlencode "start_date=20240101" \
      --data-urlencode "end_date=20240601"

Authentication

Every request must include an Authorization header with your API key. Keys are scoped to your account and can be rotated or revoked instantly from the dashboard.

Authorization: Bearer sopk_live_xxxxxxxxxxxxxxxx

Key types

• sopk_live_… — production keys, count against your monthly quota.
• sopk_test_… — test keys, separate quota, safe to embed in CI.

Rotation

Rotating a key issues a new secret and keeps the old one alive for a 24-hour grace window, so you can deploy without downtime. Revoking a key takes effect immediately.

Security

• Treat the key like a password. Never commit it or expose it in browser code.
• API keys are hashed at rest; the full value is shown exactly once at creation.
• All traffic must be TLS — plain HTTP is rejected.

Errors

Failed requests return a JSON body with stable error and message fields. Validation errors include a details object listing the offending parameters.

{
  "error": "invalid_parameters",
  "message": "exp must be YYYYMMDD",
  "details": { "fieldErrors": { "exp": ["exp must be YYYYMMDD"] } }
}

Retry guidance

• 502 / 503 — retry with exponential backoff (250 ms × 2ⁿ, max 5 attempts).
• 429 — stop, upgrade your plan, or wait until X-RateLimit-Reset.
• 400 / 401 / 402 — never retry; fix the request or account first.

Rate limits & quotas

Every successful response carries the following headers so clients can self-throttle without polling:

Quotas are tracked per account, not per key, and reset at 00:00 UTC on the first of each month. Per-minute rate limits also apply (Free 60/min burst 20, Pro 600/min burst 100, Business 3000/min burst 500). Responses include X-RateLimit-Limit-Minute, X-RateLimit-Burst, and Retry-After headers. See pricing for plan limits.

Idempotency

Every endpoint accepts an optional Idempotency-Key request header. When two requests arrive within 24 hours with the same key and the same body, the second request returns the original cached response — without re-hitting the upstream provider and without consuming additional monthly quota. This is the recommended pattern for safely retrying after a timeout or network error.

Rules

• Key is an opaque client-generated string, ≤ 255 characters. UUIDs work well.
• Scope is per API key. Two different keys may reuse the same value without collision.
• Replays return the original status code and body, plus Idempotent-Replayed: true.
• Reusing a key with a different request body returns 409 idempotency_conflict.
• 5xx responses are not cached, so transient upstream failures are safe to retry with the same key.
• Entries expire after 24 hours.

curl "https://api.czar28.com/v1/options/quote/eod?root=AAPL&exp=20260116&strike=180&right=C&start_date=20250601&end_date=20250701" \
  -H "Authorization: Bearer sopk_live_..." \
  -H "Idempotency-Key: 8e3b5c0a-2f4a-4b9d-9a8e-1c2d3f4a5b6c"

CORS

Every /v1 endpoint allows cross-origin GET from any origin and exposes the rate-limit headers, so you can call the API directly from a browser app running on your own domain.

Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET, OPTIONS
Access-Control-Allow-Headers: Content-Type, Authorization, Idempotency-Key
Access-Control-Expose-Headers: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset, X-RateLimit-Burst, Retry-After, API-Version, Idempotent-Replayed

Heads-up: anything you ship to the browser is publicly visible. Don't embed a high-volume key in a public site — proxy through your own backend instead.

Response envelope

All data endpoints return the same shape: a header with metadata and a response array of rows. The header.format array names each column, in order, for the rows in response.

{
  "header": {
    "latency_ms": 47,
    "format": ["ms_of_day", "bid", "ask", "bid_size", "ask_size", "date"]
  },
  "response": [
    [34200000, 6.85, 7.05, 12, 9, 20240102],
    [34260000, 6.80, 7.00, 14, 11, 20240102]
  ]
}

Loading into pandas:

import pandas as pd
df = pd.DataFrame(body["response"], columns=body["header"]["format"])

Versioning & deprecation policy

The API is versioned in the URL path. The current stable version is /v1. We will never make a backwards-incompatible change to a released version — breaking changes ship as a new major version (/v2) alongside the old one.

What counts as a breaking change

• Removing or renaming an endpoint, field, parameter, or error code
• Changing the type or semantics of an existing field
• Making a previously optional parameter required
• Tightening validation in a way that rejects previously valid input

What is not breaking (safe to add anytime)

• New endpoints, optional parameters, or response fields
• New optional response headers
• New enum values returned by the server (clients must tolerate unknown values)
• Bug fixes that align behavior with the documented contract

Deprecation timeline

• Day 0 — deprecation announced via email and on this page. Successor version is generally available.
• Day 0 onward — deprecated endpoints return a Deprecation: true header (RFC 9745) and a Sunset header (RFC 8594) with the removal date. A Link header points to the successor.
• 12 months minimum — deprecated version continues to work unchanged. Paid plans get a written 12-month commitment from announcement to sunset.
• Sunset date — deprecated version returns 410 Gone with { "error": "version_sunset" }.

Currently active versions

Changelog

Notable changes to the public API. Additive changes (new endpoints, optional parameters, new response fields) ship without notice; anything breaking follows the deprecation policy above.

OpenAPI & Postman

Machine-readable spec and a ready-to-import Postman collection. Set the apiKey variable to your sopk_… key after importing.