Examples and docs

A collection can document itself. Saved examples record what a request returns; Markdown docs on the collection, its folders and its requests explain what they’re for. Together they feed three things: mock servers answer with your examples, exported HTML documentation shows both, and Postman and OpenAPI exports carry them to other tools.

Save a response as an example

An example is a saved response: name, status code, headers and body, plus the method and URL of the request that produced it.

1. Open a saved request and send it.
2. When the response looks right, click Save as Example above it.
3. The example is named after the status, such as “200 OK”, and saved with the request.

Save as Example appears only for requests saved in a collection. The headers Content-Length, Content-Encoding, Transfer-Encoding, Connection and Date are left out, because they describe one particular delivery rather than the response.

Examples also come from:

• Saving a captured request: its response becomes the request’s first example.
• Importing a Postman collection (its saved responses) or an OpenAPI spec (one example per documented response code, built from the spec’s examples or schemas).

A collection’s Overview tab counts its examples. The app has no editor for an example’s contents. To rename, change or remove one, edit the examples array in the request’s .request.json file in the workspace folder; the app reloads it within a few seconds.

Where examples are used

Feature	How it uses examples
Mock servers	Serves each example at its request’s method and path. Callers pick one with x-mock-response-name or x-mock-response-code.
HTML documentation	Shows each example’s name, status and body under its request.
Postman export	Each example becomes a saved response.
OpenAPI export	Examples become the operation’s documented responses.
Spec sync	Keeps examples you added when it updates requests from a spec.

Write documentation

Collections, folders and requests each have Markdown documentation with Edit and Preview modes.

Where	How to open it
Collection	Click the collection; the editor is on its Overview tab under Documentation.
Folder	Click the folder; its Overview tab.
Request	The request’s Docs tab. A dot on the tab means it has docs.

Docs are saved in the workspace with the item, imported from and exported to Postman descriptions, and imported from OpenAPI descriptions. An OpenAPI operation marked deprecated starts with “Deprecated.”.

Use Markdown for headings, bold and italic text, inline code, code blocks, lists, links, quotes and rules. Exported docs only turn http and https links into links. The in-app preview shows inline formatting; the exported HTML renders all of it.

Agent Mode can write a request’s docs for you: its Document this request action reads the request, runs it if needed, and saves Markdown to the Docs tab.

Export HTML documentation

The client turns a collection into one self-contained HTML file: a sidebar of folders and requests, and a page with every request’s details. It needs no server; open it in a browser or host it anywhere.

1. Right-click the collection and choose Export › API Documentation (HTML)…, or use More › Export API Documentation (HTML)… in the collection’s tab.
2. Choose where to save it. The default name is <collection> docs.html.
3. The file opens in your browser.

The page contains:

• The collection’s title, documentation, and a note about its auth type when it has one.
• A Variables table of the collection’s enabled variables, without secret ones.
• A Code examples menu that switches every request’s snippet between cURL, JavaScript, Python, NodeJS – Axios, Go, Swift, Java – OkHttp, C# – HttpClient, PHP – cURL and Ruby – Net::HTTP. The reader’s choice is remembered in their browser.
• For each folder, its name and docs.
• For each request: method and name, URL, docs, path variables, query parameters (disabled ones marked optional), enabled headers, the body, a code snippet, and every example with its status code and body.

Snippets keep {{variables}} as written, so readers see what to fill in. The page follows the reader’s light or dark appearance, and on narrow screens the sidebar is hidden.

cloakctl docs NAME --out FILE.html produces the same file from the command line. See Generate docs, SDKs and MCP servers.

Check what's in the docs before you publish them

The export includes header values, bodies, URLs and example responses exactly as saved. Before you publish it, make sure none of them contain real tokens, customer data or internal hosts. Use variables such as {{token}} in requests, and mark sensitive collection variables secret so they’re left out.

Brand the documentation

The collection’s Docs Branding tab sets how its exported docs look. A dot on the tab means branding is set.

123456

Branding for a collection's exported documentation.

1. Title replaces the collection name
2. Accent color, typed or picked
3. Logo from a URL or an image file
4. Markdown footer
5. Hide the attribution line
6. Preview in your browser, or export

×

Field	What it does
Title	The page title and heading. Empty uses the collection’s name.
Accent color	A CSS color, such as #ff6c37, for headings and links. Type it or use the color well. Only plain color syntax is accepted, so it can’t inject other CSS.
Logo	An https:// image URL, or Choose… to embed a PNG, JPEG, SVG or GIF file under 512 KB in the page. Shown at the top of the sidebar. Other kinds of URL are ignored.
Footer (Markdown)	Text at the bottom of the page, such as a copyright line and links. Rendered as Markdown with HTML escaped, so it can’t add scripts.
Hide “Made with Cloak Proxy”	Removes the attribution and date line at the bottom.

Preview writes the page to a temporary file and opens it in your browser. Export HTML Docs… saves it. Branding is saved in the collection’s collection.json and used by cloakctl docs too.

Host the file on GitHub Pages, S3, Netlify or your own domain like any static page.

Related

Mock serversServe your examples on localhost.

Generate docs, SDKs and MCP serversEverything you can generate from a collection.

Import and exportPostman and OpenAPI in and out.

Turn traffic into API docsFrom captured requests to published docs.