Getting Started with the Product Atlas API

The Product Atlas API is a read-only API that returns product details and attributes, across a curated set of retailers, using familiar field names and identifiers. Get started with the API using the following steps.

Base URL

https://atlas.usebutton.com/v1

Every endpoint in this reference is relative to that base URL. All requests and responses are JSON.

Getting your API key

API keys are issued via self-serve key creation. See general authentication for details. The API key you use to access Product Atlas API endpoints also allows you to access Button's other server-to-server API endpoints.

⚠️
❗️Keep your API key private
Only call the Product Atlas API from a server you control. Don't embed your key in a mobile app or public webpage, and don't commit it to source control.

Authentication

Send your API key on every request, using either header:

X-Api-Key: YOUR_API_KEY

A missing or invalid key returns 401. A valid key that isn't entitled to the request (for example, a retailer your organization isn't granted access to) returns 403.

Make your first request

curl https://atlas.usebutton.com/v1/retailers \
  -H "'X-Api-Key: YOUR_API_KEY"

{
  "retailers": [
    { "slug": "amazon", "name": "Amazon" },
    { "slug": "walmart", "name": "Walmart" }
  ]
}

This list is scoped to your organization and can change over time, so treat it as the live source of truth rather than hard-coding retailer slugs. See Retailer Coverage for more.

Data freshness and normalization

Field values are not yet fully normalized. The Product Atlas API is launching ahead of a full catalog normalization effort, so field completeness and formatting (casing, units, category taxonomy) currently varies by retailer. Use last_updated on a product as the freshness signal — don't assume a fixed refresh interval.

Fields a retailer didn't provide are omitted from the response entirely, rather than returned as null or an empty string.

Rate limits

Requests are rate-limited per organization. If you exceed the limit, you'll get a 429 with a Retry-After header telling you how many seconds to wait before retrying.

Exact request limits are still being finalized ahead of general availability. Build your integration to respect Retry-After rather than assuming a fixed number, and check with your Button representative for current guidance.

Errors

Every error response shares one shape:

{
  "error": {
    "code": "not_found",
    "message": "product not found"
  }
}

code is a stable, machine-readable value — branch your error handling on code, not on message, since the wording of message may change.

HTTP status	`code`	Meaning
`400`	`bad_request`	The request was malformed: a missing/invalid parameter, an unknown retailer slug, or a batch over the size limit.
`401`	`unauthorized`	The API key is missing or invalid.
`403`	`forbidden`	The key is valid, but not entitled to this request.
`404`	`not_found`	No matching product.
`429`	`rate_limited`	You're over your rate limit. Check `Retry-After`.
`500`	`internal_error`	Something went wrong on Button's side.
`502` / `504`	`upstream_error`	Button's internal catalog returned an error or timed out.

Getting help

Contact your Button account representative, or [email protected] for help integrating.