Hoppscotch: Free Browser-Based API Testing Tool Getting Started Guide

Hoppscotch started life as Postwoman — a browser-based API client created as a fast, free, open-source alternative to Postman. The name changed to Hoppscotch in 2021, but the mission stayed the same: give developers a full-featured API testing tool they can open in any browser, with nothing to install, no account required, and no data sent to third-party servers (in the self-hosted version).

Today, Hoppscotch supports REST, GraphQL, WebSocket, Server-Sent Events, Socket.IO, and MQTT — all from a single interface at hoppscotch.io. It has team workspaces, collection sync, environment variables, test scripting, and a self-hosted Docker deployment path. This guide walks through all of it.

What Makes Hoppscotch Different

Most API clients are desktop apps. Hoppscotch runs entirely in the browser, which means:

• Zero install — open the URL, start testing
• Platform-agnostic — works on any OS including Chromebooks and Linux machines where Postman/Insomnia installation is painful
• Self-hostable — run your own instance so no API requests or credentials ever touch Hoppscotch's servers
• Open source — MIT licensed, auditable, forkable

The tradeoff is browser limitations. Because requests originate from the browser, CORS restrictions apply. If the API you're testing doesn't send permissive CORS headers, your request will be blocked. Hoppscotch solves this with the Hoppscotch Browser Extension (available for Chrome and Firefox) and the Hoppscotch CLI, which route requests through a local proxy that bypasses CORS.

Getting Started with the Web App

Navigate to hoppscotch.io. No login required — you can start sending requests immediately.

The interface has three main sections:

• Left sidebar — navigation between REST, GraphQL, Realtime, and other protocol tabs; also has Collections and Environments
• Request panel — URL bar, method selector, headers, body, auth configuration
• Response panel — status code, response time, response body, headers

Your First REST Request

1. Select REST from the left sidebar
2. Choose GET from the method dropdown
3. Enter a URL: https://jsonplaceholder.typicode.com/posts/1
4. Click Send

You'll see the JSON response appear in the response panel, along with the status code (200), response time, and size. Click the Headers tab in the response panel to see response headers.

Sending a POST Request

Switch the method to POST. Select application/json as the body type. Enter a JSON body:

{
  "title": "Testing Hoppscotch",
  "body": "This is a test post created via the API",
  "userId": 1
}

Click Send. JSONPlaceholder echoes back the created object with an id of 101.

Authentication

Click the Authorization tab in the request panel. Hoppscotch supports:

• No Auth
• Basic Auth — username/password, base64-encoded automatically
• Bearer Token — paste your JWT or API key
• OAuth 2.0 — full authorization code, client credentials, implicit flows
• API Key — adds to header or query parameter
• AWS Signature — for AWS API Gateway and S3

For Bearer Token auth, enter the token in the field. Hoppscotch appends Authorization: Bearer <token> to every request while that auth type is selected.

Collections

Collections organize your requests into folders. Create a collection by clicking the + icon next to "Collections" in the left sidebar.

A collection can have nested folders — for example:

Users API
├── Auth
│   ├── POST Login
│   └── POST Refresh Token
├── Users
│   ├── GET List Users
│   ├── GET Get User
│   └── DELETE Delete User
└── Posts
    ├── GET List Posts
    └── POST Create Post

Save any request to a collection by clicking Save and selecting the target folder. Collections are stored in your browser's local storage when you're not logged in. Log in with a GitHub, Google, or email account to sync collections to Hoppscotch's cloud — or to your own self-hosted instance.

Exporting collections: Hoppscotch can export collections in its own JSON format and in the OpenAPI format. It can import Postman Collection v2 and v2.1 files, making migration from Postman straightforward.

Environments

Environments let you define variables that get substituted into requests at runtime. Define a variable using <<variableName>> syntax in the URL, headers, or body:

https://<<baseUrl>>/api/v2/users/<<userId>>

Create an environment: click Environments in the left sidebar, then New Environment. Add key-value pairs:

Select the environment from the dropdown in the top-right corner of the interface. All <<variable>> placeholders in your request resolve to the environment values.

Global variables work the same way but are available across all environments. Use global variables for values that never change across environments — like a shared API version prefix or a fixed test user ID.

Writing Test Scripts

Hoppscotch includes a test scripting engine powered by JavaScript. Each request has a Pre-request Script tab and a Tests tab.

Tests run after the response is received. The API uses the Chai assertion library, similar to Postman and Bruno:

// Test status code
pw.test("Status is 200", () => {
  pw.expect(pw.response.status).toBe(200);
});

// Test response body structure
pw.test("Response has required fields", () => {
  const body = pw.response.body;
  pw.expect(body).toHaveProperty("id");
  pw.expect(body).toHaveProperty("email");
  pw.expect(body.email).toBeString();
});

// Test response time
pw.test("Response is fast", () => {
  pw.expect(pw.response.responseTime).toBeLessThan(1000);
});

// Test a specific value
pw.test("User role is admin", () => {
  pw.expect(pw.response.body.role).toBe("admin");
});

