Oil Price API Demo (No Auth) API

openapi: 3.2.0
info:
  title: Oil Price API V1 Demo (No Auth) API
  version: v1
  description: 'Source-aware oil and energy data API. Check each endpoint''s source timestamp,

    coverage, and freshness fields before using a response in a time-sensitive workflow. ## Authentication


    API-key endpoints use `Authorization: Token YOUR_API_KEY`. Operations that do

    not require an API key explicitly declare an empty security requirement. `/v1/demo/prices` is keyless. ## Rate Limiting


    - Free tier: 50 requests per day

    - Paid tiers have plan-specific monthly quotas. - `402` means the allowance is exhausted: a Free or post-trial caller

    must upgrade, and a paid plan has used its monthly allowance (the body

    carries `MONTHLY_QUOTA_EXCEEDED` and reset metadata, so do not retry before

    the reset). `429` means an active-trial allowance or a rolling rate limit

    (for example the hourly safety limit) is exceeded; retry `429` and transient

    `5xx` responses with bounded backoff. - Website login and signup (`POST /sessions` and `POST /users`) also enforce

    authentication-attempt limits independently of API plan quotas: 3 attempts

    per normalized email address in 5 minutes, and 3 attempts per minute per

    verified visitor IP. Requests without a verified proxy identity retain

    the existing 20 requests/minute IP ceiling. A `429` on these routes means

    wait for `Retry-After` before retrying; upgrading a plan does not remove

    authentication-attempt limits. Futures curves are never refused because a market is closed or a session has

    just reopened. The last available data is served with `metadata.freshness_status`,

    `metadata.stale`, `metadata.latest_data_at` and `metadata.stale_by_minutes`:

    `outside_market_hours` while the venue is closed (weekend, daily break,

    holiday); `awaiting_first_print` for the first 30 minutes of a new session

    while only a valid prior close exists; `degraded` when the market is open and

    the source is behind. None of these is a fresh trade; source timestamps remain

    unchanged. Data older than the 96-hour serving bound is refused with 503. Gasoil reports `metadata.freshness_status: no_recent_trades` when the

    benchmark contract has not traded within 30 minutes but our collector confirmed

    the quote within that window and the curve printed within 90 minutes. The last

    trade is served with its true `latest_data_at` and `stale_by_minutes`, plus

    `source_checked_at` and `curve_latest_trade_at`. Paid monthly-cap responses include `retry_guidance`: immediate retries cannot

    restore quota. When a representative sample supports it, `batching_opportunity`

    describes an estimated lower request rate; batching does not restore an already

    exhausted allowance. It may replace an unnecessary upgrade recommendation. ## Continuous futures coverage


    On `/v1/futures/continuous/brent`, `/v1/futures/continuous/wti` and their

    `/historical` routes, `metadata.history_available_from` is the earliest

    stored public continuous futures source date, falling back to collection

    date for older imports without a source timestamp. It is a date string or

    null when no public observations exist. Coverage metadata is cached for up

    to one hour and does not promise observations or volume on every later date. It describes the archive independently of the request''s date range; account

    depth limits remain in `metadata.history_window` on historical responses. Latest-response `metadata.total_historical_records` counts stored public

    snapshots, including revisions, rather than distinct source dates. Latest

    quotes and their prior-day comparisons exclude private organization rows

    and other price types. Repeated source timestamps select the later collected

    revision; the oldest metadata/response cache formats are no longer used. ## Spread and indicator query parameters


    Spread and indicator endpoints reject unrecognized query parameter names with

    HTTP 400 and `error.code: UNKNOWN_PARAMETERS`, after authentication and access

    checks. The error includes `unrecognized_parameters`, `allowed_parameters`,

    and a `suggestions` map for recognized date-name mistakes; values are not

    echoed.'
  contact:
    name: Oil Price API Support
    email: support@oilpriceapi.com
    url: https://oilpriceapi.com
  license:
    name: Commercial License
    url: https://oilpriceapi.com/terms
servers:
- url: https://api.oilpriceapi.com
  description: Production server
tags:
- name: Demo (No Auth)
  description: Keyless representative responses for evaluation.
