OilPriceAPI for AI Agents

Use this guide to make a first read-only request, then discover the operations your application needs. A plain Markdown version is generated from this page for agents that do not render HTML.

Discover the contract

Use operation IDs and parameter schemas from the selected spec. Do not derive endpoint names from marketing page URLs, invent commodity codes, or assume that an operation in a schema is included in the current account's plan.

Make a first read-only request

Try the public demo without credentials:

curl --fail-with-body --max-time 10 "https://api.oilpriceapi.com/v1/demo/prices"

The demo returns data.prices[] and data.meta. Read the demo limit from data.meta.rate_limit; demo limits are separate from authenticated account quotas. The demo is a separate contract, not an exact fixture for every authenticated endpoint.

For an authenticated request, have the account owner provision a key and set OILPRICEAPI_KEY in the process environment or a secret manager. Keep it out of chat prompts, browser code, source control, and logs. The API origin is https://api.oilpriceapi.com; the versioned base URL is https://api.oilpriceapi.com/v1.

curl --fail-with-body --max-time 10 \
  "https://api.oilpriceapi.com/v1/prices/latest?by_code=BRENT_CRUDE_USD" \
  -H "Authorization: Token ${OILPRICEAPI_KEY:?Set OILPRICEAPI_KEY first}"

The key header uses Token. Send credentials only to the intended API origin. See the complete Python, Node.js, and Go examples for environment lookup, HTTP errors, and timeouts.

Interpret the result before using it

• A single by_code returns the price object at data. Multiple codes return an array at data.prices; match by code and explicitly handle missing codes.
• Check HTTP status and the JSON success/error envelope before reading prices. HTTP 200 alone is not proof that the requested dataset is present or usable. Validate the returned code and every field you consume: a numeric, finite price (zero is valid) and a nonempty string formatted in the first-request examples. Reject missing, null, or incorrectly typed values.
• Use each endpoint's schema. The demo uses updated_at; authenticated latest prices use as_of for the original source observation and collected_at for ingestion time. A recent created_at can reflect collection or a heartbeat; never use it as a fallback for missing as_of. Missing or invalid source time is unknown, not current. See the latest-price reference.
• Preserve synthetic: true for carried-forward/heartbeat values and every stale signal: stale: true, data_status: "stale", or freshness.status: "stale". Any of these must retain a stale warning even if another field says false. Missing flags mean unknown, not false.
• Retain the code, currency, unit, timestamp, source, and available freshness fields with each value. State when a timestamp or unit is unavailable. Never replace a missing source timestamp with the time the request ran.
• A successful request can contain stale observations. Evaluate freshness against the source's publication schedule and the application's tolerance. Explain stale or missing data before making a claim about current prices.
• Do not equate spot prices, front-month futures, retail fuel, and assessments. Verify the selected series in the catalog before comparing or calculating.

Recover without retry loops

These retry bounds are integration recommendations, not API guarantees. Cache per code and parameters within the application's freshness tolerance. Persist pagination cursors and stop on completion or a configured page/request budget. Preserve a returned request ID for support, with credentials redacted. See error recovery and rate limiting.

Connect through MCP

The maintained oilpriceapi-mcp package provides tools for compatible clients. Follow the MCP setup guide for the client configuration, then list the server's tools to verify the installed version's capabilities. Use the client's credential configuration for the key. Validate the client-specific configuration format and package requirements.

Begin with read-only price discovery. Tools that create or delete watches, webhooks, alerts, or keys change account state. Obtain explicit authorization for the concrete change and its recurring behavior before executing them. An API key's technical permissions do not establish the user's intent.

After a timed-out write, inspect existing resources before retrying. Do not assume an idempotency header is supported unless the operation documents it. The agent subscriptions guide describes persistent watches and cursor-based event polling.

Verify before production

Exercise missing credentials, invalid codes, denied entitlement, rate limits, timeouts, missing values, stale timestamps, and the recovery path as well as success. Check account-specific access and limits before scheduling polling. Review the production checklist and data usage policy for the intended use.