> For the complete documentation index, see [llms.txt](https://docs.peakcommerce.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.peakcommerce.com/developers/api-reference/api-reference.md). # Overview The PeakCommerce **Agent API** is a RESTful, JSON, action-oriented API under `/api/v1`. It is designed equally for human-built integrations and for AI agents — every response includes a `nextActions` array describing the operations available from the returned resource (HATEOAS). This index page and the per-tag pages below are generated from the OpenAPI spec in `server/routes/v1/discovery.ts` by `npm run docs:api` and kept in sync with the route code by `npm run docs:check`. ## Quick links (hand-written guides) * [Authentication](/developers/api-reference/authentication.md) * [Base URL & environments](/developers/api-reference/base-url.md) * [Errors](/developers/api-reference/errors.md) * [Pagination](/developers/api-reference/pagination.md) * [Rate limits](/developers/api-reference/rate-limits.md) * [Webhooks overview](/developers/api-reference/webhooks-overview.md) * [OpenAPI 3.1 spec (JSON)](https://api.peakcommerce.com/api/v1/openapi.json) Detailed per-resource reference pages live under [`reference/`](https://gitlab.com/peak-hercules/peak-help-docs/-/blob/main/developers/api-reference/reference/README.md) — they are hand-written and complement the auto-generated per-tag pages listed under "API groups" below. ## Idempotency & safe retries `POST`, `PATCH`, and `PUT` requests accept an **`Idempotency-Key`** header (≤255 characters). A replay with the same key, method, and path within **24 hours** returns the original response without re-executing the operation — the replayed response carries `X-Idempotency-Replayed: true`. * Use a fresh key (e.g. a UUID) per logical operation, so a retry after a network failure or timeout is safe. * Without an `Idempotency-Key`, a retried write may create a duplicate — set one on every state-changing request you might retry. * For pure-read endpoints (`GET`), retries are always safe. ## Spec validation The OpenAPI document in this repo is validated with the Redocly CLI: ```bash npx -p @redocly/cli redocly lint docs/help/developers/api-reference/openapi.yaml # Woohoo! Your API description is valid. 🎉 ``` Each group page below renders interactive, testable operations from the live OpenAPI spec. ## OpenAPI document * [OpenAPI spec (JSON)](https://api.peakcommerce.com/api/v1/openapi.json) — full machine-readable spec ## API groups * [Accounts](/developers/api-groups/accounts.md) * [Admin - API Keys](/developers/admin-api/admin-api-keys.md) * [Admin - Audit](/developers/admin-api/admin-audit.md) * [Admin - Content](/developers/admin-api/admin-content.md) * [Admin - Partners](/developers/admin-api/admin-partners.md) * [Admin - Roles](/developers/admin-api/admin-roles.md) * [Admin - Users](/developers/admin-api/admin-users.md) * [Credits](/developers/api-groups/credits.md) * [Discovery](/developers/api-groups/discovery.md) * [Invoices](/developers/api-groups/invoices.md) * [Observability](/developers/api-groups/observability.md) * [Orders](/developers/api-groups/orders.md) * [PaymentMethods](/developers/api-groups/paymentmethods.md) * [Payments](/developers/api-groups/payments.md) * [Preview](/developers/api-groups/preview.md) * [Pricing](/developers/api-groups/pricing.md) * [Refunds](/developers/api-groups/refunds.md) * [Seller](/developers/api-groups/seller.md) * [Sessions](/developers/api-groups/sessions.md) * [Shipping](/developers/api-groups/shipping.md) * [Subscriptions](/developers/api-groups/subscriptions.md) * [Webhooks](/developers/api-groups/webhooks.md) --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.peakcommerce.com/developers/api-reference/api-reference.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.