paths:
  /v1/demo/prices:
    get:
      summary: Get demo prices (No authentication required)
      operationId: getV1DemoPrices
      tags:
      - Demo (No Auth)
      description: '**Start here - no API key needed!**


        Returns the latest prices for free-tier commodities. Perfect for testing the API

        before signing up or for embedding in documentation examples.


        **Available commodities:**

        - Brent Crude Oil (BRENT_CRUDE_USD)

        - WTI Crude Oil (WTI_USD)

        - Natural Gas Henry Hub (NATURAL_GAS_USD)

        - Gold (GOLD_USD)

        - Gold AM/PM Fix (GOLD_AM_USD, GOLD_AM_GBP, GOLD_AM_EUR, GOLD_PM_USD, GOLD_PM_GBP, GOLD_PM_EUR)

        - Silver (SILVER_USD)

        - Silver Fix (SILVER_FIX_USD, SILVER_FIX_GBP, SILVER_FIX_EUR)

        - EUR/USD (EUR_USD)

        - USD/NOK (USD_NOK)

        - EUR/NOK (EUR_NOK)

        - GBP/USD (GBP_USD)

        - Heating Oil (HEATING_OIL_USD)

        - Gasoline RBOB (GASOLINE_USD)

        - Diesel (DIESEL_USD)


        **Rate limit:** 25 requests per day, per IP (no key required). The count resets at 00:00 UTC.


        **Batch size:** up to 20 codes per request (`?codes=A,B,C`), counted as a single

        request — the same cap the authenticated `/v1/prices/latest` enforces. More than

        20 returns `400`. With no parameters the endpoint returns the first 20 free codes.


        **Need more?** Get a free API key for full access.'
      security: []
      responses:
        '200':
          description: Demo price data with code examples
          headers:
            X-RateLimit-Limit:
              description: Maximum requests per UTC day, per IP
              schema:
                type: integer
                example: 25
            X-RateLimit-Remaining:
              description: Remaining requests today (UTC)
              schema:
                type: integer
            X-Demo-Mode:
              description: Indicates demo mode is active
              schema:
                type: string
                example: 'true'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DemoPricesResponse'
              example:
                status: success
                data:
                  prices:
                  - code: BRENT_CRUDE_USD
                    name: Brent Crude Oil
                    price: 75.42
                    currency: USD
                    updated_at: '2026-01-10T15:30:00Z'
                  - code: WTI_USD
                    name: WTI Crude Oil
                    price: 71.28
                    currency: USD
                    updated_at: '2026-01-10T15:30:00Z'
                  meta:
                    demo_mode: true
                    rate_limit: 25 requests per day, per IP
                    signup_url: https://www.oilpriceapi.com/signup
                  examples:
                    curl: curl -X GET "https://api.oilpriceapi.com/v1/demo/prices"
                    python: 'import requests

                      response = requests.get("https://api.oilpriceapi.com/v1/demo/prices")

                      print(response.json())

                      '
                    javascript: "fetch(\"https://api.oilpriceapi.com/v1/demo/prices\")\n  .then(r => r.json())\n  .then(console.log)\n"
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Rate limit exceeded
                  message:
                    type: string
                    example: 'Demo limit reached: 25 requests per day from this IP. No API key is needed to use the demo — this limit exists so it stays available to everyone.'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /v1/demo/prices/{code}:
    get:
      summary: Get single demo commodity price
      operationId: getV1DemoPricesByCode
      tags:
      - Demo (No Auth)
      description: 'Get the latest price for a specific free-tier commodity.


        **No authentication required.**


        Only free-tier commodities are available. For premium commodities,

        sign up for a free API key.'
      security: []
      parameters:
      - name: code
        in: path
        required: true
        description: Commodity code (must be a free-tier commodity)
        schema:
          type: string
          enum:
          - BRENT_CRUDE_USD
          - WTI_USD
          - NATURAL_GAS_USD
          - GOLD_USD
          - SILVER_USD
          - PLATINUM_USD
          - PALLADIUM_USD
          - COPPER_USD
          - GOLD_AM_USD
          - GOLD_AM_GBP
          - GOLD_AM_EUR
          - GOLD_PM_USD
          - GOLD_PM_GBP
          - GOLD_PM_EUR
          - SILVER_FIX_USD
          - SILVER_FIX_GBP
          - SILVER_FIX_EUR
          - EUR_USD
          - USD_NOK
          - EUR_NOK
          - GBP_USD
          - HEATING_OIL_USD
          - GASOLINE_USD
          - DIESEL_USD
          example: BRENT_CRUDE_USD
      responses:
        '200':
          description: Single commodity price
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: success
                  data:
                    type: object
                    properties:
                      code:
                        type: string
                        example: BRENT_CRUDE_USD
                      name:
                        type: string
                        example: Brent Crude Oil
                      price:
                        type: number
                        format: float
                        example: 75.42
                      currency:
                        type: string
                        example: USD
                      updated_at:
                        type: string
                        format: date-time
        '403':
          description: Premium commodity requested
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: fail
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        example: PREMIUM_COMMODITY
                      message:
                        type: string
                        example: PERMIAN_DUC_WELLS is a premium commodity. Sign up for a free API key to access all commodities.
                      signup_url:
                        type: string
                        example: https://www.oilpriceapi.com/signup
        '500':
          $ref: '#/components/responses/InternalServerError'
