Oil Price API Storage API

openapi: 3.2.0
info:
  title: Oil Price API V1 Storage 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: Storage
  description: Petroleum and natural-gas storage datasets.
paths:
  /v1/storage/cushing:
    get:
      summary: Get Cushing oil storage data
      operationId: getV1StorageCushing
      tags:
      - Storage
      description: 'Latest-available Cushing, Oklahoma oil storage intelligence with market signals.

        Cushing is the delivery point for WTI crude and North America''s largest oil storage hub.

        **Premium Feature** - Scale tier required.'
      security:
      - ApiKeyAuth: []
      responses:
        '200':
          description: Cushing storage data with analytics
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CushingStorageResponse'
        '401':
          description: Unauthorized
        '403':
          description: Premium access required
        '500':
          $ref: '#/components/responses/InternalServerError'
components:
  schemas:
    CushingStorageResponse:
      type: object
      properties:
        status:
          type: string
          example: success
        data:
          type: object
          properties:
            current_storage:
              type: number
              example: 42500000
              description: Current storage in barrels
            capacity:
              type: number
              example: 76000000
              description: Total capacity in barrels
            utilization:
              type: number
              example: 55.92
              description: Utilization percentage
            week_change:
              type: number
              example: -1250000
              description: Week-over-week change in barrels
            month_change:
              type: number
              example: -3500000
              description: Month-over-month change in barrels
            market_signal:
              type: string
              enum:
              - bullish
              - bearish
              - neutral
              example: bullish
            trend:
              type: string
              enum:
              - building
              - drawing
              - stable
              example: drawing
            updated_at:
              type: string
              format: date-time
    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