Oil Price API Discovery API

openapi: 3.2.0
info:
  title: Oil Price API V1 Discovery 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: Discovery
  description: No-key representative sample endpoints for API discovery.
paths:
  /v1/status:
    get:
      tags:
      - Discovery
      operationId: getPublicOperationalStatus
      summary: Read the latest public operational status snapshot
      description: 'No API key is required. Health calculations run in a background worker;

        this request only reads the latest snapshot. The existing ten-minute

        cache warmer refreshes it, and reads older than five minutes request a

        refresh. `last_checked` is the calculation time, not the request time.

        Missing or invalid snapshots, snapshots at least fifteen minutes old,

        and cache failures return 503 with unknown health and `Retry-After: 60`.'
      security: []
      parameters:
      - name: include
        in: query
        required: false
        schema:
          type: string
          enum:
          - commodities
          example: commodities
        description: Include each tier's commodity breakdown.
      responses:
        '200':
          description: A recent operational status snapshot.
          content:
            application/json:
              schema:
                type: object
                required:
                - status
                - data
                properties:
                  status:
                    type: string
                    enum:
                    - success
                  data:
                    type: object
                    properties:
                      operational:
                        type: boolean
                      status:
                        type: string
                        enum:
                        - operational
                        - degraded
                        - outage
                      last_checked:
                        type: string
                        format: date-time
                      score:
                        type: number
                      grade:
                        type: string
                      message:
                        type: string
                      components:
                        type: object
                        additionalProperties:
                          type: string
                          enum:
                          - operational
                          - degraded
                          - outage
                          - unknown
                      affected_components:
                        type: array
                        items:
                          type: string
                      tiers:
                        type: object
                        additionalProperties:
                          type: object
        '429':
          description: The shared IP or token burst limit was reached. Retry after the delay in the response.
        '503':
          description: Status checks are unavailable; retry after the stated delay.
          headers:
            Retry-After:
              schema:
                type: integer
                example: 60
          content:
            application/json:
              example:
                status: unavailable
                data:
                  operational: null
                  status: unknown
                  message: Status checks are temporarily unavailable. Please retry in a minute.
                  last_checked: null
  /sample:
    get:
      summary: No-key sample commodity prices
      operationId: getPublicSamplePrices
      tags:
      - Discovery
      description: Public no-auth sample endpoint for agent discovery. Returns representative public prices only; organization-owned private rows are excluded.
      security: []
      parameters:
      - name: by_code
        in: query
        required: false
        description: Representative commodity code to sample.
        schema:
          type: string
          enum:
          - WTI_USD
          - BRENT_CRUDE_USD
          - NATURAL_GAS_USD
          example: WTI_USD
      - name: measure
        in: query
        required: false
        description: Sample measurement to return.
        schema:
          type: string
          enum:
          - spot_price
          - change_24h
          - source_timestamp
          default: spot_price
          example: spot_price
      responses:
        '200':
          description: Representative public sample prices
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '422':
          description: Unsupported code or measure
        '429':
          description: Anonymous sample rate limit exceeded
  /v1/sample:
    get:
      summary: No-key sample commodity prices
      operationId: getV1PublicSamplePrices
      tags:
      - Discovery
      description: Public no-auth sample endpoint for agent discovery. Returns representative public prices only; organization-owned private rows are excluded.
      security: []
      parameters:
      - name: by_code
        in: query
        required: false
        description: Representative commodity code to sample.
        schema:
          type: string
          enum:
          - WTI_USD
          - BRENT_CRUDE_USD
          - NATURAL_GAS_USD
          example: WTI_USD
      - name: measure
        in: query
        required: false
        description: Sample measurement to return.
        schema:
          type: string
          enum:
          - spot_price
          - change_24h
          - source_timestamp
          default: spot_price
          example: spot_price
      responses:
        '200':
          description: Representative public sample prices
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '422':
          description: Unsupported code or measure
        '429':
          description: Anonymous sample rate limit exceeded
components:
  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