components:
  schemas:
    DemoPricesResponse:
      type: object
      description: Response from demo API endpoint (no authentication required)
      properties:
        status:
          type: string
          example: success
        data:
          type: object
          properties:
            prices:
              type: array
              items:
                $ref: '#/components/schemas/DemoPrice'
            meta:
              type: object
              properties:
                demo_mode:
                  type: boolean
                  example: true
                rate_limit:
                  type: string
                  example: 25 requests per day, per IP
                signup_url:
                  type: string
                  example: https://www.oilpriceapi.com/signup
                documentation_url:
                  type: string
                  example: https://docs.oilpriceapi.com
            examples:
              type: object
              properties:
                curl:
                  type: string
                python:
                  type: string
                javascript:
                  type: string
    DemoPrice:
      type: object
      description: 'Price data returned from demo endpoints. WTI and Brent use the same benchmark

        selector as authenticated latest prices, including freshness and rollover policy.

        Missing or failed benchmark selection returns a null price and unavailable status.

        '
      properties:
        code:
          type: string
          description: Commodity code
          example: BRENT_CRUDE_USD
        name:
          type: string
          description: Human-readable commodity name
          example: Brent Crude Oil
        price:
          type:
          - number
          - 'null'
          format: float
          description: Selected price, or null when unavailable
          example: 75.42
        currency:
          type: string
          description: Price currency
          example: USD
        updated_at:
          type:
          - string
          - 'null'
          format: date-time
          description: Collection time, or null when unavailable. See benchmark.observed_at for source market time.
        benchmark:
          $ref: '#/components/schemas/PriceBenchmark'
        stale:
          type: boolean
          description: Whether the selected observation is stale under the commodity's freshness policy
        data_status:
          type: string
          description: Freshness verdict when evaluated, or unavailable when no benchmark can be selected
        message:
          type: string
          description: Recovery guidance when the price is unavailable
        source:
          type: string
          description: Data source
          example: OilPriceAPI
    PriceBenchmark:
      type: object
      description: 'Semantic identity and provenance for WTI or Brent benchmark prices. Explicit

        contract identity is included only when known. WTI retains its early-roll

        policy; the selected delivery month may differ from the earliest unexpired

        contract. Compare contract_month and observed_at when comparing quotes.

        '
      properties:
        id:
          type: string
          description: Stable benchmark identifier
          example: nymex_wti_front_month
        name:
          type: string
          description: Benchmark instrument name
        instrument_type:
          type: string
          example: front_month_futures
        quote_type:
          type: string
          example: indicative_last_price
        unit:
          type: string
          example: barrel
        contract_month:
          type: string
          pattern: ^\d{4}-(0[1-9]|1[0-2])$
          description: Selected delivery month when explicitly known; omitted for an unidentified publisher-managed contract
          example: 2026-12
        roll_method:
          type: string
          description: How the selected observation identifies its contract
          example: explicit_contract_curve
        roll_signal:
          type: string
          description: Stored signal used in contract selection, when available. A signal does not by itself mean a roll occurred.
          example: volume
        observed_at:
          type:
          - string
          - 'null'
          format: date-time
          description: Source market observation time; null when unavailable, never substituted with collection time
        observation_time_basis:
          type: string
          enum:
          - upstream_market
          - unavailable
        collected_at:
          type: string
          format: date-time
          description: Time the selected price row was collected
        source_tier:
          type: string
          description: Selection tier of the observation
    ErrorResponse:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              description: Machine-readable error code (e.g. UNAUTHORIZED, NOT_FOUND, INVALID_PARAMETER).
              example: UNAUTHORIZED
            message:
              type: string
              example: 'Missing or invalid API key. Include header: Authorization: Token YOUR_API_KEY'
            status:
              type: integer
              example: 401
            request_id:
              type: string
              example: fa0e389f-ca86-47b2-b167-2b4645a2fb8b
            docs:
              type: string
              example: https://docs.oilpriceapi.com#UNAUTHORIZED
            signup_url:
              type:
              - string
              - 'null'
              example: https://www.oilpriceapi.com/auth/signup
            demo_endpoint:
              type:
              - string
              - 'null'
              example: /v1/demo/prices
  responses:
    InternalServerError:
      description: Unexpected server error. Retry transient failures with bounded backoff and retain the request ID when contacting support.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: Authorization
      description: 'API key as: Authorization: Token YOUR_API_KEY'
externalDocs:
  description: OilPriceAPI developer documentation
  url: https://docs.oilpriceapi.com