Overview
A v3 collection is a directory tree under postman/collections/, one file
per entity — every request, every folder's metadata, every saved example is
its own file. There is no single collection.json to open and edit; the
directory structure itself is the collection.
postman/collections/
bookstore api/
.resources/
definition.yaml (optional)
get all books.resources/
examples/
200 OK.example.yaml
400 Bad Request.example.yaml
500 Internal Server Error.example.yaml
get all books.request.yaml
get-book-by-id.request.yaml
add new book.request.yaml
authentication/
.resources/
definition.yaml (optional)
signup.request.yaml
login.request.yaml
- Every folder under
postman/collections/is a collection; it can contain subfolders and requests. - A folder or collection can have a
.resources/directory — an optional metadata directory for that scope..resources/definition.yamlholds the collection/folder's own metadata; request examples live under.resources/<request-name>.resources/examples/. - Never place a request file inside a
.resources/directory — those are metadata-only.
Definition file (.resources/definition.yaml)
Optional metadata for a collection or folder:
$kind: "collection"— required, even for a folder's definition.name— optional, defaults to the filesystem folder name.description— optional.variables— array of{key, value, description?, disabled?}.valuemust be a string;disableda boolean.auth— a single auth object{type, credentials: [{key, value}, ...]}, or an array for multiAuth:[{id, name, type, credentials, rules?}, ...].scripts— array of{type, code, language: "text/javascript"}.typeis one ofhttp:beforeRequest,http:afterResponse,graphql:beforeQuery,graphql:afterResponse,grpc:beforeInvoke,grpc:onIncomingMessage,grpc:afterResponse.order— number, used for folder ordering.
HTTP request (*.request.yaml)
$kind: "http-request"— required.name— optional (see naming rules below for when to include it).order— number; only used for relative comparison, so space values out (e.g. multiples of 1000) rather than packing them tight — a later insertion between two requests shouldn't force renumbering every sibling.url— string, with{{varName}}variable syntax.method—GET|POST|PUT|DELETE|PATCH|HEAD|OPTIONS.headers— array of{key, value, description?, disabled?}.queryParams— array of{key, value, description?, disabled?}.pathVariables— array of{key, value, description?}.body—{type, content};typerequired wheneverbodyis present.- Types:
json,formdata,urlencoded,text,xml,html,javascript,file,none. json/text/xml/html/javascript:contentis a string.formdata:contentis an array of{key, type: "text"|"file", value or src, contentType?, description?}.urlencoded:contentis an array of{key, value, description?}.
- Types:
auth—{type, credentials}.settings—{protocolVersion?, strictSSL?, followRedirects?, maxRedirects?, disabledSystemHeaders?}.scripts— array of{type: "beforeRequest"|"afterResponse", code, language: "text/javascript"}.examples— optional, a relative path to the examples directory, e.g../.resources/<request-name>.resources/examples/.
HTTP example (*.example.yaml)
$kind: "http-example"— required.name— optional.request: {url, method}.response: {statusCode, statusText, headers: [{key, value}], body: {type, content}}.order— optional.
Saved examples are what collection ai-readiness checks for — a request
with no examples scores worse for agent consumption even if perfectly
valid structurally.
Environments (postman/environments/*.yaml)
name— required.values— array of{key, value: string, enabled, type}.valuemust be a string (same rule as collection variables);enabledis boolean;typeis a string, e.g."default".
YAML rules
Invalid YAML breaks parsing silently in confusing ways — when in doubt, single-quote it:
- Single-quote any value containing
{{variables}}:url: '{{base_url}}/users'— never leave it unquoted. - Single-quote values containing
: # & * ! [ ] { } > |, e.g.name: 'Health check: v2'. - Multi-line content (JSON bodies, scripts, queries) uses a
|-block scalar:body: type: json content: |- { "name": "example" } - Quote strings that resemble booleans/numbers when a string is intended:
value: "true",value: "123". ordermust be a bare number, never quoted:order: 1000.- Single-quote file paths and use forward slashes only:
examples: './.resources/name.resources/examples'.
Naming rules
<request-name>(the filename stem before.request.yaml) must not contain/ \ : * ? " < > |— sanitize to-.- Include
namein the file only when it differs from<request-name>(e.g.name: 'Health/check'insideHealth-check.request.yaml, since the filename itself can't hold the/). - Filenames must be unique, case-insensitively, per directory.
Worked example: "bookstore api"
postman/collections/bookstore api/get all books.request.yaml
$kind: http-request
method: GET
url: '{{base_url}}/books'
order: 1000
postman/collections/bookstore api/get-book-by-id.request.yaml
$kind: http-request
name: 'get book by :id'
method: GET
url: '{{base_url}}/books/:id'
order: 2000
pathVariables:
- key: id
value: '1'
postman/collections/bookstore api/add new book.request.yaml
$kind: http-request
method: POST
url: '{{base_url}}/books'
order: 3000
headers:
- key: Content-Type
value: application/json
body:
type: json
content: |-
{
"title": "Example Book",
"author": "Jane Doe"
}
postman/collections/bookstore api/.resources/definition.yaml
$kind: collection
name: Bookstore API
variables:
- key: base_url
value: 'https://api.bookstore.com/v1'
Critical Rules
- Every entity is its own file — there's no single collection.json to open. A request, its parent folder's metadata, and its saved examples are three separate files, not sections of one document.
- Unquoted
{{variables}}or special characters are the most common way a hand-written file fails to parse. Single-quote per the YAML rules above rather than debugging a cryptic lint error after the fact. orderis relative, not an index. Don't renumber every sibling file to insert one request — leave headroom (spacing of 1000) from the start.- This file covers HTTP only. A collection using GraphQL, gRPC,
WebSocket, Socket.IO, MQTT, MCP, or LLM requests needs
reference/other_protocols.md — don't
guess those schemas from the HTTP shape above, they diverge in real ways
(e.g. gRPC's
methodDescriptor, LLM'suserPrompts/systemPrompts).
Reference
- Other request protocols — GraphQL, gRPC, WebSocket, Socket.IO, MQTT, MCP, and LLM request schemas.