OLYMPUSby New Odyssey
Menu
Documentation

Quickstart

From sign-up to your first response in four steps.

  1. Create an account

    Sign up with your email address and confirm it using the link we send. You get an organization on the Free plan, which includes both products.

  2. Create an API key

    In the console, open API keys and create a key. You can limit it to one product and set an expiry date. The full key is shown once. Store it in your secret manager or an environment variable:

    shell
    export OLYMPUS_API_KEY="oly_live_..."

  3. Make a request

    Send the key in the X-API-Key header:

    SEC Filings & Financial Data: resolve a ticker
    curl -s "https://api.olympus.new-odyssey.com/v1/sec/companies/search?ticker=AAPL" \
  -H "X-API-Key: $OLYMPUS_API_KEY"
    Geographic & Demographics: a ZCTA profile
    curl -s "https://api.olympus.new-odyssey.com/v1/geo-demographics/locations/02139" \
  -H "X-API-Key: $OLYMPUS_API_KEY"

  4. Check your usage

    The console shows requests by day, product and endpoint. You can also read usage with any key:

    shell
    curl -s "https://api.olympus.new-odyssey.com/v1/usage?from=2026-10-01" \
  -H "X-API-Key: $OLYMPUS_API_KEY"

Authentication

Product and usage endpoints take an organization API key in X-API-Key, or as Authorization: Bearer <key>. Keys look like oly_live_… or oly_test_…. Keys in query strings are rejected because URLs end up in logs. A key scoped to one product returns 403 API_KEY_PRODUCT_SCOPE on the other product. Revoked and expired keys return 401 API_KEY_REVOKED or 401 API_KEY_EXPIRED.

Errors

Every error, from every service, has the same body: a human-readable error, a stable code, the product when there is one, and optional details. Every response carries an X-Request-Id. Include it when you contact us.

404 Not Found
{
  "error": "Company not found",
  "code": "NOT_FOUND",
  "product": "sec",
  "details": { "cik": "0000000001" }
}

Rate limits and quotas

Each plan sets a per-minute rate limit and a monthly request quota per product (see pricing). Responses carry X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset, plus X-Quota-Limit, X-Quota-Remaining and X-Quota-Reset. Over either limit, the API returns 429 with RATE_LIMIT_EXCEEDED or QUOTA_EXCEEDED and a Retry-After header.

Provenance

Records include a provenance object with dataset_id, source_id, source_url, source_version, source_date, published_at, schema_version, validation_status and a stable record_id. The response's meta.datasets lists the active publication of each dataset it read, with its freshness. See coverage for sources and release schedules.

OpenAPI specifications