# data-api /v1 — agent docs

> Public API for Walmart marketplace data (item details, offers, sellers, search, reviews), served
> from a live mirror or fetched fresh on demand, plus bulk jobs and self-serve metering. This doc
> set is written for an AI coding agent implementing a client against this API: every operation has
> its own self-contained file with request/response examples and a copy-paste integration recipe.

## Start here

1. **Auth:** every request carries `Authorization: Bearer dak_live_<prefix>_<secret>`. See
   [guides/authentication.md](guides/authentication.md).
2. **Base URL:** `https://api.data-api.dev` (production) or `https://sandbox.api.data-api.dev` (test keys, no
   charges).
3. **`maxAge` and pricing:** every sync read takes an optional `maxAge` (seconds) — the oldest
   observation you'll accept before a fresh fetch happens. Omit it for the cheapest answer (mirror if
   any copy exists), pass `0` to always fetch fresh. See [guides/pricing-and-maxage.md](guides/pricing-and-maxage.md).
4. **You are never charged on failure.** Every error response — validation, auth, rate limit,
   upstream failure/timeout — charges nothing. There are no refunds because there is nothing to
   refund. See [guides/errors.md](guides/errors.md).
5. **Retry/backoff per error code:** `429` → back off until `Retry-After`; `502`/`504` → retry with
   backoff; `400`/`401`/`403`/`404` → fix the request, don't retry unchanged; `402` → don't retry until
   the balance changes. Full table in [guides/errors.md](guides/errors.md).
6. **Idempotency:** every `POST` accepts an `Idempotency-Key` header — send a fresh UUID per
   *logical* request and reuse it only when retrying the exact same request.
7. **Pagination:** paged endpoints take a 1-based `page` query param; `search`/`reviews` signal the
   end with `rowCount: 0`, `walmart.seller_items` additionally reports `maxPage`. See
   [guides/pagination.md](guides/pagination.md).
8. **Picking an operation:** sync endpoints (`GET /v1/walmart/...`) answer one key per call, in line
   with the request. `POST /v1/jobs` runs one `op` (a site-qualified id like `walmart.item`, the
   same id the matching sync operation file below is named after) over many keys at once — use it
   for bulk work instead of looping sync calls. See [guides/bulk-jobs.md](guides/bulk-jobs.md).

## Operations

- [`GET /v1/walmart/items/{itemId}`](operations/walmart.item.md) (`walmart.item`) — Get item details and Buy Box.
- [`GET /v1/walmart/items/{itemId}/offers`](operations/walmart.offers.md) (`walmart.offers`) — Get all-seller offers for an item.
- [`GET /v1/walmart/sellers/{sellerId}`](operations/walmart.seller.md) (`walmart.seller`) — Get a seller record.
- [`GET /v1/walmart/sellers/{sellerId}/items`](operations/walmart.seller_items.md) (`walmart.seller_items`) — Get a page of a seller's catalog.
- [`GET /v1/walmart/search`](operations/walmart.search.md) (`walmart.search`) — Search, one page of results.
- [`GET /v1/walmart/items/{itemId}/reviews`](operations/walmart.reviews.md) (`walmart.reviews`) — Get a page of an item's reviews.
- [`POST /v1/jobs`](operations/createJob.md) (`createJob`) — Submit a bulk job.
- [`GET /v1/jobs/{id}`](operations/getJob.md) (`getJob`) — Get job status.
- [`GET /v1/jobs/{id}/results`](operations/getJobResults.md) (`getJobResults`) — Get job results, paged.
- [`GET /v1/usage`](operations/getUsage.md) (`getUsage`) — Get self-serve usage metering.
- [`GET /v1/balance`](operations/getBalance.md) (`getBalance`) — Get current credit balance.

## Guides

- [guides/authentication.md](guides/authentication.md)
- [guides/errors.md](guides/errors.md)
- [guides/pricing-and-maxage.md](guides/pricing-and-maxage.md)
- [guides/pagination.md](guides/pagination.md)
- [guides/bulk-jobs.md](guides/bulk-jobs.md)
- [guides/rate-limits.md](guides/rate-limits.md)

## Machine-readable OpenAPI

- Full document: [`/openapi.json`](/openapi.json)
- Per-operation slice: `/docs/agents/openapi/<operation-id>.json` (e.g. `/docs/agents/openapi/walmart.item.json`)