Postview User Guide
Postview turns your collections into collaborative workspaces. Browse requests, resolve environment variables, invite teammates with role-based access, and generate code snippets instantly.
Quick Start
You can get started in seconds without creating an account:
- Open the web viewer at /app.
- Click Load sample to explore a pre-configured demo API, or drag-and-drop your own Postman JSON file.
- Select any endpoint in the sidebar to inspect parameters, headers, and request body.
Importing Collections
Postview can natively parse Postman Collection v2.0 and v2.1 exports. You can import collections in two ways:
- Drag-and-Drop: Drag any exported
*.postman_collection.jsonfile and drop it onto the viewer. - File Picker: Click Open .json in the top header to select a file from your device.
Every imported collection is automatically organized into its own workspace with full folder hierarchies, request counts, and saved example responses.
Team Workspaces
Switch between multiple API collections effortlessly using the Workspace Switcher in the top navigation bar.
- Each workspace maintains its own collection tree, environment variables, and collaborator settings.
- Workspaces persist in your browser session and synchronize across devices when signed in.
Environment Variables
Postview automatically recognizes double-bracket variables ({{baseUrl}}, {{token}}, {{userId}}) anywhere in your collection:
- URL Endpoints: Interpolates root hostnames and path variables dynamically.
- Query Parameters & Headers: Replaces tokens in real-time as you switch values.
- Request Payloads: Injects test IDs or variables directly into raw JSON payloads.
Use the Environment Bar below the header to update your baseUrl or load an exported environment file.
Code Snippet Generator
Click the <> Code button next to any endpoint to generate ready-to-run code snippets in four popular formats:
- cURL: POSIX-compatible terminal commands with headers and data flags.
- JavaScript (Fetch): Modern
fetch()code for web apps and scripts. - Python (Requests): Clean
requests.request()blocks for Python services. - Node.js (Axios): Ready-to-use Axios configurations with response handlers.
All active environment variables are automatically resolved in generated snippets before copying.
Executing Requests
Click Send to execute live HTTP calls against your API. The response panel displays the status code, latency (ms), content type, and formatted response body.
Access-Control-Allow-Origin headers, you can use the included headless CLI (pcv.cjs) or MCP server to run requests directly without browser restrictions.
Roles & Permissions
When collaborating in shared workspaces, Postview enforces role-based access control (RBAC) to protect sensitive systems:
| Role | Permissions | Can Run Live Requests |
|---|---|---|
| Owner / Admin | Full access to manage workspace, invite teammates, and edit settings | Yes |
| Member | Can inspect endpoints, update environment variables, and run requests | Yes |
| Viewer | Read-only inspection and code export. Live execution is safely locked. | No (Read-only) |
To invite teammates, click Share in the top header and select their role before sending an invite link.
AI Agents & Model Context Protocol (MCP)
Give an AI agent (Claude Desktop, Cursor, Google Antigravity) access to your workspaces in 2 minutes:
- In Postview web, open Tokens and create a token (e.g.
antigravity). Copy the secret — it is shown once. - Add this to your agent's MCP config. No download needed,
npxfetches the bridge (postview-mcp) on first run:
{
"mcpServers": {
"postview": {
"command": "npx",
"args": ["-y", "postview-mcp"],
"env": { "POSTVIEW_TOKEN": "" }
}
}
}
The agent then discovers your projects itself: list_workspaces →
list_collections → list_requests → get_request →
run_request. Agents can customize any call on the fly by passing params (URL query parameters), headers (HTTP headers), body (custom JSON/payload override), and vars (template variables). Workspace shared variables like {{baseUrl}} resolve automatically, and secrets never leave the server. Revoke the token anytime from the Tokens panel.
Headless CLI (pcv.cjs)
For terminal workflows and CI/CD pipelines, use the zero-dependency CLI tool:
# List all endpoints in a collection node pcv.cjs list sample-collection.json # Export an endpoint as a cURL command node pcv.cjs show sample-collection.json "List users" --curl
Testing the CLI & Agent Package (agent/)
Postview includes a zero-dependency CLI and MCP server packaged in agent/ (published as postview-mcp). You can log into your account, list your cloud workspaces, and run requests directly from your terminal.
1. Log into your Postview Account
Run the login command with your account email and password:
# From the agent directory: cd agent node pcv.cjs login you@company.com YourSecretPassword # Or anywhere via npx: npx -y -p postview-mcp pcv login you@company.com YourSecretPassword # Or install globally: npm install -g postview-mcp pcv login you@company.com YourSecretPassword
2. Verify Session & Cloud Workspaces
Inspect your authenticated user profile and list all cloud-synced workspaces:
# Check current profile node pcv.cjs me # List all cloud workspaces node pcv.cjs workspaces
3. Create an Agent Token for AI Assistants
Create a dedicated API token for AI coding assistants (Claude Desktop, Antigravity, Cursor):
node pcv.cjs tokens create "AntigravityAgent"
4. Execute Live Requests via CLI
Send requests against any endpoint in your workspace (with optional custom body, headers, or query parameters):
# Run request from a cloud workspace:
node pcv.cjs run "cloud:My API/My API" "Sign In" --var baseUrl=http://localhost:5000/api
# Send custom parameters, headers, or body payload:
node pcv.cjs run "cloud:My API/My API" "Sign In" --data '{"email":"user@test.com","password":"123"}' -H "X-Trace-Id: 9988" -p debug=true
5. Dynamic BaseURL & On-the-Fly Bearer Tokens
Agents automatically inherit the environment variables configured in your workspace, and can acquire authentication credentials dynamically:
-
Live BaseURL Sync: When you or your team update
baseUrlin the Postview Web UI (or click Variables…), the change is instantly synced to the cloud workspace in Cloudflare D1. Any connected AI agent will immediately use this updated URL on its next request. -
Auto-Token Capture on Sign-In: When an agent runs a login endpoint (e.g.
POST /api/auth/loginorPOST /api/users/signin), Postview automatically detects the returned JWT/bearer token, caches it in the workspace session, and attachesAuthorization: Bearer <token>to all subsequent requests. -
The
set_variableMCP Tool: Agents can invokeset_variable({ key: "token", value: "<jwt>", secret: true })at any point during an interactive prompt to set credentials or environment variables on the fly. - Web Workspace Credential Manager: Click Variables… in the web Environment bar to set tokens or credentials, toggle AES-GCM encryption sealing, and manage keys shared with AI agents.