Collections and requests

A collection is a group of saved requests, optionally organized into folders. Collections and folders carry shared settings (documentation, auth and scripts) that their requests inherit, and a collection also has its own variables. This page covers building and organizing them, every part of the HTTP request editor, and the response viewer.

Requests for other protocols (gRPC, WebSocket, MQTT and the rest) live in the same collections; their editors are described in API client protocols.

Create a collection and a request

1. Click Collections in the rail, then + › New Collection. The collection opens in a tab, named “New Collection”. Click its name to rename it.
2. Right-click the collection in the sidebar and choose Add Request. A request named “New Request” opens.
3. Type a URL, for example https://api.example.com/v1/users?limit=10, and pick a method.
4. Press ⌘ ↩ or click Send.

To try something without saving it, press ⌘ T. You get an “Untitled Request” tab that isn’t in any collection. Its Save menu (⌘ S) lists your collections; pick one to save the request at its top level, or choose New Collection… to create “My Collection” and save it there. The tab becomes a saved request.

Paste a cURL command

Paste a whole curl … command into the URL field. The client fills in the method, URL, query params, headers and body. See Import and export for the flags it understands.

Organize the sidebar

12345

A collection's tab shows its counts and documentation. Its buttons start a run, a load test or a mock server.

1. Click a collection or folder to open its settings; click the arrow to expand it
2. A folder inside the collection
3. Filter by request name or URL
4. Run, Load Test, Mock and More
5. Overview, Authorization, Scripts, Variables and Docs Branding tabs

×

• Filter at the top of the sidebar matches request names and URLs, and folder names. Matching folders open while you filter.
• Drag a request or folder onto a folder to move it there, or onto a collection’s row to move it to the collection’s top level. You can drag between collections. A folder can’t be dropped into itself.
• The badge before each request shows its method (GET, POST, PUT, PATCH, DEL, HEAD, OPT) in color, or its protocol: GQL, gRPC, WS, SIO, MQTT, MCP, AI, TCP, SQL.
• Opening a request expands the folders above it.

Collection menu

Right-click a collection in the sidebar:

Item	What it does
Add Request	A new HTTP request at the collection’s top level.
Add Other Request	A new request of another protocol: GraphQL, gRPC, WebSocket, Socket.IO, MQTT, MCP, AI, TCP / UDP or Data.
Add Folder	A new folder named “New Folder”.
Run Collection	Opens the collection runner.
Performance Test	Opens a load test.
Mock Collection	Opens the collection’s mock server.
Monitor Collection	Creates a monitor that runs it on a schedule.
Generate MCP Server…	Saves a Node.js MCP server with one tool per request as a zip. See Generate docs, SDKs and MCP servers.
Generate SDK	TypeScript…, Python… or Swift…: writes a client library into a folder you choose.
Export	Postman Collection v2.1…, OpenAPI 3.0 (YAML)… or API Documentation (HTML)…. See Import and export.
Rename	Edit the name in place. Esc cancels.
Duplicate	A copy named “… copy” with new ids.
Delete	Moves the collection to Recently Deleted for 30 days.

Folder and request menus

Folder item	What it does
Add Request	A new request inside the folder.
Add Folder	A subfolder.
Run Folder	Runs only this folder’s requests.
Rename, Duplicate, Delete	As for collections. A duplicated folder is added at the collection’s top level; a deleted one goes to Recently Deleted with everything in it.

Request item	What it does
Open	Opens it in a tab (a single click does the same).
Send	Sends it without opening it.
Rename, Duplicate	Rename in place, or copy it as “… copy” in the same folder.
Copy as cURL	Copies a cURL command with variables filled in. See Code snippets.
Delete	Moves it to Recently Deleted and closes its tab.

Collection and folder settings

Click a collection or folder to open its tab.

Tab	Collection	Folder
Overview	Counts of requests, top-level folders, saved examples and requests with a post-response script, and the collection’s Markdown documentation.	The folder’s Markdown documentation.
Authorization	Auth every request uses unless it sets its own. A collection can’t inherit.	Auth for the folder’s requests. Defaults to Inherit auth from parent.
Scripts	Pre-request and post-response scripts that run for every request, before the folder’s and request’s own.	Scripts for the folder’s requests.
Variables	Collection variables, available as {{name}} in every request.	Not available on folders.
Docs Branding	Title, accent color, logo and footer for exported HTML docs.	Not available on folders.

The collection’s header also has Run, Load Test, Mock and More (Add Request, Add Folder, Monitor…, Generate MCP Server… and the three exports). A folder’s header has Run Folder and Add Request. Both have a comments button. See Comments.

How auth and scripts combine is in Authorization and Scripts and tests. Variables are in Variables and environments.

The request editor

123456

A saved request with a path variable, and its response.

1. Method menu and URL
2. Send (⌘↩)
3. Request tabs; numbers and dots show which ones have content
4. Path variables come from :name segments in the URL
5. Code snippets and comments
6. Save as Example and Copy Body

×

The header shows where the request lives (Petstore / Admin /) and its name, which you can edit in place. Below it:

• Method menu: GET, POST, PUT, PATCH, DELETE, HEAD or OPTIONS.
• URL field: “Enter URL or paste a cURL command”. Pressing ↩ in the field sends the request. A URL without a scheme is sent as http://.
• Send: ⌘ ↩. While the request is in flight it becomes Cancel.

If the URL or a header uses a variable that isn’t defined in the active environment, the collection or globals, an orange warning under the URL bar names it. See Variables and environments.

