The OpenAPI specification of our API: what it is, where to download it and what it contains

The short answer: the OpenAPI specification is a JSON file, openapi.json, that describes the whole API in a format tools understand: the address, every operation, the parameters, request bodies, responses, errors and how to authenticate. The reference in the documentation is built from this same file. It uses the OpenAPI 3.1 format.

Where to find it

Where	How to get there
In the API reference	At the end of the page, in the Specification section: Download the OpenAPI specification. It already carries the MozOut API address.
In llms.txt	In the last section, Specification.
From the API itself	The GET /v1/openapi.json operation returns the specification, with no key.

To import into a tool, use the file from the reference, which is the one that goes with the documentation you are reading.

What is inside

Part	What it is
info	The name, version and description: how to authenticate and what sets the Sandbox and Production modes apart.
servers	The API base address.
paths	Every operation, with its summary, parameters, body, responses and examples.
components	The shared pieces: data schemas, error responses, headers and the bearerAuth scheme, the key in the Authorization header.
tags	The areas: domains, dns, sms, billing and the rest. Tools use them to create folders.
x- fields	Our own extensions: x-permission gives the permission for each operation, x-summary-pt and x-description-pt hold the Portuguese texts, and x-limits sums up the limits.

What it is for

1	Importing into an API client, such as Postman or Insomnia, to have every request ready: see Postman and Insomnia and other clients.

2	Generating a client in your language: see generating an API client.

3	Checking in your tests that your program requests and responses match what the API expects.

4	Giving an AI assistant the exact description of the operations.

5	Seeing what changed: keep a copy and compare it with the next one.

The standard texts in the specification are in English. The Portuguese ones are in the x-summary-pt and x-description-pt fields, which most tools ignore.

Paths start with /v1 and the server address does not include it. If you set up a tool by hand, do not add /v1 twice.

Download the specification and import it into your favourite tool.

Download the specification

Categories

Categories