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)
Detailed per-resource reference pages live under reference/ — 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:
Each group page below renders interactive, testable operations from the live OpenAPI spec.
OpenAPI document
OpenAPI spec (JSON) — full machine-readable spec
API groups
Last updated
Was this helpful?