---
id: api-openapi
title: OpenAPI document
summary: Where to fetch the machine-readable API description, and what is guaranteed about it.
faces: ["public", "agent"]
section: back-end
group: API reference
slug: openapi
order: 60
---
# OpenAPI document

The whole merchant surface is published as OpenAPI at [/openapi.json](/openapi.json). Every page in this
section is generated from it, so the document and the prose cannot disagree.

Fetch it if you want to generate a client, drive tests, or let an agent read the API without scraping pages.
`/.well-known/ripper-docs.json` carries its hash, so you can tell whether a copy you hold is current.

Two things are worth knowing before you generate from it. Each operation carries `x-ripper-audience`, which
says whether your server calls it or the checkout calls it from the browser, so a generated client can leave
out the browser routes. And `operationId` is the stable, codegen-friendly name: it is what these pages quote,
and it does not change when a route moves.

Breaking changes are announced 90 days ahead.