# 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](https://docs.oilpriceapi.com/agent-quickstart.md) is generated from this page for agents that do not render HTML. ## Discover the contract | Resource | Purpose | | --- | --- | | [OpenAPI YAML](https://api.oilpriceapi.com/swagger.yaml) | Backend-published operations, parameters, authentication, and response schemas | | [Extended docs OpenAPI](https://docs.oilpriceapi.com/openapi.yaml) | Adds documented operations not yet present in the backend spec; verify the endpoint reference before generating clients | | [Documentation index](https://docs.oilpriceapi.com/llms.txt) | Find task-specific reference pages | | [Product facts](https://api.oilpriceapi.com/product-facts.json) | Current reviewed offer, canonical request, and product qualifications | | [Commodity catalog](https://docs.oilpriceapi.com/api-reference/commodities/list) | Discover supported codes and their currencies and units | | [Service status](https://status.oilpriceapi.com) | Check an outage before retrying | 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: ```bash 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`. ```bash 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](https://docs.oilpriceapi.com/#quick-start) 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](https://docs.oilpriceapi.com/api-reference/prices/latest). - 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 | Response or failure | Next action | | --- | --- | | 400 / unknown code | Correct parameters using the catalog. Do not retry unchanged input. | | 401 | Check the key and `Token` header. Ask the account owner to repair credentials; do not print them. | | 402 / 403 | Read the error and inspect entitlement or quota. Explain the required account action; do not purchase or upgrade automatically. | | 404 | Verify the operation path and identifier against the endpoint reference. | | 429 | Honor `Retry-After` when provided. Inspect rate/quota headers; a spent quota may require waiting for its reset rather than short retries. | | Timeout / transient 5xx | For reads, use bounded exponential backoff with jitter; for example, at most two retries within the caller's deadline. | | HTTP 200 with missing or stale data | Report the limitation or use a clearly dated cached observation when the application permits it. Do not invent a value. | 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](https://docs.oilpriceapi.com/guides/error-recovery) and [rate limiting](https://docs.oilpriceapi.com/guides/rate-limiting). ## Connect through MCP The maintained [oilpriceapi-mcp package](https://www.npmjs.com/package/oilpriceapi-mcp) provides tools for compatible clients. Follow the [MCP setup guide](https://www.oilpriceapi.com/ai-integrations#mcp-setup) 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](https://docs.oilpriceapi.com/api-reference/agents/mcp-agent-subscriptions) 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](https://docs.oilpriceapi.com/guides/production-checklist) and [data usage policy](https://www.oilpriceapi.com/legal/data-usage) for the intended use.