Developer guide

OilPriceAPI with JavaScript / Node.js

Start with one authenticated Brent request, verify the returned source timestamp, then build outward from the canonical quickstart.

Get API key Canonical quickstart

Runtime

Node.js 18+

Environment

OILPRICEAPI_KEY

Authentication

Authorization: Token YOUR_API_KEY

First request

/v1/prices/latest?by_code=BRENT_CRUDE_USD

First request

Prove the API path first

Store the key as OILPRICEAPI_KEY and run the request from a trusted server process. Do not expose the key in browser bundles, logs, notebooks, or shared documents.

No test-key prefix

OilPriceAPI does not issue special test keys. Use the keyless demo endpoint or fixtures for tests; keep customer keys out of CI.

typescript

SDK v1.0.2

npm install oilpriceapi

import { pathToFileURL } from "node:url";

import { OilPriceAPI } from "oilpriceapi";

export async function run() {
  const client = new OilPriceAPI({
    apiKey: process.env.OILPRICEAPI_KEY,
    baseUrl: process.env.OILPRICEAPI_BASE_URL,
    retries: 0,
  });
  const [price] = await client.getLatestPrices({ commodity: "BRENT_CRUDE_USD" });

  return {
    commodity: price.code,
    currency: price.currency,
    valueType: typeof price.price,
    timestampType: typeof price.created_at,
  };
}

if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
  console.log(JSON.stringify(await run()));
}

This exact server-side example is exercised by the official SDK's fixture and guarded production CI.

Universal curl

Compare your client with the contract

curl "https://api.oilpriceapi.com/v1/prices/latest?by_code=BRENT_CRUDE_USD" \
  -H "Authorization: Token YOUR_API_KEY"

Expected shape

Read the timestamp from the response

{
  "status": "success",
  "data": {
    "code": "BRENT_CRUDE_USD",
    "price": 78.41,
    "currency": "USD",
    "created_at": "2026-03-09T12:00:00.000Z",
    "type": "spot_price"
  }
}

Keyless first touch

Use demo data before signup

The demo route is the supported no-key path. It is rate limited and intentionally narrower than authenticated, account-entitled access.

curl "https://api.oilpriceapi.com/v1/demo/prices"

Open demo response

Recover without guessing

Result	Next action
401	Check that the header is exactly Authorization: Token YOUR_API_KEY.
402 / 403	The dataset may require a plan or account entitlement. Check pricing or contact support.
429	Read the rate-limit response and retry after the indicated reset; do not loop immediately.
Timeout / 5xx	Use a bounded timeout and exponential backoff. Keep the last valid source timestamp visible.

Executable recovery paths

Handle API failures by type

401Invalid or missing credentialView code

GET /v1/prices/latestTested SDK source

import { pathToFileURL } from "node:url";

import { AuthenticationError, OilPriceAPI } from "oilpriceapi";

export async function run() {
  const client = new OilPriceAPI({
    apiKey: process.env.OILPRICEAPI_KEY,
    baseUrl: process.env.OILPRICEAPI_BASE_URL,
    retries: 0,
  });

  try {
    await client.getLatestPrices({ commodity: "BRENT_CRUDE_USD" });
  } catch (error) {
    if (error instanceof AuthenticationError) {
      return { handled: true, statusCode: error.statusCode ?? 401 };
    }
    throw error;
  }

  throw new Error("Expected the API to reject the credential");
}

if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
  console.log(JSON.stringify(await run()));
}

403Dataset entitlementView code

GET /v1/prices/latestTested SDK source

import { pathToFileURL } from "node:url";

import { OilPriceAPI, OilPriceAPIError } from "oilpriceapi";

export async function run() {
  const client = new OilPriceAPI({
    apiKey: process.env.OILPRICEAPI_KEY,
    baseUrl: process.env.OILPRICEAPI_BASE_URL,
    retries: 0,
  });

  try {
    await client.getLatestPrices({ commodity: "BRENT_CRUDE_USD" });
  } catch (error) {
    if (error instanceof OilPriceAPIError && error.statusCode === 403) {
      return { handled: true, statusCode: error.statusCode };
    }
    throw error;
  }

  throw new Error("Expected the API to reject the account entitlement");
}

if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
  console.log(JSON.stringify(await run()));
}

429Request limit reachedView code

GET /v1/prices/latestTested SDK source

import { pathToFileURL } from "node:url";

import { OilPriceAPI, RateLimitError } from "oilpriceapi";

export async function run() {
  const client = new OilPriceAPI({
    apiKey: process.env.OILPRICEAPI_KEY,
    baseUrl: process.env.OILPRICEAPI_BASE_URL,
    retries: 0,
  });

  try {
    await client.getLatestPrices({ commodity: "BRENT_CRUDE_USD" });
  } catch (error) {
    if (error instanceof RateLimitError) {
      return { handled: true, statusCode: error.statusCode ?? 429 };
    }
    throw error;
  }

  throw new Error("Expected the API to enforce its request limit");
}

if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
  console.log(JSON.stringify(await run()));
}

TimeoutBounded timeoutView code

GET /v1/prices/latestTested SDK source

import { pathToFileURL } from "node:url";

import { OilPriceAPI, TimeoutError } from "oilpriceapi";

export async function run() {
  const client = new OilPriceAPI({
    apiKey: process.env.OILPRICEAPI_KEY,
    baseUrl: process.env.OILPRICEAPI_BASE_URL,
    retries: 0,
    timeout: 20,
  });

  try {
    await client.getLatestPrices({ commodity: "BRENT_CRUDE_USD" });
  } catch (error) {
    if (error instanceof TimeoutError) {
      return { handled: true, errorType: "TimeoutError" };
    }
    throw error;
  }

  throw new Error("Expected the request to time out");
}

if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
  console.log(JSON.stringify(await run()));
}

Current offer

7-day core commodity API trial

New accounts receive 10,000 trial requests without a credit card, followed by 200 requests per month on Free. Dataset access and limits vary by plan, source, and account entitlement.

Continue with quickstart API documentation