Postview Postview Docs v1.2
Home Open Viewer

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:

  1. Open the web viewer at /app.
  2. Click Load sample to explore a pre-configured demo API, or drag-and-drop your own Postman JSON file.
  3. 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.json file 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.

Tip for Local APIs: Browsers enforce Cross-Origin Resource Sharing (CORS). If your local API does not include 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:

  1. In Postview web, open Tokens and create a token (e.g. antigravity). Copy the secret — it is shown once.
  2. Add this to your agent's MCP config. No download needed, npx fetches 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 baseUrl in 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/login or POST /api/users/signin), Postview automatically detects the returned JWT/bearer token, caches it in the workspace session, and attaches Authorization: Bearer <token> to all subsequent requests.
  • The set_variable MCP Tool: Agents can invoke set_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.