Oil Price API Webhooks API

openapi: 3.2.0
info:
  title: Oil Price API V1 Webhooks 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: Webhooks
  description: Webhook endpoint configuration and delivery history.
paths:
  /v1/webhooks:
    get:
      summary: List webhook endpoints
      operationId: getV1Webhooks
      tags:
      - Webhooks
      description: 'Get all configured webhook endpoints for the authenticated user.

        **Requires the Scale plan.**'
      security:
      - ApiKeyAuth: []
      responses:
        '200':
          description: List of webhook endpoints
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookListResponse'
        '403':
          description: Insufficient plan - Scale required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InsufficientPlanError'
        '500':
          $ref: '#/components/responses/InternalServerError'
    post:
      summary: Create webhook endpoint
      operationId: postV1Webhooks
      tags:
      - Webhooks
      description: 'Create a new webhook endpoint to receive event-driven updates.

        **Requires the Scale plan.**'
      security:
      - ApiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateWebhookRequest'
      responses:
        '201':
          description: Webhook endpoint created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookResponse'
        '400':
          description: Bad request - Invalid webhook configuration
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Insufficient plan - Scale required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InsufficientPlanError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /v1/webhooks/{webhook_id}:
    get:
      summary: Get webhook endpoint details
      operationId: getV1WebhooksByWebhookId
      tags:
      - Webhooks
      description: 'Get details of a specific webhook endpoint.

        **Requires the Scale plan.**'
      parameters:
      - name: webhook_id
        in: path
        required: true
        description: Webhook endpoint ID
        schema:
          type: string
          example: wh_1a2b3c4d5e6f
      security:
      - ApiKeyAuth: []
      responses:
        '200':
          description: Webhook endpoint details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookResponse'
        '404':
          description: Webhook not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Insufficient plan - Scale required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InsufficientPlanError'
        '500':
          $ref: '#/components/responses/InternalServerError'
    put:
      summary: Update webhook endpoint
      operationId: putV1WebhooksByWebhookId
      tags:
      - Webhooks
      description: 'Update an existing webhook endpoint configuration.

        **Requires the Scale plan.**'
      parameters:
      - name: webhook_id
        in: path
        required: true
        description: Webhook endpoint ID
        schema:
          type: string
          example: wh_1a2b3c4d5e6f
      security:
      - ApiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateWebhookRequest'
      responses:
        '200':
          description: Webhook endpoint updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookResponse'
        '404':
          description: Webhook not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Insufficient plan - Scale required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InsufficientPlanError'
        '500':
          $ref: '#/components/responses/InternalServerError'
    delete:
      summary: Delete webhook endpoint
      operationId: deleteV1WebhooksByWebhookId
      tags:
      - Webhooks
      description: 'Delete a webhook endpoint.

        **Requires the Scale plan.**'
      parameters:
      - name: webhook_id
        in: path
        required: true
        description: Webhook endpoint ID
        schema:
          type: string
          example: wh_1a2b3c4d5e6f
      security:
      - ApiKeyAuth: []
      responses:
        '204':
          description: Webhook endpoint deleted successfully
        '404':
          description: Webhook not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Insufficient plan - Scale required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InsufficientPlanError'
        '500':
          $ref: '#/components/responses/InternalServerError'
components:
  schemas:
    WebhookResponse:
      type: object
      properties:
        success:
          type: boolean
          example: true
        webhook:
          $ref: '#/components/schemas/Webhook'
    PaginationMeta:
      type: object
      properties:
        current_page:
          type: integer
          example: 1
        per_page:
          type: integer
          example: 100
        total_pages:
          type: integer
          example: 5
        total_count:
          type: integer
          example: 450
        next_page:
          type:
          - integer
          - 'null'
          example: 2
        prev_page:
          type:
          - integer
          - 'null'
          example: null
    InsufficientPlanError:
      type: object
      properties:
        status:
          type: string
          example: error
        error:
          type: object
          properties:
            code:
              type: string
              example: INSUFFICIENT_PLAN
            message:
              type: string
              example: Drilling intelligence data is available exclusively to Scale subscribers
            details:
              type: object
              properties:
                required_tier:
                  type: string
                  example: reservoir_mastery
                upgrade_url:
                  type: string
                  example: https://oilpriceapi.com/pricing
                current_plan:
                  type: string
                  example: free
    UpdateWebhookRequest:
      type: object
      properties:
        url:
          type: string
          format: uri
          example: https://api.yourcompany.com/webhooks/oilpriceapi
          description: Webhook endpoint URL (must be HTTPS)
        events:
          type: array
          items:
            type: string
            enum:
            - alert.triggered
            - price.updated
            - price.significant_change
            - drilling.rig_count.updated
            - drilling.frac_spread.updated
            - drilling.well_permit.updated
            - drilling.duc_well.updated
            - api.limit.warning
            - api.limit.exceeded
          example:
          - price.updated
          - drilling.rig_count.updated
          description: Events to subscribe to
        active:
          type: boolean
          example: true
          description: Enable or disable the webhook
        description:
          type: string
          example: Production webhook for price updates
          description: Optional description for the webhook
    WebhookListResponse:
      type: object
      properties:
        success:
          type: boolean
          example: true
        webhooks:
          type: array
          items:
            $ref: '#/components/schemas/Webhook'
        meta:
          $ref: '#/components/schemas/PaginationMeta'
    CreateWebhookRequest:
      type: object
      required:
      - url
      - events
      properties:
        url:
          type: string
          format: uri
          example: https://api.yourcompany.com/webhooks/oilpriceapi
          description: Webhook endpoint URL (must be HTTPS)
        events:
          type: array
          minItems: 1
          items:
            type: string
            enum:
            - alert.triggered
            - price.updated
            - price.significant_change
            - drilling.rig_count.updated
            - drilling.frac_spread.updated
            - drilling.well_permit.updated
            - drilling.duc_well.updated
            - api.limit.warning
            - api.limit.exceeded
          example:
          - price.updated
          - drilling.rig_count.updated
          description: Events to subscribe to. alert.triggered receives threshold/volatility alerts only when that alert selects this exact endpoint URL on the same account.
        description:
          type: string
          example: Production webhook for price updates
          description: Optional description for the webhook
    Webhook:
      type: object
      properties:
        id:
          type: string
          example: wh_1a2b3c4d5e6f
        url:
          type: string
          format: uri
          example: https://api.yourcompany.com/webhooks/oilpriceapi
        events:
          type: array
          items:
            type: string
            enum:
            - price.updated
            - price.significant_change
            - drilling.rig_count.updated
            - drilling.frac_spread.updated
            - drilling.well_permit.updated
            - drilling.duc_well.updated
            - api.limit.warning
            - api.limit.exceeded
          example:
          - price.updated
          - drilling.rig_count.updated
        secret:
          type: string
          example: whsec_1234567890abcdef
          description: HMAC signing secret for verification
        active:
          type: boolean
          example: true
        created_at:
          type: string
          format: date-time
          example: '2025-08-10T10:30:00Z'
        updated_at:
          type: string
          format: date-time
          example: '2025-08-10T10:30:00Z'
        last_delivery:
          type: object
          properties:
            attempted_at:
              type: string
              format: date-time
              example: '2025-08-10T12:00:00Z'
            status:
              type: string
              enum:
              - success
              - failed
              - pending
              example: success
            response_code:
              type: integer
              example: 200
    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