The request tabs are Params, Authorization, Headers, Body, Scripts, Settings and Docs. A number after a tab name counts its enabled rows; a dot means it has content. The client remembers which tab you last used.

Key and value tables

Params, headers, path variables, form fields and variables all use the same table:

• The checkbox turns a row on or off without deleting it. Disabled rows are dimmed and not sent.
• Each row has Key, Value and Description. Descriptions appear in exported docs.
• Type in the empty last row to add one. The × at the end of a row deletes it.
• Values that use an undefined {{variable}} turn orange.

Params

Query Params and the URL’s query string stay in sync. Typing in the URL updates the table; editing the table rewrites the URL. Disabled params stay in the table but leave the URL.

Path Variables appear when the URL has segments that start with a colon, such as /pets/:petId. Give each one a value; it replaces :petId when you send. Path variable values can use {{variables}}.

Headers

Add headers in the table. When you don’t set them yourself, the client also sends User-Agent, Accept, Host, Content-Length and cookies from its cookie jar. The body type also sets Content-Type if you haven’t (see below), and the request’s auth adds its own headers when you send.

Body

1

Choose the body type on the Body tab.

1. Body types

×

Type	What you enter	Content-Type added if missing
None	Nothing.	None.
Raw	Text in an editor. A menu picks JSON, TEXT, XML, HTML or JAVASCRIPT.	application/json, text/plain, application/xml, text/html or application/javascript, when the body isn’t empty.
x-www-form-urlencoded	Key and value rows, form-encoded when sent.	application/x-www-form-urlencoded
form-data	Key and value rows. Each row’s Text / File menu switches the value to a file; Choose… picks it.	multipart/form-data with a boundary. Each file part gets a content type from its extension.
Binary	A file, chosen with Choose File…. Its bytes are the body.	application/octet-stream
GraphQL	A query and variables, with schema introspection. See GraphQL.	application/json

Raw, form and GraphQL bodies resolve {{variables}}, including form keys, values and form file paths. The Binary file path is used as chosen. File paths can start with ~.

Scripts

JavaScript that runs before the request is sent and after the response arrives, with Postman’s pm API. See Scripts and tests.

Request settings

The Settings tab controls how this one request is sent.

Setting	Default	What it does
Send through Cloak Proxy (shows in traffic; debugging tools apply)	On	Routes the request through the proxy on its port, so it appears in the traffic list and debugging tools apply. Off sends it directly, without the macOS system proxy.
Follow redirects	On	Follows up to 10 redirects. Off returns the 3xx response.
Verify TLS certificates	On	Off accepts self-signed and otherwise invalid certificates. Use it only for servers you control.
Encode the URL automatically	On	When the URL isn’t valid as typed (for example, it contains spaces), percent-encodes it before sending.
Timeout (ms, 0 = default 30 s)	0	How long to wait for the response. 0 means 30 seconds.
Unix socket (e.g. /var/run/docker.sock)	Empty	Sends the request over a Unix domain socket. Docker fills in /var/run/docker.sock. The URL’s host is ignored; its path is sent over the socket, for example http://localhost/v1.43/containers/json. Requests over a socket don’t go through the proxy.

A request to the proxy’s own port on localhost is always sent directly, so it doesn’t loop through itself.

Turning off TLS verification

With Verify TLS certificates off, the client can’t tell a real server from an impostor. Leave it on for anything that isn’t your own development server, and don’t commit requests that have it off for production hosts.

Docs

Markdown documentation for the request, with Edit and Preview. It’s shown in exported HTML docs and Postman exports.

Read the response

The lower half of the editor shows the last response. Drag the divider to resize it. The header shows the status (green for 2xx, orange for 3xx, red for 4xx and 5xx), the total time and the body size, plus Save as Example (saved requests only) and Copy Body.

Tab	What it shows
Body	The body in Cloak Proxy’s body viewers: JSON tree with filtering and queries, Pretty, Raw and Hex, HTML and image previews, and more.
Visualize	HTML from pm.visualizer.set(). Shown only when a script set it.
Headers	Response headers, with the count in the tab.
Cookies	The client’s cookie jar: domain, name, value, path and expiry of every cookie it has received. Clear All empties it; the trash button removes one.
Test Results	Each pm.test with PASS, FAIL or SKIP and the failure message. The tab shows passed/total.
Console	Script errors, then console.log output with its level and the script it came from.
Request	The request exactly as sent: method, final URL, headers (including auth and cookies) and body, after scripts and variables.
Timing	Bars for pre-request scripts, waiting (time to first byte), download and post-response scripts, with the total and the start time.

1234

The Timing tab separates script time from network time.

1. Headers the client adds when you don't
2. Timing tab
3. Script and network phases
4. Total and start time

×

The cookie jar works like a browser’s: cookies a server sets are sent back on later requests to the same domain and path, secure cookies only over HTTPS. It belongs to the API client and isn’t shared with Safari or the proxy. It isn’t saved in the workspace.

If the request couldn’t be sent, the response area says Couldn’t send the request with the reason (for example “Couldn’t connect to api.example.com:443 (DNS lookup failed)” or “The request timed out”) and any console output. Bodies over 50 MB are cut off.

Related

AuthorizationEvery auth type and how inheritance works.

Variables and environmentsUse {{variables}} across requests.

Examples and docsSave responses as examples and publish docs.

HTTP requestsHTTP-specific details, including Unix sockets.