Note that Hoppscotch uses pw (Postwoman) as the global object name — it's a legacy from the original name. pw.expect(), pw.test(), pw.response are the key APIs.

Pre-request scripts run before the request is sent. Use them to compute dynamic values:

// Set a timestamp header value
pw.env.set("requestTimestamp", new Date().toISOString());

// Generate a random ID for idempotency keys
pw.env.set("idempotencyKey", crypto.randomUUID());

pw.env.set() writes to the active environment. pw.env.get("name") reads from it. Variables set this way are available in subsequent requests during a collection run.

GraphQL Testing

Hoppscotch has a dedicated GraphQL interface — not just a POST request with a JSON body, but a proper GraphQL client with schema introspection.

Click GraphQL in the left sidebar. Enter your GraphQL endpoint URL and click Connect. Hoppscotch fetches the schema via introspection and builds an explorer automatically.

Write a query in the query panel:

query GetUser($id: ID!) {
  user(id: $id) {
    id
    name
    email
    posts {
      title
      publishedAt
    }
  }
}

Define query variables in the Variables tab:

{
  "id": "user_abc123"
}

Click Run. The response appears in the right panel. Hoppscotch also shows query execution time and highlights schema errors in the editor.

For mutations:

mutation CreatePost($input: CreatePostInput!) {
  createPost(input: $input) {
    id
    title
    slug
  }
}

Headers (including Authorization) are set in the Headers tab, same as with REST requests.

WebSocket and Realtime Testing

Hoppscotch supports protocols beyond HTTP:

WebSocket: Click Realtime → WebSocket. Enter a ws:// or wss:// URL and click Connect. Once connected, you can send messages in the message panel and watch all incoming and outgoing messages in the conversation log with timestamps.

Server-Sent Events (SSE): Connect to an SSE endpoint and watch the event stream in real time. Useful for testing event-driven APIs and long-polling endpoints.

Socket.IO: Connect to Socket.IO servers, subscribe to events, and emit messages. Hoppscotch handles the Socket.IO handshake automatically.

MQTT: Connect to MQTT brokers. Subscribe to topics and publish messages — useful for IoT API testing.

These realtime testing modes are uncommon in Postman (which added WebSocket support later and more clumsily). For teams working with WebSocket APIs, event streams, or message queues, Hoppscotch's realtime panel is a significant advantage.

Team Collaboration Features

Log in to Hoppscotch with a work account and create a Team Workspace. Team workspaces allow:

• Shared collections — collections visible to all team members
• Shared environments — environment variables accessible to the whole team
• Role-based access — Owner, Editor, Viewer roles per workspace
• Invite by email — add team members to a workspace

The free plan supports teams with limited members and collections. The Pro plan (paid, cloud-hosted) removes limits and adds audit logs, SAML SSO, and priority support.

For self-hosted instances, team features require the paid Enterprise license — but you control all data on your own infrastructure.

Self-Hosting with Docker

For teams that can't send API requests through a third-party service, Hoppscotch offers a complete self-hosted stack.

The minimal self-hosted setup requires PostgreSQL and three containers: the app frontend, the backend API, and an admin dashboard.

# docker-compose.yml (simplified)
version: "3.8"

services:
  hoppscotch-app:
    image: hoppscotch/hoppscotch:latest
    ports:
      - "3000:3000"
    environment:
      VITE_BASE_URL: https://hoppscotch.yourcompany.com
      VITE_SHORTCODE_BASE_URL: https://hoppscotch.yourcompany.com
      VITE_BACKEND_GQL_URL: https://hoppscotch-backend.yourcompany.com/graphql
      VITE_BACKEND_WS_URL: wss://hoppscotch-backend.yourcompany.com/graphql

  hoppscotch-backend:
    image: hoppscotch/hoppscotch-backend:latest
    environment:
      DATABASE_URL: postgresql://user:password@db:5432/hoppscotch
      JWT_SECRET: your-jwt-secret
      TOKEN_SALT_COMPLEXITY: 10
      SESSION_SECRET: your-session-secret

  db:
    image: postgres:15
    environment:
      POSTGRES_DB: hoppscotch
      POSTGRES_USER: user
      POSTGRES_PASSWORD: password
    volumes:
      - pgdata:/var/lib/postgresql/data

volumes:
  pgdata:

Run docker compose up -d. Navigate to http://localhost:3000. The first user to sign up becomes the admin.

The full configuration guide is in the Hoppscotch documentation. Key configuration: OAuth providers (Google, GitHub, Microsoft), SMTP for email invites, and the AIO (all-in-one) image if you want a single container.

Comparison with Postman

Hoppscotch's weakest area compared to Postman is the collection runner and CLI maturity. Postman's Newman runner has years of integrations, richer reporting formats, and more configuration options. Hoppscotch's CLI (@hoppscotch/cli) is newer and improving, but not yet at Newman's level.

For browser-based testing, quick API exploration, and teams with data-sensitivity requirements who need self-hosting, Hoppscotch is an excellent choice — and for realtime protocol testing, it's genuinely better than Postman.