Postman¶

The visual API client. Postman shines for exploratory testing of model endpoints — build a request once, save it in a collection, and replay it with different environments (dev/staging/prod) or auth tokens without retyping anything.

Table of Contents¶

Installation / Setup
Core Syntax
Common Operations
Practical Examples
Common Patterns
Best Practices
Common Mistakes
Troubleshooting
Related Cheat Sheets
Official Documentation

Installation / Setup¶

# Desktop app: download from https://www.postman.com/downloads/
# No install CLI needed for the GUI — the CLI (newman) is for CI testing:

npm install -g newman        # run collections from the terminal / CI

Term	Meaning
Request	One HTTP call: method, URL, params, headers, body
Collection	A saved folder of requests — shareable, runnable, versionable
Environment	Named set of variables (`base_url`, `api_key`) switchable per workspace
Workspace	Shared space for collections + environments (team collaboration)
newman	Postman's CLI runner — executes collections headlessly

Core Syntax¶

Building a request¶

Field	Where	Purpose
Method + URL	top bar	`POST` + `http://localhost:8000/predict`
Params tab	under URL	Query params `?top_k=5` (auto URL-encoded)
Headers tab	under URL	`Content-Type`, `Authorization`, custom headers
Body tab	under URL	`raw` + `JSON` for most model APIs
Authorization tab	under URL	Bearer/API key/Basic — auto-attaches the header
Tests tab	under URL	JS assertions that run after the response arrives
Pre-request Script	under URL	JS that runs before sending (e.g. sign a timestamp)

Variables¶

{{base_url}}/predict      # used anywhere in URL, headers, body
{{api_key}}               # referenced in the Authorization header

Variables resolve from (highest to lowest): local → environment → collection → global.
Define them in an Environment (per-deployment) rather than hard-coding URLs.

Common Operations¶

Test an ML prediction endpoint (step by step)¶

New request → method POST, URL {{base_url}}/predict.

Body → raw → JSON:

{
  "tenure": 12,
  "monthly_charges": 89.5,
  "contract": "month-to-month",
  "support_calls": 3
}

Set an environment with base_url = http://localhost:8000.
Send — inspect status, time, and the pretty-printed JSON response.
Save → name it → pick a collection (e.g. Churn API).

Environments for dev / staging / prod¶

Environment	Variable	Value
Local	`base_url`	`http://localhost:8000`
Staging	`base_url`	`https://staging-api.example.com`
Prod	`base_url`	`https://api.example.com`

Same collection, zero edits — just switch the environment dropdown.

Authentication quick setups¶

Auth type	When	Postman setup
Bearer token	OpenAI-style APIs	Authorization tab → Type `Bearer Token` → paste token (or `{{api_key}}`)
API Key	many internal services	Header `X-API-Key: {{api_key}}`
Basic Auth	legacy endpoints	Authorization → `Basic Auth` → user/pass
OAuth 2.0	SSO-protected APIs	Authorization → `OAuth 2.0` → Get New Access Token

Save requests into collections — they become executable documentation.
Use collection variables for values shared by every request in that collection.
Export: ... menu → Export → JSON file (share/commit alongside your API spec).
Import OpenAPI specs: Import → Link/File — Postman generates a collection from your FastAPI /openapi.json.

Practical Examples¶

Example 1 — Vision model upload¶

Request: POST {{base_url}}/classify
Body → form-data → key file, change type to File, pick an image

Tests tab:

pm.test("200 + label returned", () => {
  pm.response.to.have.status(200);
  const body = pm.response.json();
  pm.expect(body.label).to.be.a("string");
});

Example 2 — Streaming chat request (SSE)¶

Some LLM APIs stream; Postman shows raw chunks in the response.
Test with stream: true in the body and confirm chunks arrive before the request finishes.

Example 3 — Folder of assertions run in CI¶

collection "Churn Model"
├── health   →  Tests: status 200, body.status == "ok"
├── predict  →  Tests: 200, body.prob_churn between 0 and 1
└── errors   →  bad payload, Tests: status 400

newman run Churn\ Model.postman_collection.json \
  -e local.postman_environment.json \
  --reporters cli

Common Patterns¶

Chain requests with variables¶

// In the *Tests* of a login/embed request, save a value for later requests:
const data = pm.response.json();
pm.collectionVariables.set("embedding_id", data.id);

Then the next request uses {{embedding_id}} — builds multi-step flows (auth → predict → audit).

Smoke-test a whole collection¶

# run all requests in order; non-2xx fails the run
newman run churn_api.json -e local.json --bail

Data-driven tests (CSV/JSON of many payloads)¶

newman run churn_api.json -d test_cases.json   # one iteration per case

Each iteration runs against a row — great for regression-testing a model endpoint on known inputs.

Best Practices¶

Use environments, never hard-coded URLs or tokens in requests.
Store keys in environment/collection variables; use Postman's secret vault for sensitive values.
Add Tests to every saved request so collections double as smoke tests.
Save example responses (Save Response as Example) — they document expected schemas.
Import your API's OpenAPI spec to auto-generate collections (FastAPI exposes /openapi.json).
Keep one collection per service and version collections with git for reviewable API changes.
Use newman in CI for scheduled endpoint health checks.

Common Mistakes¶

Mistake	Fix
Forgetting `Content-Type: application/json` on raw JSON bodies	Postman usually adds it for raw→JSON; verify in Headers
Typing the token into the URL or body instead of headers	Use the Authorization tab or `{{api_key}}` header
Hard-coding `localhost:8000` everywhere	Use `{{base_url}}` per environment
Secrets committed in a shared collection	Store in environment variables/secret vault; never export to git
Wrong variable shadowing (two envs active)	Only one environment is active at a time — check the dropdown
Tests that pass while status is 500	Assert the status first, then body fields
File uploads sent as raw instead of form-data	Switch Body to `form-data` and set the key type to File

Troubleshooting¶

Symptom	Cause / Fix
`Could not get any response`	Server down, wrong port, or SSL issue — check the URL and console
Response is HTML instead of JSON	Wrong Content-Type sent, or a proxy/load-balancer error page — set the header, check the URL
`{{base_url}}` stays literal in the URL	The variable doesn't exist — add it to an environment or collection
Request works in curl but not Postman	Compare headers; Postman adds defaults like `Accept-Encoding` — check the Headers tab
`401 Unauthorized`	Token expired or wrong env — regenerate and store in the active environment
Certificate error against a local server	Settings → disable SSL verification (local testing only)

REST API — methods, resources, status codes
HTTP — headers, CORS, status semantics
curl — the terminal equivalent for scripting
python-requests — automate what you designed in Postman
FastAPI / Flask — generate a collection from /openapi.json
JSON — request/response payloads
git — versioning collection files

Official Documentation¶

Postman docs — https://learning.postman.com/
Postman collections — https://learning.postman.com/docs/collections/intro-to-collections/
newman CLI — https://learning.postman.com/docs/collections/running-collections/using-newman-cli/

Last Updated¶

2026-09-06 — Initial version.