This guide builds a working chain step by step, shows the common patterns (login tokens, created ids, pagination, polling) and explains the variable rules that make chains work or quietly break. The examples use swc.*, Swastik Codes' scripting API; it is the same object as Postman's pm.*, so you can write pm. instead and Postman scripts run unchanged.

Why chain requests

Real API workflows are rarely a single call:

• Log in, then call protected endpoints with the token from the login response.
• Create, then read, update and delete the resource using the id the create call returned.
• Follow pagination using the cursor or next-page URL from each page.
• Start a job, then poll until its status says it is finished.

Copying values from one response into the next request by hand works once. It does not work in a test suite you run every day, in CI or on a schedule. Chaining makes the sequence repeatable.

The building blocks

Variables resolve from the narrowest scope that defines them: local, then data (in a data-driven run), environment, collection, then global. The environments and variables page describes the scopes in full.

Step by step: a three-request chain

This example uses JSONPlaceholder, a free fake REST API, so you can follow along in the app with a free account. The chain finds a user by username, lists that user's posts, then loads the comments on the first post.

1. Set up a collection and a base URL

Create a collection called Chaining demo. In its Variables tab add:

Declaring userId and postId up front is optional but worth doing, for a reason explained in the section on variable rules below.

2. First request: find the user and save the id

Create a GET request to {{baseUrl}}/users?username=Bret, save it in the collection as Find user, and add this Post-response script in the Scripts tab:

const users = swc.response.json();

swc.test('user was found', function () {
  swc.response.to.have.status(200);
  swc.expect(users).to.be.an('array').with.lengthOf(1);
});

swc.collectionVariables.set('userId', users[0].id);

Send it. The API returns an array with one user whose id is 1, and the script stores 1 in the collection variable userId. Open the collection's Variables tab and you will see the new value.

3. Second request: use the id, save the next one

Create List posts: GET {{baseUrl}}/posts?userId={{userId}}. The variable is highlighted in the URL, and shown in red if it does not resolve. Its post-response script:

const posts = swc.response.json();

swc.test('user has posts', function () {
  swc.response.to.have.status(200);
  swc.expect(posts).to.be.an('array').that.is.not.empty;
  swc.expect(posts.every(function (p) { return p.userId === Number(swc.collectionVariables.get('userId')); })).to.be.true;
});

swc.collectionVariables.set('postId', posts[0].id);

4. Third request: use both

Create Get comments: GET {{baseUrl}}/posts/{{postId}}/comments, with a test:

swc.test('comments belong to the post', function () {
  const comments = swc.response.json();
  swc.expect(comments).to.not.be.empty;
  comments.forEach(function (c) {
    swc.expect(c.postId).to.eql(Number(swc.collectionVariables.get('postId')));
  });
});

The tests convert with Number(...) so the comparison works whether the stored value comes back as a number or as text.

5. Run the chain

Open the collection's menu in the sidebar and choose Run collection. The collection runner shows the run order (the order of the requests in the collection, which you can change for the run), sends each request, runs its scripts and passes the updated variables to the next request. The summary shows every test for all three requests. Export it as JSON, JUnit XML or HTML if you need to share the result.

Pattern: log in and reuse the token

The most common chain is authentication. Suppose your API has POST /auth/login that returns {"access_token": "...", "expires_in": 3600}.

The Login request (with No auth in its Authorization tab, since it is how you get credentials) has a JSON body that uses environment variables:

{
  "email": "{{email}}",
  "password": "{{password}}"
}

and a post-response script:

swc.test('login succeeded', function () {
  swc.response.to.have.status(200);
});

const body = swc.response.json();
swc.environment.set('token', body.access_token);
swc.environment.set('tokenExpiresAt', Date.now() + body.expires_in * 1000);

Then open the collection, set its Authorization to Bearer token with the value {{token}}, and leave the other requests on Inherit auth from parent. Every request after Login is sent with the fresh token. Put Login first in the collection so the runner sends it first. The JWT authentication testing guide covers what to assert about the token itself.

swc.environment.set writes to the active environment, so select one before you run. If no environment is active, use swc.collectionVariables.set instead.

Fetching the token only when needed

Instead of a separate login request, a collection-level Pre-request script can fetch a token with swc.sendRequest whenever there is none or it has expired. Collection scripts run before every request in the collection:

const expiresAt = Number(swc.environment.get('tokenExpiresAt') || 0);

if (!swc.environment.get('token') || Date.now() > expiresAt - 30000) {
  swc.sendRequest({
    url: swc.environment.get('baseUrl') + '/auth/login',
    method: 'POST',
    header: [{ key: 'Content-Type', value: 'application/json' }],
    body: {
      mode: 'raw',
      raw: JSON.stringify({ email: swc.environment.get('email'), password: swc.environment.get('password') })
    }
  }, function (err, res) {
    if (err) { console.log(err); return; }
    const body = res.json();
    swc.environment.set('token', body.access_token);
    swc.environment.set('tokenExpiresAt', Date.now() + body.expires_in * 1000);
  });
}

Requests made with swc.sendRequest go through the same network rules as normal sends and show up in the console, so you can see what the script sent. For standard OAuth 2.0 flows the built-in OAuth 2.0 auth type is simpler, since it gets and refreshes tokens without a script; see OAuth 2.0 in an API client.

Pattern: create, then read, update and delete

A create call gives you the id the rest of the CRUD chain needs. Many APIs return it in the body; some only in the Location header.

// Post-response script of "Create order"
swc.test('order created', function () {
  swc.response.to.have.status(201);
});

const order = swc.response.json();
swc.collectionVariables.set('orderId', order.id);

// If the API only sends a Location header such as /orders/ord_123:
const location = swc.response.headers.get('Location');
if (location) {
  swc.collectionVariables.set('orderUrl', location);
}

The following requests use {{baseUrl}}/orders/{{orderId}}: GET to confirm it exists, PATCH to change it, DELETE to remove it, and a final GET that expects 404. That last request is easy to forget and catches APIs that only pretend to delete. If you are unsure which codes to expect at each step, see HTTP status codes explained.

Pattern: values inside JSON bodies

Variables work inside request bodies too. When the next request needs a value in its body:

{
  "orderId": "{{orderId}}",
  "quantity": 2,
  "note": "created by run at {{$isoTimestamp}}"
}

{{$isoTimestamp}} is a dynamic variable, generated fresh on each send, alongside others such as {{$guid}} and {{$randomInt}}. If you need a value that is not a plain string, such as an array or an object from the previous response, store it as JSON and insert it without quotes:

swc.collectionVariables.set('itemIds', JSON.stringify(swc.response.json().items.map(function (i) { return i.id; })));

{ "ids": {{itemIds}} }

Pattern: loops and polling with setNextRequest

The runner normally goes top to bottom. A script can change that with swc.execution.setNextRequest('Request name'), which jumps to the named request next, or swc.execution.setNextRequest(null), which ends the iteration. This is how you follow pagination:

// Post-response script of "List orders" (URL: {{baseUrl}}/orders?cursor={{cursor}})
const page = swc.response.json();

if (page.next_cursor) {
  swc.collectionVariables.set('cursor', page.next_cursor);
  swc.execution.setNextRequest('List orders');
} else {
  swc.collectionVariables.set('cursor', '');
}

Polling a background job looks the same: repeat Check job status until the job reports done, then jump on to Download result. Add a delay between requests in the runner settings so you poll politely, and make sure the loop has an exit, because a job that never finishes would otherwise keep the run going until you stop it. setNextRequest is meant for collection runs and monitors; it does not change anything when you click Send on a single request.

Variable rules that decide whether a chain works

Which scope to use. Use collection variables for values that belong to one API's test flow (ids, cursors). Use environment variables for values that differ between staging and production, such as base URLs and credentials, and for tokens tied to those credentials. swc.variables.set sets a local variable: when you click Send it lasts only for that request, so it is the wrong choice for passing a value to a request you send later by hand.

Shared versus personal values. Every variable has an initial value, shared with your team, and a current value, which stays on your device and is never stored on the server. When a script updates a variable that already exists, it changes the current value. When a script creates a variable that does not exist yet, the value becomes its initial value, which is shared when the collection or environment syncs. So declare token (with an empty initial value) before your scripts set it, and a real token never ends up in the shared copy.

Single sends versus runs. When you click Send, changes to environment, collection and global variables are written back as soon as the scripts finish, so you can run a chain by hand, one request after another. Collection variables are only written back when the request is saved in that collection. In the collection runner, changes always flow from one request to the next within an iteration. The Persist variables between requests option (on by default) also keeps them between iterations and writes them back to your environment after the run; turn it off when every iteration should start from the same initial values.

Debugging. If a request is sent with an empty value, open the console panel. It shows the request exactly as sent, after variable substitution, plus anything your scripts logged. Logging the value you extract is often the fastest check:

console.log('saving userId', users[0] && users[0].id);

Chaining without scripts: Flows

If you prefer not to write scripts, Flows chain saved requests on a visual canvas. Each node's output becomes the next node's input: after a login request, a Select node on body.token picks out the token, and the next request uses it as {{input}}, for example in an Authorization: Bearer {{input}} header. Condition, Loop and Delay nodes handle branching and polling. Flows suit workflows that branch or loop over data, while the collection runner with scripts suits test suites with assertions and reports. Both use your saved requests.

Common mistakes

• Running requests in the wrong order. The runner follows the collection order unless you reorder it or use setNextRequest. Put the request that produces a value before the one that uses it.
• No active environment. swc.environment.set has nowhere to write. Select an environment or use collection variables.
• Reading the body of an error. If login fails, swc.response.json().access_token is undefined, and every later request fails with 401. Test the status before extracting, so the first failure explains the rest.
• A stale value from an earlier run. A variable keeps its last value. Clear it at the start of a run (swc.collectionVariables.unset('orderId') in the first request's pre-request script) if a leftover value could hide a failure.

Frequently asked questions

How do I use a response value in the next request?

In the first request's post-response script, read the value and save it: swc.collectionVariables.set('id', swc.response.json().id). In the next request, use {{id}} wherever the value is needed.

Do Postman pm.environment.set scripts work for chaining?

Yes. pm and swc are the same object in Swastik Codes, so pm.environment.set, pm.collectionVariables.set and pm.response.json() behave the same way. Imported Postman collections keep their chains.

How do I save a value from a response header?

Use swc.response.headers.get('Header-Name'), for example swc.collectionVariables.set('orderUrl', swc.response.headers.get('Location')).

Can I chain requests without running the whole collection?

Yes. Variables set by scripts are saved when you click Send, so you can send the requests one at a time in order. Use the collection runner when you want the chain to run unattended, or a folder run to run only part of it.

Can I run a chain of requests on a schedule?

Yes. Attach the collection to a monitor and it runs on a cron schedule with the same scripts, alerting you by email or webhook when a test fails.

Step 1: get a cURL command

You usually already have one: from API documentation, a teammate's message, a terminal history or a bug report. If the request comes from a website or web app, the browser can produce one for you.

Copy as cURL from browser devtools

• Chrome and Edge: open DevTools (F12), go to the Network tab, reload or trigger the request, right-click it and choose Copy → Copy as cURL. On Windows there are two variants, Copy as cURL (cmd) and Copy as cURL (bash).
• Firefox: in the Network tab, right-click the request and choose Copy Value → Copy as cURL. On Windows, Firefox also offers POSIX and Windows variants.
• Safari: enable the Develop menu, open Web Inspector, go to Network, right-click the request and choose Copy as cURL.

A copied command contains every header the browser sent, including Cookie and Authorization. Treat it like a password: do not paste it into public issues or chat channels, and remove headers you do not need (sec-ch-ua, sec-fetch-*, priority and similar browser-only headers rarely matter to an API).

If you want many requests at once rather than one, save the whole Network log as a HAR file instead; Swastik Codes imports HAR files as a collection.

Step 2: import the cURL command

There are two ways in.

Paste into the URL bar. Open a new HTTP request in the app and paste the full command where the URL goes. It is recognised because it starts with curl, and the method, URL, query parameters, headers, body, auth and relevant settings are filled in. A short confirmation appears.

Use the import dialog. Open the command palette (Ctrl+K or Cmd+K) and run Import cURL / paste raw text…, or open Import and paste the text. The import dialog is the better choice for commands copied from Windows or for several commands at once:

• It understands POSIX quoting ('…', "…" and $'…' strings) and ` line continuations, the cmd flavour with ^` escapes that browsers produce on Windows, and PowerShell backtick continuations.
• Several commands in one paste become one collection with a request per command.
• Anything it cannot carry over is reported as a warning instead of being dropped silently, for example a proxy (-x), client certificates (--cert, --key, --cacert) or a cookie file. Proxies and certificates are configured in the app's settings instead.

Here is a typical command to try:

curl -X POST 'https://httpbin.org/post?source=docs' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer abc123' \
  --data-raw '{"sku":"A-1","quantity":2}' \
  --compressed

After the import you have a POST request with a source=docs query parameter, two headers and a raw JSON body. Send it to check that it behaves as in your terminal. Sending from the web app needs a free account, and the target must be publicly reachable; for localhost see how to test a localhost API.

How each cURL flag is imported

In the import dialog, --digest and --ntlm next to -u set the auth type to Digest or NTLM, and --http2 or --http1.1 set the request's HTTP version. Output-only flags such as -s, -v, -i, -o and -w are ignored because they only affect how curl prints.

File references need attention: the web app cannot read a path on your disk, so check file fields in the Body tab and select the file there before sending.

Step 3: generate Python, JavaScript or other code

With the request open, click the Code snippet button in the request toolbar (or run Generate code snippet from the command palette). Choose a language and copy or download the snippet. The 30 targets are:

Two options matter:

• Resolve variables: on, {{baseUrl}} and {{token}} are replaced with their current values; off, the placeholders stay. Resolved snippets can contain real secrets.
• Snippet settings: indent with spaces or tabs, the indent width, and whether to trim the request body.

The request's auth is applied in the snippet, including auth inherited from a folder or collection, so a Bearer token becomes an Authorization header. Generating code never sends the request. The code generation page has the details.

The round trip also works the other way: build or fix a request in the app, then pick cURL as the target to get a command for a terminal or a bug report.

Converting by hand: cURL to Python requests and fetch

If you only need one conversion, or want to understand what a generator produces, these are the equivalents for the common flags.

Method, headers and a JSON body (-X, -H, --data-raw)

curl -X POST https://api.example.com/v1/orders \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer abc123' \
  --data-raw '{"sku":"A-1","quantity":2}'

import requests

resp = requests.post(
    "https://api.example.com/v1/orders",
    headers={"Authorization": "Bearer abc123"},
    json={"sku": "A-1", "quantity": 2},  # json= sets Content-Type: application/json
)
print(resp.status_code, resp.json())

const resp = await fetch('https://api.example.com/v1/orders', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    Authorization: 'Bearer abc123',
  },
  body: JSON.stringify({ sku: 'A-1', quantity: 2 }),
});
console.log(resp.status, await resp.json());

Form data (-d)

curl -d 'name=Ada&role=admin' https://api.example.com/users sends application/x-www-form-urlencoded and uses POST because data is present.

requests.post("https://api.example.com/users", data={"name": "Ada", "role": "admin"})

await fetch('https://api.example.com/users', {
  method: 'POST',
  body: new URLSearchParams({ name: 'Ada', role: 'admin' }), // sets the form content type
});

Basic auth (-u)

curl -u ada:secret https://api.example.com/me sends Authorization: Basic with ada:secret Base64-encoded.

requests.get("https://api.example.com/me", auth=("ada", "secret"))

// Browser: btoa(); in Node.js use Buffer.from('ada:secret').toString('base64')
await fetch('https://api.example.com/me', {
  headers: { Authorization: 'Basic ' + btoa('ada:secret') },
});

File upload (-F)

curl -F 'title=Report' -F 'file=@report.pdf' https://api.example.com/upload sends multipart/form-data.

with open("report.pdf", "rb") as f:
    requests.post(
        "https://api.example.com/upload",
        data={"title": "Report"},
        files={"file": ("report.pdf", f, "application/pdf")},
    )

const form = new FormData();
form.append('title', 'Report');
form.append('file', fileInput.files[0]); // a File or Blob
await fetch('https://api.example.com/upload', { method: 'POST', body: form });
// Do not set Content-Type yourself: the multipart boundary is added for you.

Insecure TLS (-k)

requests.get("https://dev.internal/health", verify=False)  # or verify="/path/to/ca.pem"

fetch in a browser has no equivalent; the browser decides whether to trust a certificate. In Node.js you can pass a custom dispatcher from the undici package with connect: { rejectUnauthorized: false }. In every language, prefer trusting the specific CA over turning verification off.

Redirects (-L) and compression (--compressed)

curl does not follow redirects unless you pass -L. Python requests follows them by default (set allow_redirects=False to stop), and fetch follows them by default (redirect: 'manual' or 'error' to change that). Both libraries request compressed responses and decompress them automatically, so --compressed usually needs no translation.

Common conversion mistakes

• Dropping the method change. -d or -F without -X still means POST. A converted GET with a body is a frequent bug.
• Sending JSON as form data. -d '{"a":1}' without a Content-Type: application/json header is sent as application/x-www-form-urlencoded by curl. Many servers then reject it; add the header (or use --json) in the original command too.
• Setting the multipart Content-Type by hand. The boundary must match the body, so let the library generate the header.
• Quoting on Windows. Single quotes do not work in cmd. Use the browser's cmd variant or paste into the import dialog, which handles ^ escapes.
• Leaking tokens. Generated snippets with resolved variables, and commands copied from devtools, contain live credentials. Rotate anything that ends up somewhere public.

Frequently asked questions

How do I convert a cURL command to Python requests?

Paste the command into a Swastik Codes request (URL bar or import dialog), open the Code snippet panel and choose Python - Requests. By hand: -X becomes the method function, -H the headers dict, -d the data argument (or json for JSON), -u the auth tuple, -F the files argument and -k verify=False.

How do I convert cURL to JavaScript fetch?

Import the command, then choose JavaScript - Fetch in the code snippet panel. By hand, -X maps to method, -H to headers, -d to body (a string, URLSearchParams or FormData), and Basic auth to an Authorization header you build yourself.

What is the difference between -d, --data-raw and --data-binary?

-d treats a leading @ as a file name and strips newlines from file contents. --data-raw sends the value as typed, even if it starts with @. --data-binary sends data exactly as given, including newlines, which matters for uploads.

Can I import several cURL commands at once?

Yes. Paste them together into the import dialog and each command becomes a request in one new collection.

Does Swastik Codes convert requests back to cURL?

Yes. Choose cURL in the code snippet panel. Other shell targets are Wget, HTTPie and PowerShell.

Is my cURL command sent anywhere when I convert it?

The import dialog parses the text with Swastik Codes' own importer (in the web app on the swastik.codes server, with an in-browser fallback; in the desktop app locally). The API named in the command is not called. Generating code never sends the request. Only pressing Send calls the API.

The rest of this guide explains why the web app cannot do it, walks through each option with concrete commands, and covers the Docker and binding problems that make a working API look unreachable.

Why an online API client cannot reach localhost

localhost is not an address on the internet. It is a name that resolves to the loopback interface, 127.0.0.1 for IPv4 and ::1 for IPv6, of whichever machine does the resolving. The same is true, in a wider sense, of private addresses such as 192.168.1.20 or 10.0.0.5: they only mean something inside your network.

A browser page is limited in what it can send. It cannot set some headers, it is subject to CORS, and it cannot open raw TCP connections for protocols such as gRPC or MQTT. So the Swastik Codes web app does not send requests from your browser tab. It sends them to the swastik.codes server, and the server makes the real request and returns the response. That is what makes custom headers, every auth type and eight protocols work in a browser.

When that server sees http://localhost:3000/health, localhost refers to the server itself, not to your laptop. For safety the server refuses private, loopback, link-local and other reserved addresses outright. A request to localhost or to 192.168.1.20 fails with an error like this:

refusing to connect to localhost: it resolves to a private or loopback address

The check runs on the resolved IP address, not on the hostname, so a public DNS name that points at 127.0.0.1 is refused too. In the web app, the error panel then offers the local bridge and the desktop app.

Would calling localhost straight from the browser work instead?

Sometimes, but it is fragile. A page served from a public HTTPS origin that calls http://localhost:3000 needs your API to send CORS headers that allow that origin, and browsers increasingly restrict public sites from reaching local and private addresses (Chrome's Private Network Access work and the newer local network access permission). Many headers cannot be set from page JavaScript at all. A client that runs outside the browser avoids all of this.

Option 1: keep the web app and run the local bridge

The swc command-line tool has a bridge command. It connects out from your computer to swastik.codes with your API key, and while it runs, the requests and collection runs you send from the web app are executed on your computer instead of our server:

swc login          # paste an API key from Account settings → API keys
swc bridge

swc bridge: requests sent from https://swastik.codes/app as you@example.com run on this computer ("dev-laptop").
✓ connected; waiting for requests
  GET http://localhost:3000/health → 200 (4 ms)
  POST http://192.168.1.20:8080/orders → 201 (18 ms)

Then click Local bridge in the app's status bar and switch it on. There is no browser extension and no CORS to configure, and nothing on your machine is opened to the internet: the bridge only takes work from your own signed-in sessions. It covers HTTP requests (REST, GraphQL queries) and collection runs; for WebSocket, gRPC, MQTT and load tests, use the desktop app. Install swc as a single file for Linux or Windows.

Option 2: use the desktop app

The Swastik Codes desktop app runs the same interface, but requests leave from your own computer through a native Rust HTTP engine instead of the swastik.codes server. Loopback and private addresses are allowed, so all of these work:

GET  http://localhost:3000/health
POST http://192.168.1.20:8080/orders
WS   ws://127.0.0.1:9001/live
gRPC localhost:50051
MQTT mqtt://10.0.0.5:1883

What you get:

• Every protocol locally: HTTP requests, collection runs, load tests, and WebSocket, Socket.IO, Server-Sent Events, gRPC, MQTT and MCP connections all start on your machine. The target sees your IP address, and your VPN, hosts file and network rules apply.
• No CORS: CORS is a rule browsers enforce on pages. A native client is not a page, so the local server does not need CORS headers for your tests to work.
• No account required: you can work in a local workspace without signing in. Signing in syncs your cloud workspaces, environments and teams between the desktop app and the browser.
• Platforms: Windows 10 or 11 (64-bit) and Linux x86_64 (.deb, .rpm or AppImage). A macOS version is not available yet; on a Mac, use one of the other options below.

The desktop app is free, like the web app.

A quick check against a local server

Start any server on port 3000. A minimal one with Node.js:

// server.mjs
import { createServer } from 'node:http';

createServer((req, res) => {
  res.writeHead(200, { 'Content-Type': 'application/json' });
  res.end(JSON.stringify({ ok: true, path: req.url }));
}).listen(3000, '127.0.0.1', () => console.log('http://127.0.0.1:3000'));

Run node server.mjs, open the desktop app, send GET http://localhost:3000/health, and you should see {"ok":true,"path":"/health"}. Add a post-response test so the check is repeatable:

swc.test('local API is up', function () {
  swc.response.to.have.status(200);
  swc.expect(swc.response.json().ok).to.eql(true);
});

Postman's pm.* syntax runs unchanged, so existing scripts work too; see writing API tests with swc.* scripts.

Keep one collection for local, staging and production

Put the base URL in a variable rather than in every request: {{baseUrl}}/health. Create an environment per target, for example local with baseUrl = http://localhost:3000 and staging with baseUrl = https://staging.example.com, and switch between them. The environments and variables page explains scopes. In the web app, choose the staging environment; in the desktop app, either works.

HTTPS on localhost

If your local server uses a self-signed certificate or one from a local CA (for example created with mkcert), the request fails certificate verification by default. Either turn off Enable SSL certificate verification in the request's Settings tab for that request, or add your local CA certificate under Settings → Certificates so verification keeps working. The second option is better if you test HTTPS behaviour itself.

Option 3: expose localhost through a tunnel

A tunnel gives your local port a temporary public HTTPS hostname. Traffic to that hostname goes to the tunnel provider and then down a connection your machine opened, so nothing on your router needs to change. This is useful when the client must be the web app, when a teammate on another network needs to call your API, or when a third-party service has to send you a webhook.

Two widely used tools:

# ngrok (needs a free account and an auth token)
ngrok http 3000

# Cloudflare Tunnel, quick mode (prints a *.trycloudflare.com URL)
cloudflared tunnel --url http://localhost:3000

Each prints a public https:// URL. Put that URL in your baseUrl variable and send from the web app as usual. Because the hostname resolves to a public address, the private-address check does not apply.

Things to know before you rely on a tunnel:

• It is public. Anyone who learns the URL can call your API. Keep authentication on, avoid real data, and stop the tunnel when you are done.
• Host header checks. Some development servers reject requests whose Host header they do not recognise. Vite (server.allowedHosts) and webpack-dev-server (allowedHosts) are common examples; add the tunnel hostname there.
• URLs change. Free or quick tunnels often get a new hostname each time they start. Keep it in a variable so you change it once.
• Extra latency and limits. Requests travel through the provider, so response times are not representative, and providers apply their own rate and size limits. Do not load-test through a tunnel.
• WebSocket and gRPC. Tunnels that support WebSocket work for wss:// testing. gRPC needs end-to-end HTTP/2, which not every tunnel mode provides; check your provider's documentation.

Option 4: deploy to a staging environment

For anything beyond a quick check, a staging deployment is the most realistic target: real TLS, a real domain, real proxies and load balancers in front of the service. It is also the only option that lets you run scheduled monitors and share a stable URL with the team. A small VM or a platform service is enough. Many problems that never appear on localhost, such as a proxy stripping a header, a body size limit or a missing CORS rule for your frontend, show up here first.

Docker networking gotchas

Many "cannot reach localhost" reports are not client problems at all. The API is running, but not where the client is looking.

The server listens on 127.0.0.1 inside a container

Inside a container, 127.0.0.1 is the container's own loopback interface. Docker's published ports forward traffic to the container's network interface, not to its loopback. A server that binds only to 127.0.0.1 inside the container is therefore unreachable through -p 3000:3000, and the request usually fails with a connection reset or an empty reply.

Bind to all interfaces inside the container:

# Node / Express
app.listen(3000, '0.0.0.0')

# Python
uvicorn main:app --host 0.0.0.0 --port 8000
flask run --host 0.0.0.0

# Vite dev server
vite --host 0.0.0.0

0.0.0.0 is a bind address meaning "every interface". It is not a destination; send your requests to localhost or the machine's IP, not to 0.0.0.0.

The port is not published

EXPOSE 3000 in a Dockerfile documents the port; it does not make it reachable from the host. Publish it when you run the container:

docker run -p 3000:3000 my-api           # host port 3000 -> container port 3000
docker run -p 127.0.0.1:3000:3000 my-api # only reachable from this machine

With Docker Compose, use ports: ["3000:3000"]. Run docker ps and check the PORTS column: 0.0.0.0:3000->3000/tcp means it is published.

The API is in a container and calls something on the host

From inside a container, localhost is the container. To reach a service on the host machine, use host.docker.internal. Docker Desktop provides that name automatically. On Linux with Docker Engine, add it yourself:

docker run --add-host=host.docker.internal:host-gateway my-api

# docker-compose.yml
services:
  api:
    extra_hosts:
      - "host.docker.internal:host-gateway"

Two containers talking to each other

Containers on the same user-defined network (every Compose project gets one) reach each other by service name: http://db:5432, http://api:3000. Neither localhost nor the host's published port is the right address between containers.

The server listens on 127.0.0.1 and you test from another device

The reverse case: a server bound to 127.0.0.1 on your laptop is unreachable from your phone, another computer or a VM. Bind to 0.0.0.0 (or the LAN interface) and allow the port through the firewall, then call http://<laptop-ip>:3000.

Quick diagnosis

Which option should you use?

• You like working in the browser: the local bridge. One command, and HTTP requests and collection runs from the web app reach your machine.
• Daily development on Windows or Linux, every protocol: the desktop app. No setup, and your collection works unchanged against staging later.
• You need the web app, a teammate, or an incoming webhook: a tunnel, for as long as the test lasts.
• Pre-release checks, monitors and shared testing: a staging deployment.

Whichever you choose, keep the address in an environment variable so the same requests, scripts and collection runs work everywhere. When your local API is ready to be tested properly, the guide on how to test a REST API online covers the next steps.

Frequently asked questions

Can I test a localhost API online without installing anything?

Almost. An online client that sends from its own server cannot see your machine's localhost by itself. With Swastik Codes, the only thing to install is the single-file swc tool: run swc bridge and switch on Local bridge in the web app. Without anything installed, the route is a tunnel that gives your local port a public HTTPS URL.

Why does Swastik Codes say "refusing to connect" for localhost?

The web app sends requests through the swastik.codes server, and that server refuses private, loopback and link-local addresses so it cannot be used to reach internal networks. Switch on the local bridge (swc bridge) or use the desktop app to send from your own computer instead.

Do I need to enable CORS on my local API to test it?

Not for the local bridge or a desktop client. CORS is enforced by browsers on web pages, so the bridge, the desktop app, curl and other native clients ignore it. You do need CORS if your own browser frontend, served from a different origin, calls the API.

What is the difference between 0.0.0.0 and 127.0.0.1?

As a bind address, 127.0.0.1 accepts connections only from the same machine (or the same container), while 0.0.0.0 accepts them on every network interface. Inside Docker, bind to 0.0.0.0 so published ports reach your server.

Is there a Swastik Codes desktop app for Mac?

Not yet. The desktop app is available for Windows and Linux. On a Mac, use the web app with a tunnel or a staging server for now.

Can I test a WebSocket or gRPC server on localhost?

Yes, with the desktop app: WebSocket, Socket.IO, SSE, gRPC, MQTT and MCP connections all start on your machine. See how to test a WebSocket API and the gRPC client guide for the protocol details.

What you need before you start

• An endpoint that is reachable from the public internet. The examples use https://jsonplaceholder.typicode.com, a free fake REST API, and https://httpbin.org, which echoes back what you send. Both can be called right away.
• A free Swastik Codes account. The web app needs an account; sign up with GitHub or email. There are no paid plans.
• The API's documentation, or at least the URL, the expected method and how it authenticates.

Why the API has to be public

A web page cannot send arbitrary cross-origin requests with any header it likes: the browser's CORS rules stop it. So the web app does not call your API directly. It sends the request to the swastik.codes server, which makes the real HTTP call and returns the response. To protect itself and other users, that server refuses private, loopback and link-local addresses, so http://localhost:3000 or http://192.168.1.10 will not work from the web app. For an API on your own machine, use the desktop app for Windows and Linux, which sends requests from your computer. The localhost testing guide covers that case in detail.

Step 1: send your first GET request

1. Open the app and sign in.
2. Click + at the end of the tab bar and choose HTTP. A new request tab opens with the method set to GET.
3. Paste https://jsonplaceholder.typicode.com/users/1 into the URL bar.
4. Press Send, or Ctrl+Enter.

The response panel shows 200 OK, the time the request took, the size of the response and a JSON object describing a user. That is a complete REST API test in its simplest form: you asked for a resource and the server returned it.

Step 2: choose the right HTTP method

REST APIs use the HTTP method to say what you want to do with a resource. The method picker lists GET, POST, PUT, PATCH, DELETE, HEAD and OPTIONS, and you can type a custom verb if your API uses one.

"Safe" and "idempotent" are defined in RFC 9110: a safe method does not change state on the server, and an idempotent one has the same effect whether you send it once or several times. This matters when testing. Repeating a GET or a PUT should be harmless; repeating a POST usually creates a second resource.

Step 3: add query parameters and path variables

Query parameters filter or page a list. Change the URL to https://jsonplaceholder.typicode.com/posts and open the Params tab. Add a row with the key userId and the value 1. The URL updates to .../posts?userId=1 as you type, and editing the URL updates the table: the two stay in sync. Untick a row to leave it out without deleting it.

Path variables are written with a colon. A URL such as https://jsonplaceholder.typicode.com/posts/:id shows an id field in the Params tab where you fill in the value. This keeps the request readable when you save it.

Step 4: set headers

Open the Headers tab to add request headers. The ones you will add most often:

• Accept: application/json to ask for JSON.
• Authorization for credentials (the Authorization tab can build it for you, see step 6).
• Custom headers your API requires, such as X-Api-Version or X-Request-Id.

The Headers tab also lists the headers the app generates automatically, such as Content-Type for a JSON body and the User-Agent. Expand that list to see exactly what will be sent and switch off the optional ones.

Step 5: send a JSON body

To create something you usually POST a JSON body. Create a new request:

1. Set the method to POST and the URL to https://jsonplaceholder.typicode.com/posts.
2. Open the Body tab, choose raw and set the language to JSON.
3. Enter the body:

{
  "title": "Testing a REST API online",
  "body": "First post from Swastik Codes",
  "userId": 1
}

4. Send it.

JSONPlaceholder answers 201 Created with your data plus a new id. (It is a fake API: nothing is stored, so the id will not exist if you request it later. A real API behaves the same way, minus that caveat.) A raw JSON body gets Content-Type: application/json automatically, which is what most APIs need to parse it.

The other body modes cover the remaining cases: form-data for file uploads, x-www-form-urlencoded for classic HTML-form posts, binary to send a whole file, and GraphQL for a query plus variables. For the details of each, see the REST API client page.

Step 6: add authentication

Most real APIs reject anonymous requests with 401 Unauthorized. Instead of building the Authorization header by hand, open the Authorization tab and pick a type:

• Bearer token for an access token: the app sends Authorization: Bearer <token>.
• API key for a key sent in a header or a query parameter.
• Basic for a username and password.
• OAuth 2.0 when you need to obtain a token first; see OAuth 2.0 in an API client.

Other schemes, including JWT signing, Digest, AWS Signature v4 and NTLM, are listed on the authorization page. You can test Basic auth against httpbin: send a GET to https://httpbin.org/basic-auth/demo/secret with Basic auth demo / secret and you get 200; change the password and you get 401.

Do not paste real secrets straight into requests you plan to share. Put them in an environment variable and reference it as {{token}}; see the next step.

Step 7: use variables and environments

Hard-coded URLs become a problem as soon as you have a staging and a production server. Create an environment (for example Staging) with variables such as:

Then write the URL as {{baseUrl}}/users/1 and the bearer token as {{token}}. Switching environments switches every request at once, and unresolved variables are marked in red before you send. Each variable has an initial value, which is shared with your team, and a current value, which stays on your device: keep personal tokens in the current value. More on this on the environments and variables page.

Step 8: read the response properly

A passing status code does not mean the API works. Read the whole response:

• Status line. The code and reason, for example 200 OK or 422 Unprocessable Content. If you are unsure what a code means, the HTTP status codes guide explains the common ones and what to check for each.
• Time and size. The timing breakdown splits the total into DNS lookup, TCP connect, TLS handshake, time to first byte and download, which tells you whether slowness comes from the network or from the server.
• Body. View it pretty-printed, raw or as a rendered preview, and search it. Check field names, types and values, not just that something came back.
• Headers. Content-Type, caching headers, Location after a create, rate-limit headers.
• Cookies. Cookies the server set, kept in a per-domain cookie jar.

If something looks wrong, open the console panel (Ctrl+Alt+C). It shows the exact request that went out, after variables were resolved: a missing header or a mistyped variable name becomes obvious.

Step 9: save the request to a collection

Requests you only send once are not tests. Press Ctrl+S (or Save) and the save dialog asks where to put the request: pick an existing collection or folder, or type a name to create a new collection, and give the request a clear name such as Get user or Create post.

Once your requests live in a collection you can share them with your team, run them all at once, generate code for them, and use them for mock servers and documentation. Sent requests are also kept in history, so you can recover an unsaved one.

If your requests already exist in Postman, you do not need to rebuild them: import the Postman collection.

Step 10: add a test

A test is a short JavaScript check that runs after the response arrives. Open the saved Get user request, go to the Scripts tab and choose Post-response. Paste:

swc.test('status is 200', function () {
  swc.response.to.have.status(200);
});

swc.test('responds in under a second', function () {
  swc.expect(swc.response.responseTime).to.be.below(1000);
});

swc.test('returns the expected user', function () {
  const user = swc.response.json();
  swc.expect(user.id).to.eql(1);
  swc.expect(user.email).to.include('@');
  swc.expect(user).to.have.property('address');
});

Send the request again and open the Test Results tab in the response panel, which lists each test by name with a passed/total count. Change eql(1) to eql(2) and send again to see what a failure looks like.

The script editor offers snippets such as Status code is 200, JSON value check and Validate JSON schema, so you rarely start from nothing. Scripts use the swc.* API; Postman's pm.* is the same object, so scripts written for Postman run unchanged. The guide to swc.* test scripts has many more examples.

Add a test to the Create post request too:

swc.test('post is created', function () {
  swc.response.to.have.status(201);
  const post = swc.response.json();
  swc.expect(post.id).to.be.a('number');
  swc.expect(post.title).to.eql('Testing a REST API online');
});

Step 11: run the collection

With two or more saved requests that have tests, open the collection's menu in the sidebar and choose Run collection. The collection runner lists the requests in order; you can reorder them for this run, pick an environment, set the number of iterations, add a delay between requests and choose when to stop early.

Start the run. Each request is sent in turn, its scripts run, and the summary shows how many requests and tests passed or failed and the average response time. Export the result as JSON, JUnit XML or an HTML report if someone else needs to see it.

From here you can go further:

• Pass data between requests, for example a token from a login call or an id from a create call. See chaining API requests.
• Run the same requests with many inputs from a CSV or JSON file: data-driven API testing.
• Run on a schedule with monitors, which alert you by email or webhook when tests fail.

Online API tester or something else?

They work well together. Swastik Codes can import a curl command into a request and generate a curl snippet from one; see converting curl to code.

Frequently asked questions

Can I test a REST API online for free?

Yes. Swastik Codes is free to use, with no paid plans. You need a free account to send requests, because the web app sends them through the swastik.codes server.

Can an online API tester call localhost?

Not from the Swastik Codes web app: its server refuses private, loopback and link-local addresses. Use the desktop app for Windows and Linux, which sends requests from your own machine, or deploy the API somewhere public.

What should I check when testing a REST API?

The status code, the response time, the headers (especially Content-Type) and the body: field names, types and values. Also test the failure cases: missing auth, invalid input and resources that do not exist should return the right 4xx codes.

Do I need to know JavaScript to write API tests?

Only a little. Most tests are a few lines built from snippets such as Status code is 200 and JSON value check, which the script editor inserts for you.

Will my Postman collections and tests work?

Yes, in most cases. You can import Postman collections (v2.0, v2.1 and v3), environments and globals, and scripts using pm.* run unchanged.

This guide walks through that collection step by step, with scripts you can paste into the app. It covers custom login endpoints that return a JWT. If your API uses an OAuth 2.0 provider such as Auth0, Okta or Keycloak, the token step is different; see OAuth 2.0 in an API client and come back here for the testing part.

What a JWT is

A JSON Web Token (JWT, RFC 7519) is a compact, URL-safe string that carries a set of claims. The usual form is a signed token (a JWS) made of three Base64url-encoded parts separated by dots:

header.payload.signature

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9
.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ
.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c

• The header names the signing algorithm, for example {"alg":"HS256","typ":"JWT"}.
• The payload holds the claims, for example {"sub":"1234567890","name":"John Doe","iat":1516239022}.
• The signature is computed over header.payload with a secret (HMAC algorithms such as HS256) or a private key (RS256, ES256, EdDSA and others).

A signed JWT is not encrypted. Anyone holding it can decode the payload, so tests may read the claims freely, and APIs should never put secrets in them. The server trusts a token only after it verifies the signature and checks the time-based claims.

The registered claims you will meet most often:

Roles, scopes and tenant ids are usually custom claims; test them the same way.

Step 1: log in and save the token

Create a collection for the API and a collection variable baseUrl pointing at your server, or define it per environment as described in environments and variables. Add a request:

POST {{baseUrl}}/auth/login
Content-Type: application/json

{ "email": "{{email}}", "password": "{{password}}" }

Set this request's Authorization tab to No Auth, because you do not have a token yet. Keep email and password in an environment's current values or in the encrypted vault rather than in the request.

In the request's Scripts tab, add a post-response script that checks the reply and stores the token:

swc.test('login returns 200', function () {
  swc.response.to.have.status(200);
});

const body = swc.response.json();

swc.test('response contains a JWT', function () {
  swc.expect(body.access_token, 'access_token').to.be.a('string');
  swc.expect(body.access_token.split('.')).to.have.lengthOf(3);
});

swc.environment.set('accessToken', body.access_token);
if (body.refresh_token) {
  swc.environment.set('refreshToken', body.refresh_token);
}

Field names differ between APIs (token, accessToken, access_token), so match yours. swc.environment.set needs an active environment; if you are not using one, write to swc.collectionVariables instead. If you already have Postman scripts, the same code works with pm. in place of swc..

Step 2: send the token as a Bearer header

Open the collection, select its Authorization tab, choose Bearer Token and enter {{accessToken}} as the token. Every request left on Inherit auth from parent now sends:

Authorization: Bearer eyJhbGciOi...

The login request keeps its own No Auth setting. Add a protected request such as GET {{baseUrl}}/me with a test:

swc.test('authenticated request succeeds', function () {
  swc.response.to.have.status(200);
});

swc.test('returns the logged-in user', function () {
  swc.expect(swc.response.json().email).to.eql(swc.environment.get('email'));
});

Send the login request first, then /me. In the collection runner, keep the login request at the top so every later request has a fresh token. Runs persist variables changed by scripts by default, so the token saved by the first request is used by the rest.

Step 3: decode the token and check its claims

The sandbox provides atob and btoa, which is all you need to read a JWT. Base64url uses - and _ instead of + and / and drops the padding, so convert before decoding:

function decodePart(part) {
  let b64 = part.replace(/-/g, '+').replace(/_/g, '/');
  while (b64.length % 4) b64 += '=';
  return JSON.parse(decodeURIComponent(escape(atob(b64))));
}

const token = swc.response.json().access_token;
const [headerPart, payloadPart] = token.split('.');
const header = decodePart(headerPart);
const claims = decodePart(payloadPart);
const now = Math.floor(Date.now() / 1000);

swc.test('token uses the expected algorithm', function () {
  swc.expect(header.alg).to.be.oneOf(['RS256', 'ES256']);
});

swc.test('token is issued for this API', function () {
  swc.expect(claims.iss).to.eql('https://auth.example.com');
  swc.expect(claims.aud).to.include('orders-api');
});

swc.test('token expires in about 15 minutes', function () {
  swc.expect(claims.exp).to.be.above(now);
  swc.expect(claims.exp - claims.iat).to.be.within(840, 960);
});

Add this to the login request's post-response script, after the token is saved. Put the decodePart helper at the top of any script that needs it. aud may be a string or an array, hence to.include.

A note on the alg check: a server that accepts "alg": "none" or lets the token choose its own algorithm is a well-known vulnerability, so it is worth asserting that the token uses the algorithm you expect and, below, that the API rejects other ones.

For HS256 tokens you can also verify the signature in a test with the bundled crypto-js, if your test environment knows the signing secret:

const CryptoJS = require('crypto-js');
const [h, p, s] = token.split('.');
const expected = CryptoJS.HmacSHA256(h + '.' + p, swc.environment.get('jwtSecret'))
  .toString(CryptoJS.enc.Base64)
  .replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');

swc.test('signature verifies with the test secret', function () {
  swc.expect(s).to.eql(expected);
});

Step 4: test the failure cases

Most JWT bugs are in the paths that should fail. HTTP has two status codes for them, and APIs mix them up often:

For Bearer tokens, RFC 6750 adds detail: an invalid or expired token gets 401 with WWW-Authenticate: Bearer error="invalid_token", and a token without the required scope gets 403 with error="insufficient_scope". Your API may document something else; test what it documents. See HTTP status codes for the rest of the list.

Create a folder Auth failures and add one request per case. Set each request's auth explicitly so it does not inherit the valid token.

Missing token

Same URL as /me, auth set to No Auth:

swc.test('missing token is rejected with 401', function () {
  swc.response.to.be.unauthorized;
});

swc.test('401 includes a Bearer challenge', function () {
  swc.response.to.have.header('WWW-Authenticate');
  swc.expect(swc.response.headers.get('WWW-Authenticate')).to.match(/^Bearer/i);
});

Tampered payload

Take the valid token, change a claim and keep the old signature. A correct server rejects it. Set the request to No Auth and add this pre-request script:

function decodePart(part) {
  let b64 = part.replace(/-/g, '+').replace(/_/g, '/');
  while (b64.length % 4) b64 += '=';
  return JSON.parse(decodeURIComponent(escape(atob(b64))));
}
function encodePart(obj) {
  return btoa(unescape(encodeURIComponent(JSON.stringify(obj))))
    .replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
}

const [h, p, s] = swc.environment.get('accessToken').split('.');
const claims = decodePart(p);
claims.role = 'admin';

swc.request.headers.upsert({
  key: 'Authorization',
  value: 'Bearer ' + h + '.' + encodePart(claims) + '.' + s
});

The test is swc.response.to.be.unauthorized. The same pre-request pattern covers the alg: none case: build the header {"alg":"none","typ":"JWT"}, encode it with encodePart, and send header.payload. with an empty signature. Expect 401.

Expired or wrongly signed token

You can create test tokens without touching your auth server: the JWT Bearer authorization type signs a token from the payload you type and sends it with the request. It supports HS256/384/512, RS256/384/512, PS256/384/512, ES256/384/512 and EdDSA, takes an HMAC secret (optionally Base64-encoded) or a PEM private key, accepts extra header fields such as kid, and can send the token in the Authorization header (prefix Bearer by default) or as a query parameter.

The payload is signed exactly as typed; no claims are added for you. To make an expired token, use an exp in the past:

{
  "sub": "42",
  "iss": "https://auth.example.com",
  "aud": "orders-api",
  "iat": 1700000000,
  "exp": 1700000600
}

With the real test signing secret this token has a valid signature but expired long ago, so the API should answer 401. Keep the payload and change the secret to any other value, and you have a token with an invalid signature, which should also get 401. Fields accept {{variables}}, including in the payload, so keep the secret in an environment or the vault, not in the request.

Use only a test or staging signing key for this, never a production one.

Valid token, insufficient permissions

Log in as a user without the admin role (a second login request saving userToken), then call an admin endpoint with Bearer {{userToken}}:

swc.test('non-admin gets 403, not 401', function () {
  swc.response.to.be.forbidden;
});

If this returns 401, the API is treating "not allowed" as "not authenticated", and clients will wrongly try to log in again.

Step 5: test token refresh

Short-lived access tokens are usually paired with a refresh token. Test the refresh endpoint as its own request:

// POST {{baseUrl}}/auth/refresh with body { "refresh_token": "{{refreshToken}}" }
const body = swc.response.json();

swc.test('refresh returns a new access token', function () {
  swc.response.to.have.status(200);
  swc.expect(body.access_token).to.not.eql(swc.environment.get('accessToken'));
});

swc.environment.set('previousRefreshToken', swc.environment.get('refreshToken'));
swc.environment.set('accessToken', body.access_token);
swc.environment.set('refreshToken', body.refresh_token);

If your API rotates refresh tokens, add a request that sends {{previousRefreshToken}} again and expects it to be rejected. A reused refresh token being accepted is a real security gap, and it is easy to miss without a test. Also test logout: after it, the refresh token should no longer work.

For long collection runs, a collection-level pre-request script can refresh the token when it is about to expire, with swc.sendRequest:

// paste the decodePart() helper from Step 3 here

const token = swc.environment.get('accessToken');
const exp = token ? decodePart(token.split('.')[1]).exp : 0;

if (exp - 30 < Date.now() / 1000 && swc.environment.get('refreshToken')) {
  swc.sendRequest({
    url: swc.environment.get('baseUrl') + '/auth/refresh',
    method: 'POST',
    header: { 'Content-Type': 'application/json' },
    body: { mode: 'raw', raw: JSON.stringify({ refresh_token: swc.environment.get('refreshToken') }) }
  }, function (err, res) {
    if (err) { console.log(err); return; }
    swc.environment.set('accessToken', res.json().access_token);
    swc.environment.set('refreshToken', res.json().refresh_token);
  });
}

Requests made from scripts show up in the console. More script patterns are in writing API tests with swc.* scripts, and passing values between requests is covered in chaining API requests.

Running the suite

Order the collection as: login, protected requests, the Auth failures folder, refresh. Run it in the collection runner with the environment selected, and export the results as JUnit XML or HTML if you need them in CI or a ticket. To catch a broken auth deployment early, attach the collection to a monitor and get an email or webhook alert when a test fails.

Requests from the web app are sent through the swastik.codes server, which needs a free account and refuses private and loopback addresses. An auth service on localhost needs the desktop app for Windows or Linux; see testing a localhost API.

Frequently asked questions

Should an expired JWT return 401 or 403?

401. The token is no longer valid credentials, so the request is unauthenticated. RFC 6750 specifies 401 with WWW-Authenticate: Bearer error="invalid_token" for expired tokens. 403 is for a valid token whose user or scopes are not allowed to do the action.

How do I decode a JWT in a test script?

Split the token on ., convert the second part from Base64url to Base64 (replace - with + and _ with /, then pad with =), decode it with atob and parse the JSON. The decodePart helper above does this. Decoding does not verify the signature; only the server, or a test that knows the key, can do that.

Can Swastik Codes generate a JWT for me?

Yes. The JWT Bearer authorization type signs a token from your payload on every send, with HMAC, RSA, RSA-PSS, ECDSA or EdDSA algorithms, and adds it as a header or query parameter. It is useful for services that accept self-signed tokens and for creating expired or wrongly signed tokens in negative tests.

How do I reuse one token across all requests?

Save it to a variable in the login request's test script, set the collection's auth to Bearer with {{accessToken}}, and leave the other requests on Inherit auth from parent. Set the login request itself to No Auth.

Is it safe to paste a JWT into an API client?

Treat access tokens like passwords: they grant access until they expire. Keep them in environment current values or the vault, which are not shared with your team, use test accounts, and avoid long-lived tokens.

How status codes work

Every HTTP response starts with a status code and an optional reason phrase, such as HTTP/1.1 201 Created. The code is for software; the reason phrase is for humans and is not even sent in HTTP/2 and HTTP/3. RFC 9110 says clients should ignore the phrase, so tests and client code should act on the number only.

RFC 9110, section 15, defines the five classes and most of the codes. One rule there is useful to know when testing: a client that does not recognise a code must treat it as the x00 code of its class. An unknown 499 is handled like 400, an unknown 599 like 500. That is why tests that check the class (any 2xx, any 4xx) are often more robust than tests that pin one exact code, and why APIs should not invent codes when a standard one fits.

The 4xx/5xx split matters most when testing. A 4xx says "your request is wrong; retrying it unchanged will not help". A 5xx says "the server failed". An API that returns 500 for invalid input makes clients guess.

1xx informational

You rarely see these in an API client, because the HTTP library handles them before the final response arrives.

• 100 Continue: the server is willing to receive the body of a request that was sent with Expect: 100-continue. Used for large uploads.
• 101 Switching Protocols: the server agrees to switch protocols, most often the WebSocket upgrade. If you are testing WebSockets, see testing a WebSocket API online.

2xx success

200 OK

The request succeeded and the body carries the result. When testing: do not stop at the status. Check Content-Type, the body shape and the values; a 200 with an error object inside is a common bug.

201 Created

A new resource was created (RFC 9110, section 15.3.2). The server usually identifies it with a Location header, and many APIs also return the created object. When testing: assert 201 rather than any 2xx for create endpoints, check the Location header or returned id, and fetch the new resource to confirm it really exists.

202 Accepted

The request was accepted for processing, but processing is not finished and may still fail. Common for jobs, exports and webhooks. When testing: the body should tell you how to follow up, typically a job id or a status URL. Poll it until the job finishes; the collection runner's setNextRequest is made for this (see below).

204 No Content

Success, with no body. Typical for DELETE and for PUT or PATCH when the API does not echo the resource. When testing: do not call swc.response.json() on a 204, because there is nothing to parse. Assert the status and, if relevant, fetch the resource afterwards.

3xx redirection

301 Moved Permanently and 308 Permanent Redirect

The resource has a new permanent URL, given in Location. The difference: on a 301, clients historically changed a POST into a GET when following it; a 308 (section 15.4.9) forbids changing the method.

302 Found and 307 Temporary Redirect

The same pair for temporary moves. 302 allows the historical POST-to-GET change; 307 requires the client to repeat the same method and body.

303 See Other

Points the client to another resource that it should fetch with GET. Often used after a POST to send the client to the result.

304 Not Modified

Returned to a conditional GET (with If-None-Match or If-Modified-Since) when the client's cached copy is still valid. It has no body. When testing caching: send the request once, copy the ETag, send it again with If-None-Match: "<etag>" and expect 304.

Testing redirects in Swastik Codes. By default the client follows redirects, so you see the final response. To test the redirect itself, open the request's Settings tab and turn off Automatically follow redirects; you then see the 3xx and its Location header. The same tab has Follow original HTTP method and a maximum number of redirects. Try https://httpbin.org/redirect-to?url=https://httpbin.org/get&status_code=307 with following on and off.

4xx client errors

400 Bad Request

The server cannot or will not process the request because of something it sees as a client error: malformed JSON, a missing required field, an invalid parameter. When testing: send deliberately broken input and check that the error body says what is wrong. A 400 with no explanation is hard for client developers to use.

401 Unauthorized

The request lacks valid authentication credentials. Despite the name, this is about authentication. RFC 9110 requires a 401 response to include a WWW-Authenticate header that tells the client how to authenticate. When testing: call each protected endpoint with no credentials, an invalid token and an expired token, and expect 401 each time. The JWT authentication testing guide walks through those cases.

403 Forbidden

The server understood the request and refuses to fulfil it: this user may not do this. When testing: use a valid token for a user without the right role and expect 403. Some APIs answer 404 instead to hide that a resource exists; that is allowed, but should be consistent.

404 Not Found

The server did not find anything at the target URL, or will not say whether it exists. When testing: request an id that does not exist and expect 404; a 500 here means the API crashes on unknown ids. Also check that a typo in the path gives 404 and not a misleading 200 from a catch-all route.

405 Method Not Allowed

The resource exists but does not support the method. The server must include an Allow header listing the methods it does support (section 15.5.6). When testing: send DELETE to a read-only endpoint and check both the status and Allow.

406 Not Acceptable and 415 Unsupported Media Type

406 means the server cannot produce a response in any format listed in your Accept header. 415 means it will not accept the format of the body you sent, usually a wrong or missing Content-Type. When testing: send XML to a JSON-only endpoint and expect 415.

409 Conflict

The request conflicts with the current state of the resource: a duplicate username, an edit based on an outdated version. When testing: create the same unique resource twice and expect 409 the second time.

412 Precondition Failed

A condition in the request headers, such as If-Match: "<etag>", was false. This is how APIs implement optimistic concurrency. When testing: update a resource with a stale ETag and expect 412.

422 Unprocessable Content

The server understands the content type and the syntax is correct, but it cannot process the instructions: a validation error such as an end date before a start date. Many APIs use 422 for semantic validation errors and 400 for malformed requests; others use 400 for both. Either is defensible; mixing them at random is not.

429 Too Many Requests

Defined in RFC 6585, section 4. The client has sent too many requests in a given time. The response may include a Retry-After header saying how long to wait. When testing: check that rate-limited responses carry Retry-After (or the API's documented rate-limit headers) and that your client backs off. In a collection run, a delay between requests keeps you under the limit.

5xx server errors

500 Internal Server Error

A generic server failure. When testing: a 500 is always worth a bug report; also check the body does not leak stack traces or internal hostnames.

502 Bad Gateway

A gateway or proxy got an invalid response from the server behind it. The API process may have crashed or be restarting.

503 Service Unavailable

The server is temporarily unable to handle the request, because of overload or maintenance. It may send Retry-After. When testing: this is the code a well-behaved API returns under load shedding; load testing is how you find out when it starts.

504 Gateway Timeout

A gateway or proxy did not get a response from the upstream server in time. Usually a slow query or a downstream dependency that hangs.

Asserting status codes in tests

In Swastik Codes, post-response scripts use the swc.* API, which is the same object as Postman's pm.*. The most direct check:

swc.test('status is 201', function () {
  swc.response.to.have.status(201);
});

Readable shortcuts exist for common codes and classes:

swc.test('request succeeded (any 2xx)', function () {
  swc.response.to.be.success;
});

swc.test('unknown id gives 404', function () {
  swc.response.to.be.notFound;
});

When more than one code is acceptable, compare the number directly:

swc.test('upsert returns 200 or 201', function () {
  swc.expect(swc.response.code).to.be.oneOf([200, 201]);
});

Check headers that belong with the code, too:

if (swc.response.code === 429) {
  swc.test('rate limit response says when to retry', function () {
    swc.response.to.have.header('Retry-After');
  });
}

if (swc.response.code === 201) {
  swc.test('created resource has a Location', function () {
    swc.response.to.have.header('Location');
  });
}

Put the status test first in each script. If the body is an HTML error page, swc.response.json() throws, and a failing status test tells you why far more clearly than a JSON parse error. The swc.* scripts guide covers the rest of the assertion API.

Testing negative cases with a data file

Status code tests become much more useful when they cover the failure cases. Put the inputs and expected codes in a CSV file:

userId,expectedStatus
1,200
99999,404
abc,404

Then request https://jsonplaceholder.typicode.com/users/{{userId}} and assert against the row:

swc.test('status matches the data row', function () {
  swc.response.to.have.status(Number(swc.iterationData.get('expectedStatus')));
});

Attach the file in the collection runner and each row becomes one iteration. Data-driven API testing explains the setup.

Polling a 202 job

// Post-response script of "Check job status"
const job = swc.response.json();
if (job.status === 'done') {
  swc.execution.setNextRequest('Download result');
} else {
  swc.execution.setNextRequest('Check job status');
}

In a collection run this repeats the status check until the job is done. Add a delay between requests in the runner settings so you do not hammer the API.

To try the assertions, send a GET to https://httpbin.org/status/<code> in the app: it returns whatever status you ask for, such as 429 or 503.

Frequently asked questions

What is the difference between 401 and 403?

401 Unauthorized means the request has no valid authentication; sending correct credentials may fix it, and the response must include WWW-Authenticate. 403 Forbidden means the server knows who you are, or does not need to, and still refuses; re-authenticating as the same user will not help.

Should an API return 400 or 422 for validation errors?

Both are acceptable under RFC 9110. A common convention is 400 for malformed requests (invalid JSON, wrong types) and 422 for well-formed requests that fail business validation. Pick one convention, document it and test it.

Is it wrong to return 200 with an error in the body?

It works, but it hides failures from every tool that looks at status codes: caches, proxies, monitoring and test runners. Use a 4xx or 5xx code and put the details in the body.

What is the difference between 301, 302, 307 and 308?

301 and 308 are permanent, 302 and 307 temporary. 307 and 308 require the client to keep the original method and body; 301 and 302 historically let clients change POST to GET.

When should an API use 404 instead of 403?

When revealing that a resource exists would itself leak information, RFC 9110 allows a server to answer 404 instead of 403. Whichever you choose, apply it consistently.

How do I test that an API returns the right status code?

Send the request and assert the code in a post-response test, for example swc.response.to.have.status(404). Cover the error paths as well as the happy path, and run them together in a collection run.

This guide covers both routes, explains what the generated collection contains, and shows how to keep the collection in step with the spec as it changes.

Two ways to bring in a spec

Both accept OpenAPI 3.0 and 3.1 and Swagger 2.0, in JSON or YAML.

Import as a collection

Open Import in the app and choose File, Folder, Link or Raw (paste the YAML or JSON). A link is fetched by your browser, so it must allow cross-origin requests; if it does not, download the file and use File instead. A preview lists what will be created, and the import settings for OpenAPI files let you choose:

• Naming requests: by summary or operationId, or by URL.
• Folder organization: by tag, by path segment, or no folders.
• Parameter generation: values from the spec's examples, or type placeholders such as <string> from the schema.
• Whether optional parameters are switched on, whether deprecated operations are included, and whether OpenAPI 3.1 webhooks become requests.

Add it to APIs

Open APIs in the sidebar and use Import a definition file, or create a new API and paste the definition. The spec then gets its own view with Definition, Documentation, Collection sync, Contract tests and Versions tabs. The rest of this guide mostly uses this route, because it keeps the spec and the tests connected. See API design for the editor itself.

What the generated collection contains

Generation follows the same rules on both routes:

Every URL starts with {{baseUrl}}, so changing one variable moves the whole collection to another server. Path and operation-level servers that differ from the global one are kept on those requests. If the spec has no servers, baseUrl is empty and you must set it before sending.

Step 1: set base URLs with environments

The generated baseUrl is a collection variable. Create an environment per server and define baseUrl in each:

Environment variables take precedence over collection variables, so selecting an environment switches every request at once. Put the credentials the auth expects (bearerToken, apiKey) in the same environments, as current values or in the vault, so they stay on your device. Environments and variables explains scopes in detail.

Requests from the web app are sent through the swastik.codes server, which needs a free account and does not connect to private or loopback addresses. To test a server running on your own machine, use the desktop app for Windows or Linux; see testing a localhost API.

Step 2: generate contract tests from the spec

Open the spec's Contract tests tab. It lists the operations and how many of them have a response schema, and offers two actions:

• Add to "your collection" (or Generate collection with tests if none is linked yet) writes tests into the requests of the linked collection.
• Create test suite collection builds a separate collection from the spec that holds only the generated tests, and Update test suite refreshes it later.

For each request matched to an operation by method and path, the generated script checks three things:

1. The status code is documented. A 404 passes only if the operation lists 404, a matching range such as 4XX, or default.
2. The Content-Type is documented for that response (skipped for 204).
3. The JSON body matches the documented schema, using swc.response.to.have.jsonSchema.

A generated block looks like this (shortened):

// <contract-tests> generated from "Orders API" for GET /orders/{id}. Regenerating replaces this block.
(function () {
  var contract = { "200": { "contentTypes": ["application/json"], "schema": { "type": "object", "required": ["id", "status"], "properties": { ... } } },
                   "404": { "contentTypes": ["application/problem+json"] } };
  var code = String(swc.response.code);
  ...
  swc.test('Response body matches the ' + key + ' schema', function () {
    swc.response.to.have.jsonSchema(expected.schema);
  });
})();
// </contract-tests>

The block sits between // <contract-tests> markers in the request's post-response script. Regenerating replaces only that block, so tests you wrote yourself above or below it are kept. A report after each run of the generator lists requests with no matching operation and operations that no request covers, which is a quick way to find untested endpoints.

How spec schemas become test schemas

OpenAPI schemas are close to JSON Schema but not identical, so the generator converts them:

• local $refs are inlined (a recursive reference becomes an empty schema that accepts anything);
• nullable: true (OpenAPI 3.0) becomes a null type, so null values pass;
• writeOnly properties are not required in responses;
• OpenAPI 3.0 boolean exclusiveMinimum/exclusiveMaximum become numeric bounds;
• format is dropped, so date-time or email formats are not checked;
• schemas larger than 200,000 characters are left out of the script.

If you need format checks, add your own schema test next to the block; JSON Schema validation in API tests shows how.

Step 3: add your own tests

Contract tests answer "does the response match the spec". They do not know your business rules. Add those to the request's post-response script, outside the markers:

const order = swc.response.json();

swc.test('total equals the sum of the lines', function () {
  const sum = order.lines.reduce((s, l) => s + l.quantity * l.unitPrice, 0);
  swc.expect(order.total).to.be.closeTo(sum, 0.001);
});

swc.collectionVariables.set('orderId', order.id);

Saving ids like this lets later requests use {{orderId}}, so a create → read → update → delete sequence can run end to end. Chaining API requests covers the pattern, and writing tests with swc.* scripts lists the assertions.

Also test the error paths the spec documents. Duplicate a request, send an invalid body or a missing id, and the contract test checks that the error status and its schema are documented too.

Step 4: lint the spec

Tests generated from a broken spec give misleading results, so fix the definition first. The Definition tab validates on the server as you edit and lists errors and warnings with the file, line, JSON path and rule. Typical findings:

Click an issue to jump to it. A definition can span several files with $refs between them; one file is the root, and validation resolves references across files.

Step 5: keep the collection and the spec in sync

When the spec changes, the header of the spec view shows Collection out of sync. Press Update collection. In the default Sync mode the merge is keyed on METHOD /path:

• new operations are added as requests;
• changed operations are updated;
• request ids, test scripts, auth, saved examples and values you edited are kept;
• requests whose operation was removed are kept as orphans, unless you tick Remove orphan requests.

A sync report lists what was added, updated, removed or orphaned. The other mode, Replace, regenerates every request and loses your edits, so choose it only on purpose. After a sync, run the contract test generator again so the embedded schemas match the new spec; it replaces only the marked blocks.

Tag a version under Versions when you release. Each version records a changelog of added, changed and removed operations against the previous one.

Step 6: run the whole suite

From the Contract tests tab, Run test suite (or Run on the linked collection) opens the collection runner. Pick the environment, set iterations or a data file if needed, and start. The summary shows passed and failed tests per request, and you can export the run as JSON, JUnit XML or a self-contained HTML report. To check the API against its spec every hour or every day, attach the collection to a monitor.

Frequently asked questions

Can I import Swagger 2.0 as well as OpenAPI 3?

Yes. Swagger 2.0, OpenAPI 3.0 and OpenAPI 3.1 are supported, in JSON or YAML. For Swagger 2 the base URL is built from schemes, host and basePath.

Does it validate responses against the OpenAPI schema?

Yes, through generated contract tests. Each test checks that the status and content type are documented and that the JSON body matches the response schema. Formats are not checked by the generated tests, and request bodies are not validated.

Will updating the collection delete my tests?

No. Sync mode keeps your scripts, auth, examples and edited values, and the generated contract tests live in a marked block that is the only part regenerated. Only Replace mode rebuilds requests from scratch.

What if my spec has no servers?

The baseUrl variable is created empty. Define baseUrl in an environment or on the collection before sending. The linter warns about this with the no-servers rule.

Can I go the other way, from a collection to OpenAPI?

Yes. Collections export to OpenAPI 3 in JSON or YAML; see import and export.

This guide explains what JSON Schema is, which draft to write, how to build a schema for a real response, and the mistakes that make schema tests pass when they should fail.

What JSON Schema is

JSON Schema is a vocabulary for describing the shape of JSON data: which type each value has, which properties are required, which values are allowed. A schema is itself a JSON document:

{
  "type": "object",
  "required": ["id", "email"],
  "properties": {
    "id": { "type": "integer", "minimum": 1 },
    "email": { "type": "string", "format": "email" }
  }
}

In API testing a schema replaces dozens of field-by-field checks. Instead of asserting that id is a number, email is a string and address is present, you describe the response once and validate the whole body in one test. It catches the problems individual assertions miss: a field that turned into a string, a property that disappeared, a null where the client expects an object.

Which draft to use

JSON Schema has gone through several drafts. The main ones in use:

Write draft-07 schemas and leave out $schema, or set it to http://json-schema.org/draft-07/schema#. A $schema pointing at draft-04, draft-06, 2019-09 or 2020-12 makes the test fail with no schema with key or ref, because only the draft-07 meta-schema is loaded.

OpenAPI uses JSON Schema too, with differences. OpenAPI 3.0 schemas are a modified subset of an older draft and add nullable; OpenAPI 3.1 aligns with 2020-12. Copying a schema from a spec usually works, with the caveats in the mistakes section below. If the API has an OpenAPI file, you can also have the tests generated; see importing an OpenAPI spec and generating tests.

Write a schema for a real response

Take an order endpoint that returns:

{
  "id": "ord_8f2k1",
  "status": "paid",
  "createdAt": "2026-10-23T09:12:44Z",
  "customer": { "id": 42, "email": "ada@example.com" },
  "items": [
    { "sku": "BK-101", "quantity": 2, "price": 12.5 }
  ],
  "total": 25.0,
  "couponCode": null
}

Write the schema from the contract you expect, not just from one sample. Mark what is always present as required, constrain enums and patterns, and say explicitly which fields may be null:

const orderSchema = {
  type: 'object',
  required: ['id', 'status', 'createdAt', 'customer', 'items', 'total'],
  additionalProperties: false,
  properties: {
    id: { type: 'string', pattern: '^ord_[a-z0-9]+$' },
    status: { type: 'string', enum: ['pending', 'paid', 'shipped', 'cancelled'] },
    createdAt: { type: 'string', format: 'date-time' },
    customer: {
      type: 'object',
      required: ['id', 'email'],
      properties: {
        id: { type: 'integer', minimum: 1 },
        email: { type: 'string', format: 'email' }
      }
    },
    items: {
      type: 'array',
      minItems: 1,
      items: { $ref: '#/definitions/lineItem' }
    },
    total: { type: 'number', minimum: 0 },
    couponCode: { type: ['string', 'null'] }
  },
  definitions: {
    lineItem: {
      type: 'object',
      required: ['sku', 'quantity', 'price'],
      properties: {
        sku: { type: 'string' },
        quantity: { type: 'integer', minimum: 1 },
        price: { type: 'number', minimum: 0 }
      }
    }
  }
};

definitions with a local $ref lets you describe a repeated shape once. (2019-09 renamed this to $defs; under draft-07, definitions is the conventional name.)

Validate it in a test

Paste the schema into the request's post-response script, in the Scripts tab, and add the test:

swc.test('status is 200', function () {
  swc.response.to.have.status(200);
});

swc.test('order matches the schema', function () {
  swc.response.to.have.jsonSchema(orderSchema);
});

The editor also offers a Validate JSON schema snippet as a starting point. Results appear in the Test Results tab. When the body does not match, the message lists all errors, because Ajv runs with allErrors:

expected data to satisfy schema but found following errors:
data.status should be equal to one of the allowed values, data.items[0].quantity should be integer

The paths tell you exactly where to look. If the body is not JSON at all, it is validated as undefined and the test fails, so keep a separate status test: the first failure then explains the second.

To validate part of a response, or any value, use swc.expect:

const body = swc.response.json();

swc.test('first item matches the line item schema', function () {
  swc.expect(body.items[0]).to.have.jsonSchema(orderSchema.definitions.lineItem);
});

jsonSchema takes Ajv options as a second argument, which is useful for the format and nullable cases below:

swc.response.to.have.jsonSchema(schema, { unknownFormats: 'ignore', nullable: true });

If you prefer to call a validator directly, require('ajv') and require('tv4') are both bundled. tv4 targets draft-04 and is mostly found in older collections:

swc.test('valid with tv4', function () {
  swc.expect(tv4.validate(swc.response.json(), schema), tv4.error && tv4.error.message).to.be.true;
});

Common mistakes

Schema tests fail quietly in one direction: a loose schema passes almost anything. These are the problems that come up most.

Forgetting required

properties only describes a property if it is present. Without required, an empty object {} passes the schema above. List every field the client depends on in required, at every level of nesting.

Leaving additionalProperties open, or closing it in the wrong place

By default extra properties are allowed, so a misspelled field (totl instead of total) passes. additionalProperties: false rejects unknown fields. Decide deliberately: closed schemas catch typos and accidental data leaks, open ones tolerate an API adding fields. A common compromise is closed at the top level and open in nested objects you do not own.

additionalProperties: false only knows the properties declared next to it. If you compose a schema with allOf, properties defined inside the allOf branches count as additional and fail. Draft 2019-09 added unevaluatedProperties for this, but it is not available in draft-07, so repeat the property names at the level that sets additionalProperties: false.

Expecting nullable to work

nullable: true is an OpenAPI 3.0 keyword, not JSON Schema. Ajv ignores unknown keywords by default, so { "type": "string", "nullable": true } still rejects null. Use a type array, { "type": ["string", "null"] }, or pass { nullable: true } as the Ajv option shown above when you paste schemas from an OpenAPI 3.0 file.

Formats that are too strict, or unknown

Ajv checks common formats such as date-time, date, email, uri, uuid, ipv4 and ipv6. date-time follows RFC 3339 and requires a time zone, so 2026-10-23T09:12:44 fails while 2026-10-23T09:12:44Z passes. That is usually a real finding about the API, not a schema bug.

Formats Ajv does not know, such as OpenAPI's int32, int64, float or binary, make validation throw unknown format "int64" is used in schema. Remove them, or pass { unknownFormats: 'ignore' }.

integer versus number

integer rejects 12.5, and number accepts both. Money is often serialized as a decimal, so check what the API really sends. Also note that "1" is a string: a schema with type: 'integer' correctly fails an API that quotes its numbers.

Typos in keywords

A misspelled keyword such as require or maxlength is ignored without an error, so the constraint silently does nothing. An invalid value for a known keyword, such as type: 'strin', makes the schema invalid and the test fails with schema is invalid. When a schema test passes suspiciously easily, send a response you know is wrong and confirm it fails.

Validating the wrong root

If the endpoint returns an array, the root schema must be type: 'array' with items. A list response wrapped in an envelope ({ "data": [...], "next": "..." }) needs an object schema with data inside it.

Apply schemas across a collection

Copying schemas into every request is hard to maintain. Two approaches scale better.

One collection-level script. Post-response scripts on a collection run after every request in it. Keep the schemas there, keyed by request name, and validate whichever one applies:

// Collection > Scripts > Post-response; define orderSchema above this line
const schemas = {
  'Get order': orderSchema,
  'List orders': { type: 'array', items: orderSchema }
};

const schema = schemas[swc.info.requestName];
if (schema) {
  swc.test('response matches the schema for ' + swc.info.requestName, function () {
    swc.response.to.have.jsonSchema(schema);
  });
}

Generated from a spec. If the API is described in OpenAPI, the spec view in APIs generates contract tests that validate each response against its documented schema, converted to draft-07 (nullable becomes a null type, formats are dropped). Importing an OpenAPI spec and generating tests walks through it.

Then run the collection in the collection runner. Every request's schema test shows up in the run summary, data files can drive the same requests with different inputs (data-driven API testing), and the results export as JUnit XML for CI. A monitor can run the same collection on a schedule and alert you when a response stops matching its schema.

Requests from the web app go through the swastik.codes server, which needs a free account and does not reach private or loopback addresses; for an API on your own machine, use the desktop app for Windows or Linux.

Frequently asked questions

Which JSON Schema validator do the test scripts use?

jsonSchema assertions use Ajv 6 with allErrors enabled, which implements draft-07. tv4 (draft-04) is also bundled for older scripts, and require('ajv') gives you Ajv directly.

Does it support JSON Schema 2020-12?

No. Schemas that declare $schema as 2019-09 or 2020-12 fail, and keywords introduced in those drafts, such as unevaluatedProperties and prefixItems, are not applied. Most response schemas can be written in draft-07 without loss.

How do I allow null for a field?

Use a type array: { "type": ["string", "null"] }. The OpenAPI nullable keyword only works if you pass { nullable: true } as the second argument to jsonSchema.

Can I validate a nested object or an array item only?

Yes. Use swc.expect(value).to.have.jsonSchema(schema) with any value from swc.response.json().

Is schema validation enough on its own?

No. A schema checks shape and types, not meaning. Combine it with value checks: the right id came back, totals add up, the status code is the documented one. Writing API tests with swc.* scripts covers those assertions.

None of them is better in general. They make different trade-offs, and many systems use more than one: gRPC between internal services, REST or GraphQL at the edge. This guide compares them point by point, sums it up in a table and shows how to test each one.

REST in brief

REST (Representational State Transfer) is an architectural style described by Roy Fielding in 2000, not a protocol or a specification. In practice, a "REST API" means:

• Resources at URLs: /orders, /orders/42, /orders/42/items.
• HTTP methods for intent: GET reads, POST creates, PUT replaces, PATCH updates, DELETE removes. GET, PUT and DELETE are idempotent by definition.
• HTTP status codes for outcomes: 200, 201, 404, 409, 422 and so on (see the HTTP status codes guide).
• A representation format, almost always JSON today, negotiated with Content-Type and Accept.

GET /v1/orders/42 HTTP/1.1
Host: api.example.com
Accept: application/json
Authorization: Bearer eyJhbGciOi...

REST has no built-in schema. Teams usually describe the contract with OpenAPI, which also drives documentation, client generation and contract tests (see testing an API against its OpenAPI spec).

Strengths: works everywhere HTTP works, including browsers, curl and every language; HTTP caching, CDNs and proxies understand it; easy to debug by reading requests. Weaknesses: fixed response shapes cause over-fetching (fields you do not need) and under-fetching (several round trips to assemble one screen); versioning and consistency depend on discipline.

GraphQL in brief

GraphQL is a query language and runtime, published by Facebook in 2015 and now maintained under the GraphQL Foundation. The server publishes a strongly typed schema; the client sends an operation (query, mutation or subscription) that selects exactly the fields it needs.

query Order($id: ID!) {
  order(id: $id) {
    id
    status
    customer { name email }
    items { sku quantity }
  }
}

Over HTTP this is typically a POST to a single endpoint such as /graphql with a JSON body containing query and variables. Queries can also be sent with GET. The response is JSON with a data key and, when something failed, an errors array. Many servers return HTTP 200 even when errors is present, so a client or test must check the body, not only the status. The GraphQL over HTTP specification, being developed at the GraphQL Foundation, defines more precise status code behaviour for the application/graphql-response+json media type.

Subscriptions (server-pushed events) usually run over WebSocket using the graphql-transport-ws protocol (the graphql-ws library) or the older subscriptions-transport-ws protocol; some servers use Server-Sent Events instead.

Strengths: one round trip for nested data, no over-fetching, a self-describing schema with introspection, strong tooling for exploring and autocompleting queries, and an easy way to evolve the API by adding fields and deprecating old ones. Weaknesses: HTTP caching is harder because most traffic is POST to one URL; the server must defend against expensive queries (depth and complexity limits, persisted queries); naive resolvers cause N+1 database queries unless batched (for example with DataLoader); and error handling is less uniform than HTTP status codes.

gRPC in brief

gRPC is an open-source RPC framework, released by Google in 2015 and now a Cloud Native Computing Foundation project. You define services and messages in a .proto file, and code generators produce typed client stubs and server interfaces in many languages.

syntax = "proto3";

service OrderService {
  rpc GetOrder (GetOrderRequest) returns (Order);
  rpc WatchOrders (WatchRequest) returns (stream OrderEvent);
}

message GetOrderRequest { string id = 1; }
message Order { string id = 1; string status = 2; repeated Item items = 3; }

gRPC runs over HTTP/2 and encodes messages with Protocol Buffers, a compact binary format, by default. Every call is a POST to /package.Service/Method; the result is reported in a gRPC status code (0 OK, 5 NOT_FOUND, 14 UNAVAILABLE, 16 UNAUTHENTICATED and so on) sent in HTTP/2 trailers, alongside key-value metadata. There are four call types: unary (one request, one response), server streaming, client streaming and bidirectional streaming. Clients set deadlines, and cancellation propagates to the server.

Strengths: small payloads and efficient parsing, strict contracts with generated code, first-class streaming in both directions, and deadlines, cancellation and status codes built into the protocol. Weaknesses: browsers cannot speak native gRPC; binary payloads are not human-readable without tooling; HTTP caching and CDNs do not apply; and long-lived HTTP/2 connections need load balancing that understands HTTP/2 (layer 7) to spread calls across servers.

gRPC in the browser: gRPC-Web

Browser JavaScript has no API to control HTTP/2 framing or read trailers, which native gRPC requires. gRPC-Web is a variant protocol that browsers can use; it normally needs a translating proxy (Envoy is the common choice) or server-side support in the framework. gRPC-Web supports unary and server-streaming calls, but not client-streaming or bidirectional streaming. Alternatives such as the Connect protocol take a similar approach. If a browser frontend is the main client, this extra layer is a real cost to weigh.

Comparison table

When to choose which

Choose REST when the API is public or consumed by many unknown clients, you want HTTP caching and CDNs to work for you, the data maps naturally onto resources, or you want the lowest barrier to entry for consumers. It remains the safest default.

Choose GraphQL when you have several clients (web, iOS, Android, partners) that need different shapes of the same data, screens assemble data from many entities or backend services, and your team is ready to invest in query cost limits, batching and schema governance. A GraphQL layer in front of existing REST or gRPC services is a common pattern.

Choose gRPC when both ends are services you control, latency and payload size matter, you want strict contracts with generated clients in several languages, or you need streaming in both directions. It is a frequent choice for internal microservice traffic, often behind a REST or GraphQL gateway for external clients.

Mixing is normal. A typical layout is gRPC between internal services, a GraphQL or REST API for the frontend, and REST webhooks for partners. Choose per boundary, not per company.

How to test each style in Swastik Codes

Swastik Codes has a request type for each style, and the three share environments, variables, auth helpers and swc.* test scripts (Postman's pm.* syntax also runs unchanged). Saved requests of all three types can be run in the collection runner and on monitors.

REST

Use the REST API client: pick a method, enter the URL, add query parameters, headers, a body (JSON, form-data, URL-encoded, binary) and an auth type, and send. Then assert on status, headers and the body:

swc.test('order is returned', function () {
  swc.response.to.have.status(200);
  const order = swc.response.json();
  swc.expect(order.id).to.eql('42');
});

If you have an OpenAPI document, import it to get one request per operation. For step-by-step guidance, see how to test a REST API online and validating responses with JSON Schema.

GraphQL

Create a request and switch its type to GraphQL with the GraphQL client. Fetch the schema by introspection (or load SDL or an introspection JSON if introspection is disabled), browse types in the schema explorer, and write the query with autocomplete and a separate variables editor. Because GraphQL often returns 200 with errors, test the body:

swc.test('no GraphQL errors', function () {
  const body = swc.response.json();
  swc.expect(body.errors, JSON.stringify(body.errors)).to.be.undefined;
  swc.expect(body.data.order.status).to.be.a('string');
});

Subscriptions connect over WebSocket with graphql-transport-ws or the legacy graphql-ws protocol. The GraphQL client guide walks through each step.

gRPC

Create a gRPC request with the gRPC client. Load the service through server reflection, .proto files (single files or a folder, with import paths) or a .proto URL. Pick a method, edit the request message as JSON (an example message is generated from the schema), add metadata and a deadline, choose TLS, and invoke. Unary, server-streaming, client-streaming and bidirectional calls are all supported, and you can paste a grpcurl command or copy a request as one.

swc.test('call succeeded', function () {
  swc.response.to.have.statusCode(0); // gRPC OK
  swc.expect(swc.response.messages.count()).to.equal(1);
});

The web app does not need a gRPC-Web proxy, because the swastik.codes server makes native gRPC calls over HTTP/2 on your behalf. That server only reaches public hosts; for localhost:50051 use the desktop app for Windows and Linux. See the gRPC client guide for streaming and scripts.

Frequently asked questions

Is GraphQL faster than REST?

Not inherently. GraphQL can reduce the number of round trips and the amount of data sent, which helps on slow mobile networks, but each query may do more work on the server, and HTTP caching is harder. A well-designed REST endpoint with caching can be faster for the same screen.

Is gRPC faster than REST?

Usually, for service-to-service calls: Protocol Buffers are smaller and quicker to parse than JSON, and HTTP/2 multiplexes calls over one connection. The difference matters most at high request rates or with large messages. For a few calls from a browser, network latency dominates and the gain is small.

Can a browser call a gRPC API directly?

Not with native gRPC. Browsers need gRPC-Web (or a similar protocol such as Connect), which usually requires a proxy or server support, and it does not support client or bidirectional streaming. Testing tools that relay calls through a server, like the Swastik Codes web app, avoid this limitation for testing purposes.

Does GraphQL replace REST?

No. GraphQL solves specific problems, mainly varied client data needs and aggregation across services. Many organisations run both, and GraphQL servers often call REST or gRPC services behind the scenes.

Can I use REST, GraphQL and gRPC in the same project?

Yes, and it is common: gRPC internally, GraphQL or REST for frontends, REST for public and partner APIs. Keep each contract in its own schema format (OpenAPI, SDL, .proto) and test every layer.

Which is best for real-time data?

gRPC streaming for service-to-service streams, GraphQL subscriptions when your API is already GraphQL, and for plain HTTP APIs, Server-Sent Events or WebSocket alongside REST. See testing Server-Sent Events and testing a WebSocket API.

This guide uses the public test server at grpcb.in, which supports server reflection on port 9000 (plaintext) and 9001 (TLS), so you can follow along before pointing the client at your own service.

What you need

• A gRPC server reachable from the public internet. The relay refuses private, loopback and other reserved addresses, so localhost:50051 or an internal IP will not work from the web app. Use a staging host or a tunnel with a public hostname. The desktop app for Windows and Linux calls services from your own machine.
• Either server reflection enabled on the server, or the .proto files that describe it.
• A free Swastik Codes account. The web app needs one, because calls run through the server.

Step 1: create a gRPC request

1. Open the app and sign in.
2. Click + in the tab bar and choose gRPC from the New request menu.
3. Enter the server address. Any of these forms work: host:port, grpc://host:port (plaintext), grpcs://host:port (TLS), or http:// and https://. For the demo, enter grpcb.in:9001 and turn on Use TLS, or simply enter grpcs://grpcb.in:9001.

The address field also accepts a pasted grpcurl command, and the code button next to it copies the current call as a grpcurl command. That makes it easy to move between a teammate's terminal and the app.

Step 2: load the service definition

gRPC messages are Protobuf, so the client needs the schema before it can turn your JSON into bytes. Open the Service definition tab and pick a Schema source.

Server reflection

Choose Server reflection and click Reflect (or Load services). Swastik Codes asks the server for its services through the reflection API (grpc.reflection.v1, falling back to v1alpha for servers that only implement the older version). With grpcb.in you will see services such as hello.HelloService, grpcbin.GRPCBin and addsvc.Add. Reflection services themselves are hidden from the list.

If your server requires authentication even for reflection, add the metadata first (see Step 4); it is sent with the reflection request too.

.proto files

Many production servers disable reflection. In that case choose .proto files and:

• click Add .proto files to upload one or more files, or add a whole folder so relative import paths are kept, or
• paste a URL to a raw .proto file and click Fetch.

If your files import each other from different roots, list the directories under Import paths, one per line, exactly like protoc -I. Imports are resolved against those paths first and then by path suffix or file name. The files are compiled in memory on the server, and well-known types such as google/protobuf/timestamp.proto are available.

Click Load protos. The method dropdown in the address bar now lists every service and method, grouped by service.

Step 3: make a unary call

Select hello.HelloService/SayHello. A badge next to the tabs tells you the call shape: unary, server streaming, client streaming or bidirectional streaming.

On the Message tab, click Use example message to get a JSON skeleton generated from the request type. For SayHello it has one field, greeting. Edit it:

{ "greeting": "Swastik" }

Press Invoke. The response panel shows the received message:

{ "reply": "hello Swastik" }

along with the response metadata (headers), trailers and the final status, for example 0 OK, plus the time to the first message and the total duration. Variables work in the message, the metadata and the address, so {"greeting": "{{name}}"} is fine.

Step 4: metadata, auth and deadlines

gRPC metadata is the equivalent of HTTP headers. Add keys on the Metadata tab, for example x-request-id or x-tenant. On the Authorization tab you can choose Bearer, Basic, API key or OAuth 2.0, which become metadata entries such as authorization: Bearer …, or inherit auth from the collection.

Under Settings you will find:

• Deadline (ms): the call is cancelled with DEADLINE_EXCEEDED if it takes longer. Set it to a small value to check how your service handles a slow downstream dependency.
• TLS options: server certificate verification, a Server name override for SNI, and PEM fields for a custom CA certificate, a client certificate and a client key (for mutual TLS).
• Max send message size and Max receive message size in MB, a Keepalive interval for HTTP/2 pings, and whether to include fields with default values in the response. Proto3 omits default values on the wire, so turning this on shows 0, "" and false fields explicitly.

Step 5: streaming calls

Streaming is where browser-based tools usually give up, and where the relay design pays off.

Server streaming. Select hello.HelloService/LotsOfReplies, send {"greeting": "Swastik"} and press Invoke. The server sends ten replies, and each one appears in the log as it arrives, followed by the final status.

Client streaming and bidirectional streaming. Select LotsOfGreetings or BidiHello. Now Invoke opens the stream without sending anything yet. Write a message and click Send message as often as you like; each message is sent on the open stream. Click End stream to half-close your side. For a bidirectional method you see the server's replies interleaved with your messages; for client streaming the single reply arrives after you end the stream.

Saved messages help here. Click save in the composer to keep a message with the request, then send it again from the Saved tab in one click.

Step 6: write gRPC tests

The Scripts tab has three hooks, each with a snippet menu:

• Before invoke runs before the call. Change swc.request.metadata or set variables, for example to compute a signature.
• On message runs for every message the server sends, with the message in swc.message.
• After response runs once the call has ended, with the status, metadata, trailers and all messages in swc.response.

A typical After response script for the server-streaming call above:

swc.test('Status code is 0 (OK)', function () {
  swc.response.to.have.statusCode(0);
});

swc.test('Ten replies', function () {
  swc.expect(swc.response.messages.count()).to.equal(10);
});

swc.test('Every message has a reply', function () {
  swc.response.messages.to.have.property('reply');
});

swc.test('Fast enough', function () {
  swc.response.to.have.responseTime.below(2000);
});

And an On message check that runs per message:

swc.test('Reply mentions the greeting', function () {
  swc.expect(swc.message.data.reply).to.include('Swastik');
});

Results appear in the response panel as passed and failed tests. Because gRPC requests are saved in collections like any other request, the collection runner and monitors run them too, scripts included. The syntax is the same pm.* API used for HTTP tests; see writing API tests with pm scripts for the full picture.

A minimal gRPC server with reflection

To test your own service, enable reflection in development and staging. In Node.js with @grpc/grpc-js:

// server.mjs  (npm install @grpc/grpc-js @grpc/proto-loader @grpc/reflection)
import * as grpc from '@grpc/grpc-js';
import * as loader from '@grpc/proto-loader';
import { ReflectionService } from '@grpc/reflection';

const def = loader.loadSync('greeter.proto', { keepCase: true });
const proto = grpc.loadPackageDefinition(def);

const server = new grpc.Server();
server.addService(proto.demo.Greeter.service, {
  sayHello(call, callback) {
    callback(null, { message: `Hello, ${call.request.name}` });
  },
});
new ReflectionService(def).addToServer(server);

server.bindAsync(`0.0.0.0:${process.env.PORT || 50051}`, grpc.ServerCredentials.createInsecure(), (err) => {
  if (err) throw err;
  console.log('gRPC server ready');
});

with greeter.proto:

syntax = "proto3";
package demo;

service Greeter {
  rpc SayHello (HelloRequest) returns (HelloReply);
}
message HelloRequest { string name = 1; }
message HelloReply { string message = 1; }

In Go, register reflection.Register(s) from google.golang.org/grpc/reflection; in Python, use grpc_reflection.v1alpha.reflection.enable_server_reflection. Put the server behind a TLS-terminating proxy that supports HTTP/2 end to end, or serve TLS from the process itself.

Troubleshooting

"Load services first" stays in the method list. Reflection or proto compilation has not run yet, or it failed. Check the error under the Service definition tab.

Reflection fails with UNIMPLEMENTED. The server does not have reflection enabled. Upload .proto files instead.

The call fails with UNAVAILABLE straight away. Usually a TLS mismatch: TLS on for a plaintext port, or off for a TLS port. Many gRPC hosts behind a load balancer only accept TLS on 443.

Import errors when loading protos. Add the directory that the import statements are relative to under Import paths, or add the whole folder so relative paths are kept.

RESOURCE_EXHAUSTED on large messages. Raise the max send or receive message size in Settings. The relay caps a single message at 16 MiB.

Fields with zero values are missing from the response. That is proto3 behaviour. Turn on the option to include default-valued fields.

Frequently asked questions

Can a browser make gRPC calls directly?

Not native gRPC. Browsers do not expose the HTTP/2 trailers that gRPC relies on, which is why gRPC-Web and proxies exist. Swastik Codes runs the real gRPC call on its server and streams the results to the browser, so your service does not need gRPC-Web.

Do I need server reflection?

No. Reflection is the quickest way to load a schema, but you can always upload .proto files or fetch them from a URL instead.

Are streaming RPCs supported?

Yes: unary, server streaming, client streaming and bidirectional streaming. For streams that you send on, Invoke opens the stream, you send messages one by one, and End stream half-closes it.

Can I test gRPC services on localhost?

Not from the web app, because the relay refuses private and loopback addresses. Use the desktop app, or expose the service on a public hostname for testing.

Can I run gRPC tests on a schedule?

Yes. gRPC requests saved in a collection run in the collection runner and in scheduled monitors, with their scripts, so you can track a gRPC API over time and get an email or webhook alert when it fails.

Try it

Open Swastik Codes, create a gRPC request, enter grpcs://grpcb.in:9001, reflect and invoke SayHello. You will need a free account to send calls. The gRPC client feature page summarises every option, and if your service also exposes HTTP or GraphQL endpoints, the REST API client and the GraphQL client live in the same workspace.

This guide explains how the performance runner works, walks through a first test, and spends most of its time on the part that matters: reading the numbers correctly and knowing when a browser-based load test is enough and when it is not.

How the performance runner works

The model is simple and matches what most API tools call a "performance runner":

• A virtual user (VU) runs the selected requests in collection order, then starts again from the top, until the test ends or it is asked to stop.
• Each VU has its own variable scope, so a token saved by a login request in one VU's loop stays available for that VU's next requests. Pre-request and test scripts run for every request, exactly as they do in a normal send.
• If you attach a data file (CSV or JSON), VU number n uses row n modulo the number of rows. Ten VUs and five rows means each row is used by two VUs.
• The load profile decides how many VUs are active at each moment. The controller re-checks it every 100 ms, starting new VUs or asking the newest ones to stop after their current request.
• A sample counts as an error when there is no response, a transport error (DNS, TLS, timeout, connection reset), or an HTTP status of 400 or higher.
• When the duration is over, requests still in flight are abandoned and not counted, so the test never overruns.
• All VUs share one connection pool and one cookie jar.

The four load profiles

The setup panel draws the profile as a small chart before you run, so you can see exactly how many VUs will be active at each second.

Limits on the hosted service

The web app runs load tests on the swastik.codes server, so there are caps to keep the service fair for everyone. Currently a run can use up to 50 virtual users and last up to 300 seconds, each user can start up to 10 runs a minute, and one run per user can be active at a time. These limits may change. TLS certificate checks cannot be switched off for server-side load tests.

As with every request sent from the web app, targets must be publicly reachable: private, loopback and reserved addresses are refused. The load comes from our server's IP address, not yours, which matters if your API has an IP allowlist or a WAF that rate-limits by address.

Step by step: your first load test

1. Prepare a collection

Open the app and create a free account (sending requests from the web app requires one). Put the requests you want to test in a collection, or in a folder of it. A realistic test usually has a small flow rather than a single endpoint, for example:

1. POST {{baseUrl}}/auth/login, with a test script that saves the token;
2. GET {{baseUrl}}/products?page=1;
3. GET {{baseUrl}}/products/{{productId}}.

The login test script might be:

swc.test("login succeeded", () => swc.response.to.have.status(200));
const { token } = swc.response.json();
swc.environment.set("token", token);

and the other requests use Bearer {{token}} in their auth. Every VU works on its own copy of the variables, so each VU logs in and keeps its own token; nothing is written back to your saved environment.

Send each request once by hand first. A load test of a request that fails with 401 only tells you that it fails very quickly.

2. Open a performance test

Click New in the top bar and choose New performance test (it is also in the command palette, Ctrl+K / Cmd+K). In the Requests section choose the collection, optionally a folder ("Entire collection" by default), tick the requests to include, and pick an environment.

3. Set the load

In the Load section set Virtual users and Duration, then pick a profile and fill in its fields. For a first run, try something modest:

• profile Ramp up, start users 1, ramp-up 30 s;
• 20 virtual users;
• duration 120 s.

Optionally attach a data file if each VU should use different input, such as different user accounts.

4. Run and watch

Press Run. While it runs you see live totals (total requests, throughput, average response, P50, P90, P95, P99, error rate and current virtual users) and three charts: throughput with VUs, response time (average and percentiles), and error rate. When it finishes, a table lists each request with its count, requests per second, average, minimum, maximum, P50, P90, P95, P99 and errors. Distinct error messages are listed underneath.

5. Compare and keep the results

Finished runs are saved under Previous runs in your browser (the most recent 30 per workspace). Open an earlier run and choose it as a baseline: the charts overlay the baseline as dashed lines, and a comparison table shows whether throughput, latency and errors got better or worse. Export JSON downloads the full result if you want to keep it with a release.

Reading the numbers

Most mistakes in load testing come from reading the results wrongly, not from running the test wrongly.

Throughput is an output, not an input

You set virtual users, not requests per second. Each VU sends its next request as soon as the previous one finishes, so throughput is roughly VUs / average response time. Twenty VUs against an endpoint that answers in 100 ms give at most about 200 requests per second. If the API slows to 400 ms, the same twenty VUs produce only 50 requests per second. A drop in throughput at constant VUs is therefore a sign of slower responses, not of fewer users.

Use percentiles, not the average

The average hides the experience of the slowest users. Percentiles do not:

• P50 (the median): half the requests were faster than this. It describes the typical request.
• P95: 1 request in 20 was slower than this. This is where queueing and lock contention usually show up first.
• P99: 1 request in 100 was slower. If one page makes ten API calls, a large share of page views include at least one call this slow.

A healthy result has P95 and P99 reasonably close to P50 and stable over the run. A P99 several times higher than P50, or percentiles that climb steadily while VUs are flat, points at a saturated resource: a connection pool, a database, a thread pool or a downstream service.

Watch the error rate alongside latency

A fast run with a 30% error rate is not a fast API, it is an API that is rejecting work quickly. Check the error list: 429 means a rate limiter is doing its job, 502/503/504 usually mean an upstream or a load balancer gave up, and timeouts mean the API never answered. Remember that errors here are transport failures and HTTP status codes of 400 and above. A failing swc.test assertion on a 200 response is not counted as an error, so check your functional behaviour with the collection runner as well.

Look at the shape over time

The charts matter more than the totals. Three patterns are worth recognising:

1. Latency rises with VUs, then flattens while throughput stops growing. You found the capacity limit. The VU count where the curve bends is a useful number to write down.
2. Latency spikes during a spike profile, then recovers. Good: the system absorbs bursts. If it does not recover after the spike ends, something is stuck, such as a queue that never drains.
3. Errors start late in a fixed-load run. Something accumulates: memory, open connections, or a cache that fills up. Run longer to confirm.

Be careful with conclusions

The load comes from one region and one server, over the public internet. Measured latency includes the network path between our server and your API. Compare runs with each other, from the same setup, rather than treating one number as the truth about production. And keep the test environment as close to production as you can: a staging database with a hundred rows will not behave like one with ten million.

When to graduate to a dedicated load-testing tool

A browser-based performance runner is the right tool for quick checks: "did this release make the search endpoint slower?", "does the API hold up with 50 concurrent users?", "what happens during a burst?". It reuses the collection, variables and scripts you already have, so there is nothing to write.

For larger or more formal tests, dedicated tools such as k6, Gatling, Apache JMeter and Locust are a better fit. They can generate far more load, run from several machines or regions, model arrival rates (requests per second) rather than only concurrent users, run inside CI with pass/fail thresholds, and export to monitoring systems. They take more setup, and the tests are written as code or in their own formats, but they are built for exactly that job. A common approach is to use Swastik Codes to explore and to catch regressions early, and a dedicated tool for capacity planning before a big launch.

Frequently asked questions

Is load testing in Swastik Codes free?

Yes. Swastik Codes is free to use today. Runs are limited (currently up to 50 virtual users and 300 seconds on the hosted service) to keep it fair for everyone.

Can I load test an API running on localhost?

Not from the web app. Tests run on the swastik.codes server, which refuses private and loopback addresses. Use a publicly reachable staging URL, or run the load test in the desktop app, where virtual users run on your own computer.

Do my test scripts run during a load test?

Yes. Pre-request and test scripts run for every request in every VU, so you can log in, save tokens and chain requests. Script-heavy collections add some overhead on the client side of the test.

What counts as an error?

No response, a transport error, or an HTTP status of 400 or above. Failing test assertions are not counted as load-test errors.

Can I compare two runs?

Yes. Choose an earlier run as the baseline to overlay it on the charts and see the differences in a table.

Run your first test

Open the app, create a free account, and start with a small ramp-up test against an endpoint you own. The load testing feature page summarises the options, Writing API tests with swc.* scripts shows how to prepare tokens and assertions, and data-driven API testing explains data files in more detail.

In Swastik Codes you open a collection's menu, choose Run collection, attach the file under Data file, and press Run. This guide builds a small working example, then covers iterations, delays, failure handling, variable persistence, reports and scheduled runs.

When data-driven tests are worth it

Data files shine when the logic is the same and only the inputs and expected outputs change:

• boundary values for a validation endpoint (empty strings, maximum lengths, invalid formats),
• one test per customer tier, region, currency or feature flag,
• regression checks for a list of known ids after a migration,
• the same smoke test against many tenants.

If each case needs different logic, separate requests are clearer. If only the data changes, a data file keeps the collection small and the cases easy to review.

Before you start

Runs from the web app are executed by the swastik.codes server: the browser streams the results as they happen. That needs a free account, and the server refuses private and loopback addresses, so the API under test must be publicly reachable. The example below uses the public https://jsonplaceholder.typicode.com API.

Step 1: write the request with data variables

Create a collection called Users with one GET request named Get user:

GET https://jsonplaceholder.typicode.com/users/{{userId}}

{{userId}} is not defined in any environment; it will come from the data file. If you send the request by hand now, the variable is unresolved and the editor highlights it as missing. That is expected.

Step 2: write tests that read the row

In the request's Scripts tab, add a Post-response script that compares the response with the expected values in the same row:

const row = {
  userId: swc.iterationData.get('userId'),
  expectedStatus: Number(swc.iterationData.get('expectedStatus')),
  expectedName: swc.iterationData.get('expectedName'),
  expectedUsername: swc.iterationData.get('expectedUsername')
};

swc.test(`user ${row.userId}: status ${row.expectedStatus}`, function () {
  swc.response.to.have.status(row.expectedStatus);
});

if (row.expectedStatus === 200) {
  const user = swc.response.json();

  swc.test(`user ${row.userId}: name is ${row.expectedName}`, function () {
    swc.expect(user.name).to.eql(row.expectedName);
  });

  swc.test(`user ${row.userId}: username is ${row.expectedUsername}`, function () {
    swc.expect(user.username).to.eql(row.expectedUsername);
  });
}

Two details matter:

• CSV values are strings. As in Postman, every value read from a CSV file is a string, so expectedStatus is converted with Number() before comparing with the numeric status code. JSON data files keep their types.
• Put the row value in the test name. The run results list tests by name, so user 3: name is Clementine Bauch tells you immediately which row failed.

Step 3: create the data file

Save this as users.csv:

userId,expectedStatus,expectedName,expectedUsername
1,200,Leanne Graham,Bret
2,200,Ervin Howell,Antonette
3,200,Clementine Bauch,Samantha
11,404,,

The first line is the header: each column name becomes a variable. The last row checks that a non-existent user returns 404. JSONPlaceholder has ten users, so id 11 is not found.

The parser handles quoted fields ("Smith, John"), escaped quotes (""), line breaks inside quotes, Windows line endings and a byte-order mark, and detects semicolon- or tab-separated files from the header line.

The same data as JSON is an array of objects:

[
  { "userId": 1, "expectedStatus": 200, "expectedName": "Leanne Graham", "expectedUsername": "Bret" },
  { "userId": 2, "expectedStatus": 200, "expectedName": "Ervin Howell", "expectedUsername": "Antonette" },
  { "userId": 3, "expectedStatus": 200, "expectedName": "Clementine Bauch", "expectedUsername": "Samantha" },
  { "userId": 11, "expectedStatus": 404 }
]

JSON is the better choice when values are numbers, booleans or nested objects you want to post as a body, for example {{payload}} filled from a nested object.

Step 4: run it

1. In the sidebar, open the Users collection's menu and choose Run collection (or Run folder on a folder).
2. The runner tab shows the requests in run order. Untick any you want to leave out and use Move up / Move down to change the order.
3. Under Data file, choose Select file and pick users.csv. A preview table shows the parsed rows, and Iterations is set to the number of rows (4).
4. Pick an Environment if your requests use one.
5. Press Run.

Results stream in as each request finishes. The summary shows requests, failed requests, tests passed and failed, the average response time and the total duration. The results table lists each iteration and request with its status, time, size and tests; filter it to failed requests, or to a single iteration, and open any row to see its tests, console output and (if saved) the response.

Iterations, delays and stopping on failure

Iterations defaults to the number of data rows, or 1 without a file. If you set more iterations than there are rows, the last row is reused for the extra iterations, which matches Postman's runner and Newman.

Delay (ms) waits between requests. Use it for rate-limited APIs: with a limit of 60 requests per minute, a 1000 ms delay keeps a long run under it.

Stop the run controls failure handling:

• Never (run every request) – the default; you get the complete picture.
• On the first failure (test or error) – stop at the first failed test or error.
• On the first failed test – stop on assertion failures only.
• On the first error (send or script) – stop when a request cannot be sent or a script throws, but keep going through failed assertions.

The hosted service caps a run at 1,000 iterations and 10,000 data rows, and the delay at 60 seconds.

Variables across requests and iterations

Data-driven runs often chain requests: create something with the row's data, then read it back. The run options control how script-set variables behave:

• Persist variables between requests – within one iteration, variable changes made by scripts always carry to the next request; with this on they also carry into later iterations. Turn it off if every row should start from the same values.
• Keep variable values after the run – write the final values back to the environment, globals and collection when the run ends. Leave it off if you do not want a test run to change your working environment.

A chained example with two requests, Create post and Get post:

// Create post – Body (raw JSON):
// { "title": "{{title}}", "body": "{{body}}", "userId": {{userId}} }

// Create post – Post-response script
swc.test(`created "${swc.iterationData.get('title')}"`, function () {
  swc.response.to.have.status(201);
});
swc.variables.set('createdId', swc.response.json().id);

swc.variables.set writes a local variable that lasts for the run, so the next request in the same iteration can use {{createdId}}.

Scripts can also change the flow per row. swc.execution.skipRequest() in a pre-request script skips a request for rows that do not apply:

// Pre-request: only rows marked as admin cases call the admin endpoint
if (swc.iterationData.get('role') !== 'admin') {
  swc.execution.skipRequest();
}

Skipped requests are counted separately in the results, so they do not look like passes.

Cookies, responses and logs

Three more options are useful on long runs:

• Save responses stores response headers and bodies in the results so you can inspect failures afterwards. Turn it off for very large runs.
• Run without stored cookies starts with an empty cookie jar; Save cookies after run writes cookies the run received back to the cookie manager. Every request in one run shares a single cookie jar.
• Turn off logs during run drops console.log output, which speeds up long runs.

Reports for CI and for people

When the run finishes, export it as:

• JSON – the full result for your own tooling,
• JUnit – XML that CI systems and test dashboards understand,
• HTML – a self-contained report to attach to a ticket or send to a colleague.

Past runs are kept in the runner's run history on your device, so you can compare a failing run with the last good one.

Run it on a schedule

A data-driven collection makes a good monitor. Monitors run a collection on a cron schedule from the server and alert by email or a signed webhook, on failures, on every run, or when a failing monitor recovers. In a monitor's advanced settings you can attach iteration data (up to 1,000 rows), set the number of iterations, choose which requests run and in which order, and set retries and timeouts. See API monitoring.

Troubleshooting

Every iteration uses the same value. The column name in the file and the variable name in the request differ (check case and stray spaces in the header row), or an environment or collection variable with the same name is masking the data. Data values take precedence over environment, collection and global variables, but a local variable set by a script (swc.variables.set) takes precedence over data.

A numeric comparison fails with matching values. CSV values are strings. Convert with Number() or compare with string literals, or use a JSON data file.

The run stops early. Check Stop the run, and whether a script calls swc.execution.setNextRequest(null), which ends the current iteration.

"too_many_iterations" or "too_much_data". The run exceeds 1,000 iterations or 10,000 rows. Split the data file.

Requests fail to send. If the target is localhost or a private address, the server refuses it; use a publicly reachable environment.

Frequently asked questions

What file formats can the collection runner read?

CSV (comma, semicolon or tab separated, with a header row) and JSON arrays of objects.

How do I read a data value in a script?

swc.iterationData.get('column'). swc.iterationData.toObject() returns the whole row. In requests, use {{column}}.

Is this compatible with Postman data files?

Yes. The same CSV and JSON files work, values from CSV are strings as in Postman, and extra iterations reuse the last row as Newman does.

Can I use a data file for load tests?

Yes. Performance tests can also take a data file, so each virtual user works through realistic inputs. See API load testing in the browser.

Try it

Open the app, create the Users collection above, attach users.csv and run it. Runs need a free account. The collection runner feature page lists every option, writing API tests with swc.* scripts covers the assertions in more depth, and API monitoring explains how to run the same collection every few minutes.

This guide walks through that flow against a public GraphQL API, then covers variables, fragments, subscriptions, authentication headers and automated tests on GraphQL responses.

What you need before you start

• A GraphQL endpoint that is reachable from the internet. The web app sends requests through the swastik.codes server (a browser cannot call arbitrary cross-origin APIs), and that server refuses private, loopback and link-local addresses. http://localhost:4000/graphql will not work from the web app; a staging URL will. The desktop app for Windows and Linux sends from your own machine and reaches it.
• A free account. The web app needs one, because requests (and schema fetches) go through the server. Create one with GitHub or an email address.

For the examples below we use the public Countries API at https://countries.trevorblades.com/. It allows introspection and needs no key, which makes it a good playground.

Step 1: create a GraphQL request

1. Open swastik.codes/app.
2. Click the + button in the tab bar. The New request menu lists every request type: HTTP, GraphQL, WebSocket, Socket.IO, Server-Sent Events, gRPC, MQTT and MCP. Choose GraphQL.
3. Paste https://countries.trevorblades.com/ into the endpoint field.

If you already have an HTTP request pointing at a GraphQL endpoint, you do not need to start over: the request-type picker next to the URL converts it in place, keeping the name, URL, headers, auth and scripts.

Step 2: load the schema

With Introspect automatically when the URL is set switched on (it is in the request's Schema tab), the schema loads as soon as you enter a valid http(s):// URL. You can also press Fetch schema next to the URL. A notification tells you how many types were loaded, and the Schema tab shows the printed SDL.

Some production servers disable introspection. In that case switch Schema source to Manual (SDL or introspection JSON) and either paste the schema, use Import file, or Import from URL if your team publishes a schema.graphql. Press Apply schema and the editor behaves exactly as if introspection had worked. The manual schema is saved with the request, so teammates get it too.

Step 3: build the query

There are two ways to write the operation, and you can mix them.

The explorer. Once a schema is loaded, an Explorer button appears above the query editor. It shows the root operation types (Query, Mutation, Subscription) as a tree. Ticking a field adds it to the operation; ticking an argument adds a variable for it and fills an example value into the variables editor. On fields that return a union or an interface, the explorer offers ... on Type branches and keeps __typename in the selection so you can tell the results apart. The tree is virtualised, so large schemas with thousands of types stay responsive, and a filter box narrows the root fields.

The editor. The query editor has schema-aware completion and validation. Type { country(code: "IN") { and it suggests the fields of Country. Misspelled fields are flagged before you send.

Try this query:

query Country($code: ID!) {
  country(code: $code) {
    ...CountryBasics
    languages {
      code
      name
    }
  }
}

fragment CountryBasics on Country {
  code
  name
  capital
  currency
  emoji
}

And in the Variables (JSON) editor underneath:

{ "code": "IN" }

Press Query (the button reads Mutate for a mutation and Subscribe for a subscription). The response panel shows the JSON result:

{
  "data": {
    "country": {
      "code": "IN",
      "name": "India",
      "capital": "New Delhi",
      "currency": "INR",
      "emoji": "🇮🇳",
      "languages": [
        { "code": "hi", "name": "Hindi" },
        { "code": "en", "name": "English" }
      ]
    }
  }
}

If a document contains several named operations, a selector appears next to the section tabs so you can pick which one to run; leaving it on (first operation) runs the first.

Use environment variables inside GraphQL variables

Variables in double braces work everywhere, including the GraphQL variables editor and the URL. Create an environment with gqlUrl = https://countries.trevorblades.com/ and country = IN, then write:

{ "code": "{{country}}" }

Switching environment then switches the data without editing the request. The same works for staging and production endpoints: put {{gqlUrl}} in the URL field.

Step 4: headers and authentication

Most real GraphQL APIs need a token. Use the request's Authorization tab rather than typing a header by hand: choose Bearer Token, API Key, Basic, OAuth 2.0 or any of the other schemes. Leave it on Inherit to use the auth configured on the folder or collection, so every operation in a collection shares one token. The same credentials are sent with the introspection call, which matters for servers that only allow introspection to authenticated users.

Anything else, such as a tenant header or apollo-require-preflight, goes in Headers.

If you need an OAuth 2.0 access token first, see OAuth 2.0 in an API client.

Step 5: subscriptions

Subscriptions run over WebSocket. In the request's Settings tab you choose:

• Subscription URL – leave it empty to use the endpoint URL with the scheme changed to ws:// or wss://, or set a separate URL if your server listens elsewhere.
• Subscription protocol – graphql-transport-ws (the protocol used by the graphql-ws library and most current servers) or the legacy graphql-ws protocol from subscriptions-transport-ws.
• Connection params (JSON) – sent in the connection_init message; this is where many servers expect an auth token, for example { "authorization": "Bearer {{token}}" }.

Write a subscription { ... } operation and press Subscribe. Events stream into the message log with timestamps until you press Unsubscribe. Very large payloads (over 1 MiB) are cut for display, so the log stays usable.

The Countries API has no subscriptions, so use your own server to try this. Remember that the server must be publicly reachable from the web app.

Step 6: test the response

A GraphQL server usually answers 200 OK even when the operation failed: the problems are in an errors array. A status check alone therefore proves little. GraphQL requests have a Scripts tab with the same Pre-request and Post-response scripts as HTTP requests, using the Postman-style pm.* API. A useful baseline for the query above:

swc.test('HTTP 200', function () {
  swc.response.to.have.status(200);
});

const body = swc.response.json();

swc.test('no GraphQL errors', function () {
  swc.expect(body.errors, JSON.stringify(body.errors)).to.be.undefined;
});

swc.test('country has a capital and languages', function () {
  const c = body.data.country;
  swc.expect(c.capital).to.be.a('string').and.not.empty;
  swc.expect(c.languages).to.be.an('array').that.is.not.empty;
});

swc.test('response matches the expected shape', function () {
  swc.response.to.have.jsonSchema({
    type: 'object',
    required: ['data'],
    properties: {
      data: {
        type: 'object',
        required: ['country'],
        properties: {
          country: {
            type: 'object',
            required: ['code', 'name'],
            properties: { code: { type: 'string', minLength: 2, maxLength: 2 } }
          }
        }
      }
    }
  });
});

jsonSchema validates with Ajv inside the script sandbox. You can also save values for later requests, for example swc.environment.set('countryName', body.data.country.name). The Test Results tab of the response shows each test as passed or failed. More patterns are in writing API tests with pm scripts.

Once the requests have tests, put them in a collection and run them together in the collection runner, or on a schedule with a monitor.

Troubleshooting

"Introspection failed". Check the URL first (many servers live at /graphql, not /). If the server needs auth for introspection, set it on the Authorization tab. If introspection is disabled in production, load the schema manually as described in step 2.

The request never reaches my server. If the URL points at localhost, a 192.168.x.x address or another private network, the swastik.codes server refuses it. Use the desktop app, deploy to a reachable staging URL, or expose the service through a tunnel with a public hostname.

HTTP 200 but no data. Look at the errors array in the response. Validation errors (unknown fields, missing required variables) come back this way on most servers.

Variables are ignored. Variables must be valid JSON, and the operation must declare them (query Country($code: ID!)). Unused variables are not an error, but undeclared ones in the operation are.

Subscription connects then closes. The usual causes are the wrong protocol (graphql-transport-ws versus legacy graphql-ws) or missing auth in the connection params.

Frequently asked questions

Can I use Swastik Codes as a free online GraphQL client?

Yes. The app is free to use today. You need a free account to send requests, because the web app sends them through the swastik.codes server.

Does it support GraphQL subscriptions?

Yes, over WebSocket with either the graphql-transport-ws protocol or the legacy graphql-ws protocol, with optional connection params.

What if my server has introspection turned off?

Paste the SDL or an introspection JSON result into the Schema tab (or import it from a file or URL) and press Apply schema. Autocomplete, validation and the explorer then work from that schema.

Can I import GraphQL requests from Postman or Insomnia?

Postman collections keep their GraphQL bodies (query and variables) when imported, and you can switch such a request to the GraphQL request type with the picker next to the URL to get the explorer and subscriptions. You can also import a GraphQL SDL file: it becomes a collection with one GraphQL request per query, mutation and subscription field, plus a graphqlUrl variable to point at your endpoint. See importing a Postman collection for the details and the import and export page for all supported formats.

Can I generate code for a GraphQL request?

Yes. A GraphQL request is an HTTP POST with a JSON body, so the code generator can turn it into cURL, JavaScript fetch, Python requests and many other snippets. See code generation.

Try it

Open the app, add a GraphQL request for https://countries.trevorblades.com/, and you will have a schema-aware editor in under a minute. Sending needs a free account. The GraphQL client feature page summarises everything the client supports, and if your team also works with real-time APIs, the WebSocket client uses the same workspace, environments and history.

The rest of this guide covers each step in more detail, the other formats the same dialog accepts (Insomnia, OpenAPI, Swagger, cURL, HAR, WSDL, RAML, GraphQL), what the import notes mean, and how to export your work back out.

Step 1: export from Postman

Postman lets you export each collection and environment as a JSON file. The exact menu wording changes between versions, but the flow has been stable for years:

1. In Postman, open the Collections sidebar, open the menu (the three dots) next to the collection, and choose Export.
2. Pick Collection v2.1 when you are asked for a format. Version 2.1 is the current, widely supported schema. Version 2.0 also imports fine.
3. Save the .json file.

For environments, open the Environments sidebar, open the menu next to the environment, and choose Export. Globals can be exported from the globals view in the same way.

If you have many collections, Postman's account settings also offer a full data export (a "data dump"). It is a single JSON file containing your collections, environments and globals. Swastik Codes imports that file in one go.

Step 2: open the import dialog

Create a free account and open Swastik Codes. Signing up creates a personal cloud workspace called "My Workspace"; import there to sync the collection across devices and share it with a team. To keep it on this device only, import into the Scratch Pad instead.

There are several ways into the same Import dialog:

• the Import button in the top bar;
• the import icon at the top of the Collections sidebar;
• the keyboard shortcut Ctrl+O (Cmd+O on macOS);
• the command palette (Ctrl+K / Cmd+K), then "Import…".

The dialog has four tabs:

The Link tab fetches the file from your browser, so the host has to allow cross-origin requests. Raw files on most code hosts and public spec URLs usually do.

Step 3: review the preview and import

After you add a file, the dialog shows each source with a label for the format it detected: a Postman collection or environment, OpenAPI, HAR and so on. Below that is a list of everything that will be created: collections, environments and globals, each with a checkbox. By default everything is selected; untick anything you do not want and click Import.

If you imported a single request (a cURL command, for example), you also get Open as new request, which opens it in a tab without creating a collection.

The first imported collection opens in a tab straight away. Environments appear in the environment selector in the top bar.

Import a collection and its environment together

You can drop the collection file and the environment file in the same go. Both appear in the preview, and both are imported in one step. After importing, pick the environment in the selector and send a request to check variables resolve. Variables that resolve are highlighted, and missing ones are flagged in a different colour, so a typo in {{baseUrl}} is easy to spot.

You can also pin environments to a collection and choose a default one, so the right environment is selected whenever you open that collection's requests.

Step 4: read the import notes

When something in the file cannot be represented exactly, the preview shows a Notes list. Nothing is silently dropped. Common notes:

• "mocks in the data dump are not imported" (also monitors, headerPresets): a Postman data dump can contain these, but they are not imported. Recreate mocks and monitors from the imported collection.
• "collection 3: …" or "environment 1: …": one item in a data dump could not be read. The rest of the dump is still imported.
• cURL notes such as "proxy … was not imported; set it in the app's proxy settings" or "--cert was not imported; add certificates in settings": the option was understood, but it belongs in settings rather than in the request.
• OpenAPI notes such as "unresolved $ref" (only local #/... references are followed from a single file) or "security scheme … is not defined".

If a whole file fails, its row shows the error next to the file name and the other files can still be imported.

Other formats in the same dialog

The same dialog accepts much more than Postman files. The format is sniffed from the content, so you do not have to choose it:

• Postman: Collection v1, v2.0, v2.1 and v3, environments, globals and data dumps.
• Insomnia: v4 exports and v5 YAML. Workspaces become collections, request groups become folders, the base environment becomes collection variables, and Nunjucks references like {{ _.host }} become {{host}}. Insomnia scripts are kept with insomnia. changed to swc.. gRPC, WebSocket and Socket.IO requests become requests of those types.
• OpenAPI 3.x and Swagger 2.0, in JSON or YAML, from a file or a URL.
• cURL commands, including headers, data, form fields, basic auth and cookies.
• HAR 1.2 files from browser dev tools. Every entry becomes a request, and its response becomes a saved example.
• WSDL 1.1 and 2.0: each SOAP operation becomes a POST request with a sample envelope and the right SOAP headers.
• RAML 0.8 and 1.0: resources become folders and methods become requests.
• GraphQL SDL and introspection results.

RAML, WSDL and Postman v3 are converted by the server, so you need to be signed in for those.

OpenAPI import settings

When the source is OpenAPI or Swagger, a View import settings toggle appears. These are the options:

Change a setting and click Apply settings to re-parse before importing. If you maintain the spec itself in Swastik Codes, the API design tools can keep a generated collection in sync with it instead of re-importing.

Folders and v3

Choose the Folder tab to import a folder. This is useful for a repository of exported collections, and for Postman's Collection v3 folder layout (*.request.yaml files with a .resources/definition.yaml). Request kinds that have no equivalent are skipped with a note.

Step 5: export back out

Importing is not a one-way door. Open the menu next to a collection and choose Export, or use Export… in settings to export something else. You can export:

The export dialog shows a preview of the file, which you can copy or download. A v2.1 export is the right choice for importing back into Postman or other tools that read Postman collections.

For keeping a workspace in Git, there is also a sync option that exports a workspace as a ZIP with one JSON file per collection and environment, and imports one back with a preview of the changes.

Troubleshooting

"Nothing importable was found." The file is valid JSON or YAML but not a recognised format. Check you exported a collection rather than, for example, a run result.

Variables show as missing after import. The collection expects an environment you have not imported, or the variable only had a current value in Postman. Current values are local to each device in Swastik Codes and are never stored on the server, so set an initial value for anything the team needs.

The Link tab fails. The host does not allow cross-origin requests. Download the file and use the File tab instead.

Requests import fine but fail to send. If they target localhost or a private IP, the web app cannot reach them because requests go through the swastik.codes server, which refuses private addresses. Use a publicly reachable URL.

Frequently asked questions

Which Postman collection version should I export?

Collection v2.1. It is the current schema and the one most tools read. v2.0 and v1 also import, and v3 imports when you are signed in.

Do I need an account to import?

In the web app, yes: a free account (GitHub or email). Import into a cloud workspace to sync across devices and share with a team, or into the Scratch Pad to keep the collection in your browser only. The desktop app imports without an account.

Are my pre-request and test scripts imported?

Yes, at collection, folder and request level. They run in a sandbox that implements the documented pm.* API, so they work as imported. swc.* is Swastik Codes' name for the same API; tick Convert Postman scripts to swc.* when importing to rewrite them, and exporting to Postman writes pm.* back. See Writing API tests with swc.* scripts.

Can I import an OpenAPI spec straight from a URL?

Yes, on the Link tab, as long as the host allows cross-origin requests.

Next steps

Open the app and import a collection now, then create a free account to send requests. The import and export feature page lists every format, and Moving from Postman covers what to check once your collections are across. When you are ready to run the whole collection with a CSV of test data, read data-driven API testing.

Mock servers are free to use. This guide shows how to create one, how requests are matched to examples, how to force a specific response with x-mock-* headers, how to make responses dynamic with templates, and how to keep a mock private.

How it works in one paragraph

You have a collection with requests such as GET {{baseUrl}}/users/:id. Each request can have saved examples: a status code, headers and a body, plus the request that produced them. When a call arrives at the mock URL, the server looks for requests with the same method and path (:id and {{variables}} in the path act as wildcards), scores their examples on query parameters, headers and body, and returns the best one. If nothing matches, it answers 404 with the error code mock_request_not_found.

Step 1: create a collection with examples

Open the app and create a free account. Mock servers with a public URL live in cloud workspaces, so you need to be signed in. (You can also create a local mock that lives on your device and answers only inside the app, which is enough to try the matching rules.)

Create a collection called "Users API" and add a request:

GET {{baseUrl}}/users/:id

There are two ways to give it an example:

1. From a real response. Send the request to a real API and click Save as example above the response. The status, headers and body are saved.
2. By hand. Once the mock exists, its Examples tab lists every request in the collection. Click Add example next to a request and fill in the name, status code, status text, response headers and body.

Here is an example body for a 200 OK response:

{
  "id": 42,
  "name": "Asha Rao",
  "email": "asha@example.com",
  "plan": "team"
}

Add a second example to the same request with status 404 and a body like {"error": "user not found"}. Having both lets you test the "not found" path of your client later.

You can also import an existing collection. Postman collections with saved examples, HAR files (every captured response becomes an example) and OpenAPI specs with examples all give you a mock-ready collection in one step. See How to import a Postman collection.

Step 2: create the mock server

Click New in the top bar and choose New mock server. The dialog asks for:

• Collection: the collection whose examples will be served. The dialog previews the routes that will be served, with the number of examples and status codes for each, and lists requests that have no examples (and so will not be served).
• Name: defaults to "<collection> mock".
• Environment: optional. Its variables resolve {{variables}} inside examples.
• Simulated network delay: none, 300 ms, 800 ms, 2 s or a custom value.
• Private: callers must send an x-api-key header with one of your API keys.

After you create it, the mock's Overview tab shows its URL with a Copy button and a ready-made curl command.

Step 3: call it

The mock URL is the root of your API. Append the path that the request uses after its base URL:

curl -i https://swastik.codes/api/mock/<mock-id>/users/42

The path in the saved request is {{baseUrl}}/users/:id, so /users/42, /users/7 and /users/abc all match. You get the 200 example back, with the status and headers you saved.

The mock answers CORS requests from any origin, so you can call it from a frontend running on localhost:5173 without any proxy:

const res = await fetch(
  "https://swastik.codes/api/mock/<mock-id>/users/42"
);
console.log(res.status, await res.json());

Request bodies sent to a mock can be up to 1 MiB.

Choosing a response with x-mock-* headers

When a request has several examples, the scoring picks the closest one. When you want a specific response, for example to test how your app handles errors, send one of these headers:

curl -i https://swastik.codes/api/mock/<mock-id>/users/42 \
  -H "x-mock-response-code: 404"

The x-mock-* headers themselves never take part in matching.

Strict matching as a setting

Body and header matching can also be switched on for the whole mock in its Overview tab under Response matching: tick Match request body and/or Match request headers and list the header names. JSON bodies are compared structurally, so key order and whitespace do not matter. This is useful for a POST /login that should return 200 for the right credentials and 401 for anything else: save one example per case and turn on body matching.

Dynamic responses with templates

A static example gets you far, but sometimes the response should echo the request. Example bodies and header values support template helpers that read from the incoming call:

The second argument is the default when the value is missing. Strings are inserted as plain text (so put quotes around them in a JSON body), numbers and booleans as written, and objects and arrays as JSON.

For GET /users/:id, this example body returns whatever id was asked for:

{
  "id": "{{$pathSegments '1'}}",
  "name": "Asha Rao",
  "requestedAt": "{{$timestamp}}"
}

/users/42 gives "id": "42". Path segments are counted after the mock root, so segment 0 is users and segment 1 is the id.

For a POST /orders that should echo what was sent:

{
  "orderId": "{{$guid}}",
  "sku": "{{$body 'items[0].sku' 'unknown'}}",
  "quantity": {{$body 'items[0].quantity' '1'}},
  "status": "received"
}

Two kinds of substitution happen, in order. First {{variables}} are resolved from the collection variables and the mock's environment, together with dynamic variables such as {{$guid}}, {{$timestamp}} and {{$randomInt}}. Then the request helpers run. Because helpers run last, text copied from the incoming request is never itself treated as a variable.

Private mocks

By default anyone with the URL can call a mock. Tick Private to require an API key: callers send x-api-key: swc_... with a key belonging to someone who has access to the workspace. Calls without a valid key get 401 or 403. Create keys in your account settings; each key is shown once when created.

curl https://swastik.codes/api/mock/<mock-id>/users/42 \
  -H "x-api-key: $SWC_API_KEY"

The call log

The Call log tab shows the last 100 calls to the mock: method, path, query, status, which example answered, request headers, request body and how long it took. You can filter by path, method and status. Sensitive headers (Authorization, Cookie, X-Api-Key and Proxy-Authorization) are stored as [redacted].

The call log is the quickest way to debug "why did I get a 404": you can see the exact path and headers the mock received and compare them with the saved request.

The Try it tab sends calls to the mock from inside the app, which is handy when you want to check a template without leaving the browser.

Troubleshooting

404 mock_request_not_found. No request in the collection has the same method and path, or strict matching filtered every example out. Check the call log for the exact path, and check that the request has at least one example. Remember that the path is matched after the base URL: for {{baseUrl}}/v1/users, call /v1/users on the mock.

The wrong example answers. Add x-mock-response-name or x-mock-response-code, or give the examples' saved requests distinguishing query parameters or headers so scoring can tell them apart.

{{baseUrl}} appears in the response. The example uses a variable that is defined neither in the collection nor in the mock's environment. Pick an environment in the mock settings or add a collection variable.

A template prints the default. The path, field or header name does not exist in the incoming request. Header names are case-insensitive; JSON paths are case-sensitive.

Frequently asked questions

Is the mock server free?

Yes. Swastik Codes is free to use today, including mock servers.

Can I mock an API from an OpenAPI spec?

Yes. Import the spec (or design it with the API design tools) to generate a collection; operations that have examples in the spec get saved examples you can serve.

Does the mock support GraphQL or WebSocket?

The mock server answers HTTP requests from saved examples. A GraphQL query sent as an HTTP POST can be mocked like any other request, using body matching to tell queries apart. WebSocket and other streaming protocols are not mocked.

Can I use the mock from a browser app on localhost?

Yes. Mocks allow requests from any origin, so a local frontend can call the mock URL directly.

How many calls are logged?

The last 100 calls per mock, with secrets redacted.

Start mocking

Open the app, create a free account, save a couple of examples and click New mock server. The mock server feature page summarises everything above, and once the real API exists you can point the same collection at it and check it with pm.* tests.

This guide shows the full flow against a small server you can deploy yourself, explains the version differences that trip people up, and lists the errors you are most likely to see.

What you need

• A Socket.IO server reachable from the public internet. The Swastik Codes web app relays the connection through the swastik.codes server, which refuses private, loopback and other reserved addresses. A server on localhost:3000 cannot be reached from the web app, so deploy it to a staging host or put it behind a tunnel with a public hostname. The desktop app for Windows and Linux connects from your own machine, so it reaches local servers.
• To know which Socket.IO major version the server runs. Check socket.io in its package.json (or the equivalent library in Python, Java or Go).
• A free Swastik Codes account, because protocol connections run through the server.

Socket.IO versions in one paragraph

Socket.IO v3 and v4 share the same wire protocol (Socket.IO protocol 5 over Engine.IO 4), and a v4 client can talk to a v3 server. Socket.IO v2 uses the older protocol 4 over Engine.IO 3 and is not compatible with v3/v4 clients: the handshake query says EIO=3 instead of EIO=4, the namespace connection is different, and v2 has no handshake auth payload (credentials usually go in the query string). If your connection opens and then nothing happens, a version mismatch is the first thing to check. v4 servers can accept v2 clients only when they are started with allowEIO3: true.

Step 1: create a Socket.IO request

1. Open the app and sign in.
2. Click + in the tab bar and choose Socket.IO from the New request menu.
3. Enter the server URL, for example https://realtime.example.com. Use the http(s):// form of the URL; Socket.IO starts its handshake over HTTP.
4. Choose the Client version: v4, v3 or v2.

On the Settings tab you can also set:

• Handshake path: the server's path option, /socket.io by default. Change it if your server mounts Socket.IO elsewhere, for example /ws/socket.io behind a proxy.
• Namespace: / by default, or for example /admin or /chat.
• Transport: WebSocket or HTTP long-polling. With WebSocket selected, the client falls back to long-polling if the WebSocket transport fails, and the log says so.
• Auth payload (JSON, v3/v4 handshake): the object your server reads as socket.handshake.auth.
• Timeouts for the handshake and for acknowledgements, automatic reconnection, the maximum message size and TLS certificate verification.

The Params, Headers and Authorization tabs work like they do for HTTP requests. Query parameters end up in socket.handshake.query on the server, headers in socket.handshake.headers, and the authorization types (Bearer, Basic, API key, OAuth 2.0) are sent as handshake headers or query parameters.

Step 2: listen for events

Open the Events tab and add the event names you care about, such as chat:message or order:updated. Incoming events with those names are highlighted in the log. Turn on Show only listened events to hide everything else, which helps on busy servers. You can add a description to each listener to document what the event carries, and switch individual listeners on and off.

All events the server sends are still received and shown unless you filter them, so you will not miss an event just because you forgot to add a listener.

Step 3: connect

Press Connect. The log shows the connection opening, the namespace being joined and any events the server emits on connect. Connection details shows the handshake request and response headers.

If the server rejects the connection in middleware (next(new Error('unauthorized'))), you will see an error event with the message the server sent, followed by a close. That message is exactly what your real clients would receive in their connect_error handler, which makes this a quick way to test your auth middleware.

Step 4: emit events and use acknowledgements

On the Message tab, enter an Event name and the Arguments. Arguments can be written in two modes:

• JSON array: one array where each element is an argument, for example [{"room": "lobby", "text": "hello"}] for a single object argument, or ["lobby", "hello"] for two string arguments.
• One per argument: a separate editor per argument with its own format (JSON, text, number, boolean or binary). Binary arguments are sent as Socket.IO attachments.

Turn on Ack to ask the server for an acknowledgement. The client then waits for the server to call the callback and shows the ack's arguments in the log. If no ack arrives within the ack timeout, you see a timeout error; set the timeout to 0 to wait forever.

Acks also work the other way. If the server emits an event with a callback and expects the client to acknowledge it, Swastik Codes answers the acknowledgement automatically (with no arguments), so server code that waits for an ack does not hang during your test.

Press Send. The emitted event appears in the log as sent, with its namespace and ack id, followed by whatever the server sends back.

Step 5: save events and examples

Save the events you emit often so you can send them again with one click from the Saved tab while connected. Each saved message remembers its event name and arguments. When the connection is closed, Save as example stores the messages and status of the session as an example of the request. Save the request to a collection with Ctrl+S or Cmd+S to share it with your workspace.

A Socket.IO v4 server to test against

Here is a small Socket.IO v4 server with auth middleware, an event with an acknowledgement, a broadcast and a second namespace. It covers every feature discussed above.

// server.mjs  (npm install socket.io)
import { createServer } from 'node:http';
import { Server } from 'socket.io';

const httpServer = createServer();
const io = new Server(httpServer, {
  cors: { origin: '*' },
});

// Reject connections without the right token in the auth payload.
io.use((socket, next) => {
  if (socket.handshake.auth?.token !== process.env.SIO_TOKEN) {
    return next(new Error('unauthorized'));
  }
  next();
});

io.on('connection', (socket) => {
  socket.emit('welcome', { id: socket.id, at: Date.now() });

  socket.on('chat:message', (msg, ack) => {
    if (!msg || typeof msg.text !== 'string') {
      return typeof ack === 'function' && ack({ ok: false, error: 'text is required' });
    }
    io.emit('chat:message', { from: socket.id, text: msg.text });
    if (typeof ack === 'function') ack({ ok: true });
  });

  // Ask the client for an ack; Swastik Codes answers it automatically.
  socket.timeout(5000).emit('server:ping', (err) => {
    console.log(err ? 'client did not ack' : 'client acked');
  });
});

io.of('/admin').on('connection', (socket) => {
  socket.emit('stats', { clients: io.engine.clientsCount });
});

httpServer.listen(Number(process.env.PORT) || 3000);

Deploy it, set SIO_TOKEN, then in Swastik Codes:

1. URL https://your-host, Client version v4, Auth payload {"token": "{{sioToken}}"}.
2. Add listeners for welcome and chat:message.
3. Connect. You should see welcome and the server:ping event; your server logs "client acked".
4. Emit chat:message with arguments [{"text": "hello"}] and Ack on. The log shows the broadcast chat:message and the ack {"ok": true}.
5. Emit chat:message with [{}] to check the error path: the ack carries {"ok": false, "error": "text is required"}.
6. Change the namespace to /admin and reconnect to see the stats event.

Then remove the token from the auth payload and connect again to confirm that the middleware rejects you with unauthorized.

Troubleshooting

Connected, but no events and no errors. Most often a version mismatch (a v2 server with a v3/v4 client, or the other way round). Switch the Client version. Also check that you are in the right namespace.

Invalid namespace error. The namespace does not exist on the server. Namespaces are case-sensitive and start with /.

404 during the handshake. The Handshake path does not match the server's path option, or a reverse proxy does not forward /socket.io/ to the Node process.

WebSocket transport fails, polling works. A proxy is not forwarding the Upgrade header. The client falls back to long-polling so you can keep testing, but fix the proxy before production: polling uses more requests and adds latency.

Ack timeout. The server handler does not call the callback, or calls it only on some code paths. Raise the ack timeout to rule out a slow handler.

Connection refused for a private address. The relay blocks private and loopback addresses on purpose. Use a public hostname.

Frequently asked questions

Can I use a plain WebSocket client to test Socket.IO?

Only in a very limited way. You would have to write Engine.IO and Socket.IO packets by hand (40 to join the default namespace, 42["event", …] to emit). The Socket.IO request type does that for you, along with namespaces, acks and reconnection.

Which Socket.IO versions are supported?

Client versions v2, v3 and v4. Pick the one that matches your server; v4 also works with v3 servers.

How do I send a token to a Socket.IO server?

For v3 and v4 servers, put it in the Auth payload JSON, which the server reads as socket.handshake.auth. You can also send it as a query parameter or a header. v2 has no auth payload, so use the query string.

Can I send binary data?

Yes. In One per argument mode, choose the binary format for an argument and it is sent as a Socket.IO binary attachment.

Does it answer acknowledgements the server asks for?

Yes. When the server emits with a callback, the client acknowledges automatically, so server code waiting for the ack continues.

Try it

Open Swastik Codes, create a Socket.IO request and connect to your server. You need a free account to connect. The Socket.IO client feature page lists every option. If you also run raw WebSocket endpoints, read how to test a WebSocket API online, and for one-way streams see how to test Server-Sent Events.

What you need

• A WebSocket endpoint that is reachable from the public internet, for example wss://api.example.com/socket. If you only want to try the client first, wss://echo.websocket.org is a public echo server: it sends one greeting line when you connect and then returns every message you send.
• A free Swastik Codes account. The web app needs one, because traffic goes through the server (see below for why).
• Whatever credentials your API expects during the handshake: a bearer token, an API key, a cookie or a query parameter.

Why the endpoint must be public

A browser page cannot open arbitrary WebSocket connections with custom headers, and it cannot reach servers that block cross-origin requests. So the Swastik Codes web app does not connect to your endpoint directly. It opens one WebSocket to the swastik.codes server, and the server opens the real connection to your endpoint and relays frames in both directions.

That relay protects itself and everybody else: it refuses private, loopback, link-local and other reserved addresses. ws://localhost:8080 or ws://192.168.1.20 will not work from the web app. Deploy your server somewhere public (a staging environment, a small VM, a platform such as Fly.io or Render), or use a tunnelling tool that gives you a public HTTPS hostname. The desktop app for Windows and Linux runs connections from your own machine, so it reaches local servers.

Step 1: create a WebSocket request

1. Open the app and sign in.
2. Click the + button at the end of the tab bar. The New request menu lists every request type: HTTP, GraphQL, WebSocket, Socket.IO, Server-Sent Events, gRPC, MQTT and MCP. Choose WebSocket.
3. Paste your URL into the address bar, for example wss://echo.websocket.org.

If you already have an HTTP request pointing at the same host, you can change its type in place with the request type picker. The URL scheme is converted for you (https:// becomes wss://), and the name, headers, query parameters and authorization carry over.

Step 2: add headers, query parameters and auth

Most production WebSocket APIs authenticate during the opening handshake, because after that the connection is just a stream of frames. The request editor has the same tabs you know from HTTP requests:

• Params: query parameters appended to the URL, such as ?token=… or ?room=lobby.
• Authorization: Bearer token, Basic auth, API key (as a header or a query parameter) or OAuth 2.0. The choice is turned into handshake headers or query parameters. You can also inherit auth from the collection the request is saved in.
• Headers: any extra handshake headers, for example Origin, a custom X-Client-Version or a Cookie.
• Settings: subprotocols (sent as Sec-WebSocket-Protocol), ping interval, handshake request timeout, maximum message size, automatic reconnection with attempts and interval, and whether to verify the server's TLS certificate.

Values can use variables like {{baseUrl}} and {{token}} from your environments, so the same request works against staging and production.

Step 3: connect and read the handshake

Press Connect. The status changes to connecting and then to connected. The message log on the right shows the connection events as well as messages. Open Connection details to see the request headers that were sent and the response headers the server returned. This is where you check things like the negotiated subprotocol or a Set-Cookie from the upgrade response.

When a handshake fails, the log shows an error event followed by a close event, with the reason. A 401 or 403 here almost always means the token or origin was rejected; a 404 means the path is wrong; a 426 Upgrade Required or a plain 200 usually means you hit an HTTP endpoint that does not speak WebSocket at all.

Step 4: send messages

The Message tab is a composer. Pick a format first:

• Text sends a text frame exactly as typed.
• JSON, XML and HTML also send text frames, with syntax highlighting and a Beautify button.
• Binary sends a binary frame. Write the bytes as Base64 or hexadecimal and choose the encoding next to the format.

Type a message such as:

{ "type": "subscribe", "channel": "orders", "id": 1 }

and press Send. Variables in the message are resolved before it is sent, so {"token": "{{token}}"} works. The Ping button sends a WebSocket ping frame, which is useful for checking that a quiet connection is still alive.

Every sent and received frame appears in the log with its direction, time and size. You can filter by sent or received, search the log, and view a message as text, JSON or a hexdump. Select two messages to see the time between them, which is a quick way to measure how long your server takes to answer a particular request. Download the shown messages as JSON exports the visible log if you want to attach it to a bug report.

Step 5: save messages and examples

Testing a WebSocket API usually means sending the same handful of messages over and over: authenticate, subscribe, send a command, unsubscribe. Instead of keeping them in a text file:

• Click Save message in the composer to keep the current message with the request. Saved messages appear under Saved messages, where you can rename them, load one back into the composer to edit it, delete it, or send it with one click while connected.
• Use Save as example on the log once the connection is closed. It stores the messages, status and metadata of that session as an example of the request, which is handy as documentation of what a typical exchange looks like.

Save the request itself to a collection (Ctrl+S or Cmd+S) so teammates in the same workspace get the URL, headers, auth and saved messages too. Connections you open are also recorded in your history, and reopening a history entry brings you back to the WebSocket editor.

A small WebSocket server to test against

If you are building the server yourself, here is a minimal Node.js server using the ws package. It answers a ping message, echoes everything else, and broadcasts a timestamp every five seconds so you can see server-initiated messages.

// server.mjs  (npm install ws)
import { WebSocketServer } from 'ws';

const port = Number(process.env.PORT) || 8080;
const wss = new WebSocketServer({ port });

wss.on('connection', (socket, req) => {
  const token = new URL(req.url, 'http://x').searchParams.get('token');
  if (token !== process.env.WS_TOKEN) {
    socket.close(1008, 'invalid token'); // 1008 = policy violation
    return;
  }
  socket.send(JSON.stringify({ type: 'welcome' }));

  socket.on('message', (data, isBinary) => {
    if (!isBinary && data.toString() === 'ping') return socket.send('pong');
    socket.send(data, { binary: isBinary }); // echo
  });
});

setInterval(() => {
  const msg = JSON.stringify({ type: 'tick', at: new Date().toISOString() });
  for (const client of wss.clients) if (client.readyState === 1) client.send(msg);
}, 5000);

console.log(`listening on ${port}`);

Deploy it behind HTTPS, then connect to wss://your-host/?token={{wsToken}} with wsToken defined in an environment. You should see the welcome message, a tick every five seconds, and your own messages echoed back. Try a wrong token to see how a policy close (code 1008) looks in the log.

Things worth testing on any WebSocket API

A connection that works once is not the same as a robust API. A few checks catch most real-world bugs:

• Auth failures: connect with no token, an expired token and a token for another tenant. The server should refuse the handshake or close with a clear code, not accept and then ignore you.
• Malformed input: send invalid JSON, an unknown type, a huge message and an empty message. The server should answer with an error message or close politely, and the connection should not hang.
• Ordering and correlation: if your protocol uses request ids, send several commands quickly and check that each reply carries the right id.
• Idle behaviour: leave the connection open. Does the server close idle sockets, and after how long? Use the ping interval setting to keep it alive and compare.
• Reconnection: turn on automatic reconnection, then restart your server. Check what your server sends to a client that reconnects, and whether subscriptions need to be repeated.
• Binary frames: if you accept binary data, send a few bytes as hex (for example 01 02 ff) and confirm they arrive unchanged.

Troubleshooting

"Sign in to use WebSocket, gRPC, MQTT and other protocols in the browser." Sending protocol traffic from the web app needs an account, because it goes through the swastik.codes relay. Create a free account and try again.

The connection is refused immediately for a local or private address. The relay blocks private and loopback addresses on purpose. Use a public hostname.

Handshake returns 400. Check the subprotocols in Settings. If the server requires a specific subprotocol (some GraphQL and STOMP servers do), it must be listed; if it does not support the one you sent, some servers reject the upgrade.

Messages arrive, but they look like gibberish. The server is sending binary frames, often MessagePack or Protobuf. Switch the log view to hexdump to inspect the bytes.

The connection closes after about a minute of silence. Many proxies and load balancers close idle connections. Set a ping interval in Settings, and consider sending application-level heartbeats from your server.

Close code 1006. This code is never sent on the wire; it means the connection dropped without a close frame. Look at your server logs and any proxy in front of it.

Frequently asked questions

Can I test a WebSocket API without installing anything?

Yes. Swastik Codes runs in the browser. You need a free account to send traffic, but there is nothing to install.

Can I connect to ws://localhost from the web app?

No. The web app relays connections through the swastik.codes server, which refuses private and loopback addresses. Use the desktop app, deploy the server to a public host, or expose it through a tunnel with a public HTTPS hostname.

Does it support binary WebSocket messages?

Yes. Choose Binary as the message format and write the payload as Base64 or hexadecimal. Received binary frames can be viewed as a hexdump.

How do I send an auth token in a WebSocket handshake?

Use the Authorization tab (Bearer, Basic, API key or OAuth 2.0), add a header on the Headers tab, or put the token in a query parameter on the Params tab. Which one works depends on your server; browser-based clients often use a query parameter because browsers cannot set handshake headers.

Is Socket.IO the same as WebSocket?

No. Socket.IO runs its own protocol on top of WebSocket or HTTP long-polling, so a plain WebSocket client cannot talk to a Socket.IO server properly. Use the Socket.IO request type instead; see how to test a Socket.IO server.

Try it

Open Swastik Codes, create a WebSocket request and connect to your endpoint or to wss://echo.websocket.org. If you do not have an account yet, sign up for free. The WebSocket client feature page lists every option, and if your API streams in one direction only, read how to test Server-Sent Events. For HTTP endpoints that sit next to your socket server, the REST API client works the same way.

This guide covers what the client does at each step, how to call tools with arguments, how to test the parts of MCP that are hard to exercise from a chat client (elicitation, sampling, roots), and how to debug MCP's OAuth flow.

Remote MCP servers only (in the browser)

The Model Context Protocol has two kinds of transport:

• STDIO – the client starts the server as a local process and talks to it over standard input and output. This is how most desktop AI tools run local servers.
• HTTP – the server is a web service. The current transport is Streamable HTTP (a single endpoint, usually /mcp, that answers POSTs with JSON or an SSE stream). Older servers use the legacy HTTP + SSE transport, with a separate SSE endpoint.

The Swastik Codes web app supports the two HTTP transports. STDIO is not available in the browser: the web app sends traffic through the swastik.codes server, and that server never starts local processes. The transport selector shows the STDIO option disabled for that reason. The same server-side relay also refuses private and loopback addresses, so the MCP server has to be reachable from the internet. If you are building a server on your laptop, deploy it to a staging host or put it behind a tunnel with a public hostname. The desktop app for Windows and Linux connects from your own machine, so it reaches local servers and can also start STDIO servers.

Sending requests requires a free account, because they go through the server. Create one if you have not already.

For a public server to practise on, DeepWiki runs a Streamable HTTP MCP server at https://mcp.deepwiki.com/mcp that needs no key for public repositories. We use it below.

Step 1: create an MCP request and connect

1. Open the app and click + in the tab bar, then choose MCP.
2. Enter https://mcp.deepwiki.com/mcp as the URL.
3. Leave Transport on Streamable HTTP. Choose HTTP + SSE (legacy) only for servers that still use the older transport.
4. Press Connect.

With Streamable HTTP and the protocol version on auto, the client starts with the classic initialize handshake (with an Mcp-Session-Id header, a GET stream for server messages, and a DELETE when you disconnect), tries the newer stateless handshake (server/discover) only if a server refuses it, and finally falls back to the legacy HTTP + SSE transport. You do not need to know in advance which one a server speaks.

Once connected, a summary line shows:

• the server name and version from serverInfo,
• the negotiated protocol version and whether it is a stateless protocol or a session established with initialize,
• the transport, the session id when there is one,
• the capabilities the server declared (for example tools, prompts, resources),
• the server's Instructions, collapsed, when it sent any.

For DeepWiki you will see a FastMCP-based server negotiating 2025-06-18, with tools, prompts and resources capabilities.

Step 2: list and call tools

The Tools tab lists every tool from tools/list with its description. Selecting one shows its Input schema and, when the server provides one, its Output schema. Arguments are entered in a form generated from the JSON schema, with a JSON view when you prefer to type the object yourself.

Select read_wiki_structure, enter a repository in owner/repo form for repoName, and press Run tool. The result panel shows the content blocks the tool returned, and structuredContent when the tool has an output schema. A tool that fails with isError: true is shown as an error, which is different from a JSON-RPC error (an unknown tool, or invalid parameters). Testing both cases is worthwhile:

• call the tool with a valid repository and check the result shape,
• call it with a missing required argument and check that the server answers with a useful error instead of crashing,
• call it with a repository that does not exist and check the error is reported in the tool result.

A search box (Search tools, resources and prompts) filters long lists, and Refresh reloads them, which is useful when a server sends notifications/tools/list_changed.

Step 3: resources and prompts

The Resources tab lists resources/list and resource templates from resources/templates/list. Enter or pick a URI and press Read resource to see the contents. The Prompts tab lists prompts/list; fill in the prompt's arguments and press Get prompt to see the messages the server would hand to a model.

If a server does not declare a capability, the corresponding list is simply empty rather than an error.

Step 4: watch notifications

The Notifications tab collects everything the server sends on its own: progress notifications, log messages, list-changed notifications and server-to-client requests. In the Configuration tab you can set the Server log level (sent as logging/setLevel on session-based connections, or in the request metadata on the stateless protocol), so a server that supports logging streams its debug output into this tab while you call tools.

The Configuration tab is also where you set:

• Protocol version – auto, or a specific revision such as 2026-07-28, 2025-11-25, 2025-06-18, 2025-03-26 or 2024-11-05. Pinning a version is the quickest way to check backwards compatibility.
• Request timeout (ms) – for slow tools.
• Verify TLS certificates – leave it on unless you are testing a staging host with a self-signed certificate.
• Headers – extra HTTP headers sent with every MCP request, for example an organisation header or a static API key.

Step 5: elicitation, sampling and roots

These features are requests from the server to the client. They are hard to test from a chat application because the application decides how to answer. In Swastik Codes you answer them yourself:

• Elicitation (ask the user for input). Turn it on in Configuration and the client advertises the capability. When the server sends elicitation/create, the request is held and shown as Input required. You fill in the requested fields and answer, or decline. This lets you test both the happy path and what your tool does when the user refuses.
• Sampling (the user writes the model's reply). With sampling advertised, a sampling/createMessage request is shown with the messages the server wants completed. You type the reply as the assistant, set the model name reported back, and send it. You can also reject the request. This is a deterministic way to test tools that call back into a model.
• Roots. List file:// URIs (with optional names) under Roots; they are returned to the server's roots/list request. Changing them sends notifications/roots/list_changed on session-based connections.

Held server requests wait until you answer, for up to 10 minutes.

Step 6: authorization and the MCP OAuth debugger

Remote MCP servers that need a user's consent use OAuth 2.1, discovered from the server itself. When a server answers 401, the Authorization tab is marked. It contains the normal auth editor (Bearer token, API key, OAuth 2.0 and so on) and a step-by-step OAuth debugger. Press Run discovery and it performs, and reports, each step the MCP authorization specification describes:

1. Probe the server – send initialize and read the WWW-Authenticate header on the 401.
2. Protected resource metadata (RFC 9728) – find which authorization server protects this MCP server.
3. Authorization server metadata (RFC 8414) – read its endpoints, with a warning when code_challenge_methods_supported does not include S256, which MCP clients require.
4. Client registration (RFC 7591) – register a client dynamically, or skip this when you enter an OAuth client ID (and secret) yourself.

Each step shows the request outcome and the metadata it found, which makes it clear exactly where a misconfigured server breaks. When discovery succeeds, the request's OAuth 2.0 settings are filled in, and Authorize runs the authorization code flow with PKCE in a popup. The web app's callback URL is https://swastik.codes/oauth/callback; register it with your authorization server if it does not use dynamic registration. The token is then sent as a Bearer token on every MCP request. The general OAuth flow is explained in OAuth 2.0 in an API client.

A minimal server to test against

If you want a server of your own, the official Python SDK can serve Streamable HTTP in a few lines:

# server.py  –  pip install "mcp[cli]"
from mcp.server.fastmcp import FastMCP

mcp = FastMCP("demo")

@mcp.tool()
def add(a: int, b: int) -> int:
    """Add two numbers."""
    return a + b

@mcp.resource("greeting://{name}")
def greeting(name: str) -> str:
    """A personalised greeting."""
    return f"Hello, {name}!"

if __name__ == "__main__":
    mcp.run(transport="streamable-http")  # serves http://0.0.0.0:8000/mcp

Deploy it somewhere public (or expose it through a tunnel), connect to https://<your-host>/mcp, and you should see one tool (add) and one resource template (greeting://{name}). Call add with {"a": 2, "b": 3} and the result is 5. Check the SDK documentation for the version you install, as the APIs evolve.

Sharing and reusing what you tested

An MCP request can be saved into a collection like any other request, so the URL, headers, auth and configuration are kept with your other API work and shared with your team when the collection lives in a team workspace. Connections are also recorded in your history. When you are happy with a server, Export configuration produces the JSON snippet to add it to Claude Desktop, Claude Code, VS Code or Cursor.

Troubleshooting

Connection fails immediately. Check the path (/mcp is common, but not universal) and that the host is public. Private and loopback addresses are refused by the swastik.codes relay.

401 Unauthorized. Open the Authorization tab and run discovery. If step 2 fails, the server does not publish protected resource metadata; enter the authorization server details manually in the OAuth 2.0 settings.

Tools list is empty. The server did not declare the tools capability, or it requires auth before listing. Look at the capabilities in the summary line.

Works with one client, not another. Pin the protocol version in Configuration and reconnect. Differences between 2024-11-05 and later revisions (for example, JSON-RPC batching and structured tool output) are a common cause.

Frequently asked questions

Is this an alternative to the MCP Inspector?

For remote servers, it covers the same ground (listing and calling tools, resources and prompts, viewing notifications) and adds saved requests, team workspaces, history and an OAuth discovery debugger. The official MCP Inspector runs on your machine and can start STDIO servers, which the Swastik Codes web app cannot. Many developers use both.

Can I test a local STDIO MCP server?

Not from the web app. It supports Streamable HTTP and the legacy HTTP + SSE transport, and the server must be publicly reachable. The desktop app for Windows and Linux can start a local STDIO server.

Which MCP protocol versions are supported?

Auto-negotiation plus explicit versions from 2024-11-05 to 2026-07-28, including the stateless handshake of the newest revision.

Do I need an account?

The web app needs one, because connections go through the swastik.codes relay.

Try it

Open the app, add an MCP request for https://mcp.deepwiki.com/mcp, and press Connect. Sending requires a free account. The MCP client feature page lists everything the client supports. If your server also exposes a plain REST or SSE interface, the REST client and SSE client live in the same workspace.

The browser's own EventSource is a poor testing tool: it only does GET, it cannot set custom headers such as Authorization, and it hides the raw stream. This guide covers what a proper SSE client shows you, how to test resumption and reconnection, and how to test POST-based streams like the ones large language model APIs use.

What you need

• An SSE endpoint reachable from the public internet. The Swastik Codes web app relays the connection through the swastik.codes server, which refuses private, loopback and other reserved addresses, so http://localhost:3000/events cannot be reached from the web app. The desktop app for Windows and Linux connects from your own machine, so it reaches local endpoints.
• A free Swastik Codes account, because streaming connections run through the server.

If you want to try the client first, Wikimedia's public EventStreams service is a real SSE endpoint: https://stream.wikimedia.org/v2/stream/recentchange streams every edit on Wikimedia projects as it happens. It is a busy stream, so expect many events per second, and disconnect when you are done.

How the SSE format works

An SSE response has the content type text/event-stream and is a sequence of events separated by blank lines. Each event is made of fields:

event: order.updated
id: 1042
data: {"orderId": "A-17", "status": "shipped"}

: this line is a comment, often used as a heartbeat

retry: 5000
data: a message without an event type is a "message" event
data: and multiple data lines are joined with newlines

• data: is the payload. Several data: lines in one event are joined with \n.
• event: is the event type. Without it, the type is message.
• id: sets the last event id. A client that reconnects sends it back in the Last-Event-ID request header so the server can resume.
• retry: tells the client how many milliseconds to wait before reconnecting.
• Lines starting with : are comments and are ignored.

Swastik Codes parses the stream incrementally following the WHATWG event stream rules, including events that arrive split across network packets and UTF-8 characters split in the middle.

Step 1: create an SSE request

1. Open the app and sign in.
2. Click + in the tab bar and choose Server-Sent Events from the New request menu.
3. Paste the URL, for example https://stream.wikimedia.org/v2/stream/recentchange.
4. Leave the method on GET and press Connect.

The client sends Accept: text/event-stream and Cache-Control: no-cache for you. If the server answers with a different content type, the log shows a note and the body is parsed as an event stream anyway, which helps when a misconfigured proxy rewrites the header.

Each event in the log shows its type, data, id and arrival time. Use View as to switch between automatic detection, text and JSON, search the log, and select two events to see the time between them. Connection details shows the request and response headers, which is where you check for proxy problems such as a missing Content-Type or an unexpected Content-Encoding.

Step 2: headers, auth and parameters

Most private SSE endpoints authenticate with a header. The Authorization tab supports Bearer, Basic, API key and OAuth 2.0, or inheriting auth from the collection. Headers takes any other header, and Params edits the query string. Use variables like {{baseUrl}} and {{token}} so the same request works across environments.

Step 3: filter event types

Busy streams mix many event types. Type the types you care about into the event filter, comma separated (for example order.updated, order.cancelled), and only those are shown. The filter only affects the display; the connection still receives everything.

Step 4: test resumption with Last-Event-ID

Resumption is the feature that makes SSE more than a long HTTP response, and it is the part most often broken in server implementations. To test it:

1. Connect and let a few events with ids arrive.
2. The id of the most recent event is shown above the log with a Use button. Click it to copy that id into the Last-Event-ID setting.
3. Disconnect, wait a moment, and connect again.

The client now sends Last-Event-ID: <id> with the request. A correct server sends the events after that id and nothing before it. Check for gaps and duplicates at the boundary. You can also type any id into Last-Event-ID by hand, for example an old id to test what the server does when the id is too old to replay.

Step 5: test reconnection and retry

In Settings, turn on Reconnect when the stream ends (honours retry:). When the server closes the stream, the client waits and reconnects with the last id it saw, just like EventSource does. The wait starts at the Reconnect delay (ms) and switches to the server's retry: value once one arrives. Reconnection attempts limits the number of tries (0 means unlimited). The log shows each reconnect with the delay and the Last-Event-ID that was sent.

Other settings: Connection timeout (ms) for the initial response, Maximum event size (MB) (larger events are discarded and reported, so a stream that never sends a newline cannot grow without bound), and server certificate verification.

Step 6: POST streams and LLM-style APIs

Many APIs stream with SSE in response to a POST request with a JSON body. Chat completion endpoints of large language model providers are the best-known example: you POST a prompt with "stream": true and receive tokens as data: events, often ending with a sentinel such as data: [DONE]. EventSource cannot do this at all.

In Swastik Codes, pick POST (or PUT, PATCH, DELETE) in the method dropdown next to the URL, then open the Body tab and write the JSON body:

{
  "model": "{{model}}",
  "stream": true,
  "messages": [{ "role": "user", "content": "Explain Server-Sent Events in one sentence." }]
}

Add the provider's auth header (usually a bearer token or an API key header) and a Content-Type: application/json header, then press Connect. Each chunk arrives as an event, so you can see exactly how the stream is split, how long the first token takes, and how the stream ends. Keep API keys in an environment variable rather than in the request, especially in shared workspaces.

A small SSE server to test against

This Node.js server uses only the standard library. GET /events sends numbered events with ids, honours Last-Event-ID and sends a heartbeat comment. POST /stream streams back the words of the text field from the JSON body, then a done event.

// server.mjs  (Node.js 18+, no dependencies)
import { createServer } from 'node:http';

const headers = {
  'Content-Type': 'text/event-stream',
  'Cache-Control': 'no-cache',
  'X-Accel-Buffering': 'no', // stop nginx from buffering the stream
};

createServer(async (req, res) => {
  if (req.method === 'GET' && req.url.startsWith('/events')) {
    res.writeHead(200, headers);
    let id = Number(req.headers['last-event-id']) || 0;
    res.write('retry: 3000\n\n');
    const tick = setInterval(() => {
      id += 1;
      const type = id % 5 === 0 ? 'order.cancelled' : 'order.updated';
      res.write(`event: ${type}\nid: ${id}\ndata: ${JSON.stringify({ seq: id, at: new Date().toISOString() })}\n\n`);
    }, 1000);
    const heartbeat = setInterval(() => res.write(': ping\n\n'), 15000);
    req.on('close', () => { clearInterval(tick); clearInterval(heartbeat); });
    return;
  }

  if (req.method === 'POST' && req.url === '/stream') {
    let raw = '';
    for await (const chunk of req) raw += chunk;
    const { text = 'hello from the stream' } = JSON.parse(raw || '{}');
    res.writeHead(200, headers);
    for (const word of String(text).split(/\s+/)) {
      res.write(`data: ${JSON.stringify({ token: word })}\n\n`);
      await new Promise((r) => setTimeout(r, 200));
    }
    res.write('event: done\ndata: [DONE]\n\n');
    return res.end();
  }

  res.writeHead(404).end();
}).listen(Number(process.env.PORT) || 3000);

Deploy it and try:

1. GET https://your-host/events: events arrive every second, every fifth one an order.cancelled. Filter on order.cancelled.
2. Click Use next to the last id, disconnect, wait five seconds and reconnect. The sequence continues from that id.
3. Turn on reconnection and restart the server: the client waits retry milliseconds and resumes.
4. POST https://your-host/stream with body {"text": "one two three four"}: four data events and a done event.

Troubleshooting

Nothing arrives for a long time, then everything at once. A proxy is buffering the response. For nginx, set proxy_buffering off; for the location or send X-Accel-Buffering: no from the app. Compression middleware can also buffer: exclude text/event-stream from it.

The connection drops after 30 or 60 seconds. An idle timeout on a load balancer or proxy. Send a comment line (: ping) every 15 to 30 seconds.

Events show up with the type message when you expected a name. The server is not sending an event: field, or it is sending it after data: in a different event block. Each event ends at a blank line.

JSON data is cut in half. The server wrote a raw newline inside the data. Each line of the payload needs its own data: prefix, or serialise the JSON on one line.

Connection refused for a private address. The relay blocks private and loopback addresses on purpose. Use a public hostname.

Frequently asked questions

What is the difference between SSE and WebSocket?

SSE is one-way, server to client, over plain HTTP, with built-in resumption through event ids. WebSocket is a two-way channel with its own framing. If clients only need to receive updates, SSE is simpler to run behind ordinary HTTP infrastructure. See how to test a WebSocket API for the other side.

Can I send custom headers to an SSE endpoint?

Yes. Unlike the browser's EventSource, Swastik Codes can send any headers, including Authorization, and supports Bearer, Basic, API key and OAuth 2.0 auth.

Can I test SSE streams that use POST?

Yes. Choose POST, PUT, PATCH or DELETE next to the URL and write the request body on the Body tab. This covers streaming LLM APIs and other POST-based streams.

How do I test Last-Event-ID resumption?

Connect, click Use next to the last id shown above the log, disconnect and reconnect. The client sends that id in the Last-Event-ID header. You can also type an id into the setting by hand.

Does MCP use SSE?

Some MCP servers use SSE as a transport, either the older HTTP+SSE transport or streamed responses in the Streamable HTTP transport. For those, use the dedicated MCP request type described in how to test an MCP server, which handles the MCP handshake for you.

Try it

Open Swastik Codes, create a Server-Sent Events request and connect to your endpoint, or to Wikimedia's public stream to see one in action. You need a free account to connect. The SSE client feature page lists every option, and the REST API client covers the non-streaming endpoints of the same API.

This guide covers what carries over, what to check after the move, how to set up a team, and where the two tools differ. It is written for people who already know Postman well and want a realistic picture before they switch, or before they run both side by side.

The short version

1. Export your collections, environments and globals from Postman as JSON (or export a full data dump).
2. Open Swastik Codes, click Import and drop the files in. The format is detected for you.
3. Create a free account so the web app can send requests, then pick an environment and run a request.
4. Run the collection in the collection runner and compare the test results with what you see in Postman.
5. Invite your team to a team workspace with admin, editor or viewer roles.

The step-by-step import itself, including screenshots of each option, is in How to import a Postman collection. The rest of this article is about everything around it.

What carries over

Swastik Codes was built against public, documented formats, so a collection keeps its structure rather than being flattened or approximated.

A few things in a data dump are not imported: header presets, mocks and monitors. When the dump contains any of these, the import preview lists a note such as "mocks in the data dump are not imported". You recreate mocks and monitors in Swastik Codes from the imported collection, which usually takes a minute each.

Scripts and tests

Scripts run in an isolated JavaScript sandbox with time and memory limits. Swastik Codes calls its script API swc; Postman's pm is the same object, so scripts written for Postman run as they are. The API covers the parts real collections use:

• variables: swc.variables, swc.environment, swc.globals, swc.collectionVariables, swc.iterationData, including replaceIn;
• swc.request, swc.response, swc.cookies and swc.info;
• swc.test (and swc.test.skip) with swc.expect and the chai-style swc.response.to.have.status(...), .header(...), .jsonBody(...) and .jsonSchema(...) assertions;
• swc.sendRequest with a callback or as a promise;
• swc.execution.setNextRequest and swc.execution.skipRequest for flow control in runs;
• swc.visualizer.set for custom response views.

Commonly required libraries are available through require, including chai, lodash, moment, crypto-js, uuid, ajv, tv4, xml2js, cheerio and csv-parse/lib/sync, plus Node-style modules such as buffer, url, querystring and util. Older scripts that use the legacy postman.setEnvironmentVariable, tests["..."] = ... and responseBody globals also run.

A typical Postman test script needs no changes:

pm.test("status is 200", () => {
  pm.response.to.have.status(200);
});

pm.test("returns a user with an id", () => {
  const body = pm.response.json();
  pm.expect(body).to.have.property("id");
  pm.environment.set("userId", body.id);
});

pm.* or swc.*

Both names work, so converting is optional. To keep one name across a workspace:

• When importing, leave Convert Postman scripts to swc.* ticked (it is shown when the selected collections contain pm.* scripts). Every collection, folder and request script is rewritten from pm. to swc..
• Later, use Convert pm.* scripts to swc.* in a collection's menu, or Convert to swc.* in the bar shown above a script that uses pm.*.
• When exporting to Postman (v2.1 or v3), scripts are written back with pm., so the collection keeps running in Postman.

The converter reads the JavaScript instead of searching for text: strings, regular expressions, npm, obj.pm and object keys named pm are left alone, and a script that already declares its own swc variable is not touched.

If you want to write new tests, Writing API tests with swc.* scripts walks through the patterns in detail.

Authorization

All the usual auth types are supported: API key, Bearer token, Basic, Digest, JWT, OAuth 1.0, OAuth 2.0 (authorization code with or without PKCE, implicit, password, client credentials and refresh), Hawk, AWS Signature v4, NTLM, Akamai EdgeGrid and ASAP. Auth set on a collection or folder is inherited the same way. For OAuth 2.0 flows in the browser, see OAuth 2.0 in an API client.

What to check after you move

Imports are faithful, but every team has a few habits that are worth a quick look.

1. Variable values that were only "current"

Postman environments distinguish between initial and current values, and an export may or may not include the current ones depending on how it was made. In Swastik Codes, current values of variables are local to your device: they are stripped before anything is stored on the server. That is good for secrets, but it means a token you only ever kept as a current value will not appear for your teammates. Set the initial value for anything the team needs, and keep personal secrets as current values or in the vault.

2. Secrets that should not be shared

Before you put a collection in a team or public workspace, run the secret scanner. It looks for API keys, tokens, passwords and private keys stored as plain text in collections, environments and globals, and it tells you which findings would be exposed through a public workspace or published documentation.

3. Requests to localhost or a private network

This is the most important difference for a web-based client. A browser cannot send arbitrary cross-origin requests, so the Swastik Codes web app sends your requests through the swastik.codes server. That server refuses private, loopback, link-local and reserved addresses. Requests to http://localhost:3000, 192.168.x.x or an internal hostname that resolves to a private IP will fail with an error, even if they work in a desktop client.

For local development, point the request at a publicly reachable staging or preview deployment instead. Or install the desktop app for Windows or Linux, which sends requests from your own machine and reaches localhost and private networks.

4. Scripts that depend on unusual libraries or timing

Scripts that use the common libraries listed above work as written. If a script loads code from a URL with eval, depends on very long setTimeout chains, or relies on a module that is not in the list, check it after the import. The console panel shows script errors with the line that failed.

5. Runner settings

Iterations, delays, data files and "persist variables" exist in the collection runner, and setNextRequest works the way it does in Newman. Re-run your main collection once and compare the pass and fail counts with your last Postman run. Differences usually point at a variable that was never set, which is easy to fix.

Setting up your team

Signing up creates a personal cloud workspace called "My Workspace" that syncs across your devices. For a team:

1. Open the teams dialog and create a team. You become its admin.
2. Invite people by email. Each invite has a role: admin manages the team and its workspaces, editor changes content, viewer reads and runs. Invite links expire after seven days.
3. Create a team workspace and import the shared collections there.

Team workspaces get the collaboration features: comments on requests and collections with @ mentions, version history with restore, forks and pull requests with reviews and merge checks, and an activity feed. Changes from teammates appear live. The collaboration page covers these in more depth.

You can also keep a workspace on your device only. Local workspaces are stored in the browser, are not synced, and are handy for experiments.

What is different

It would not be fair to suggest the two tools are identical, so here is an honest list.

• Where requests come from. In the web app, requests are sent by the swastik.codes server rather than your machine. That removes CORS limits, but it means private and loopback targets are refused, and the target server sees our IP address rather than yours. Postman's desktop app sends from your machine.
• Desktop apps. Swastik Codes runs in the browser, and as a desktop app for Windows and Linux that sends requests from your machine. A macOS version is coming.
• Ecosystem. Postman has a large public network of shared collections, integrations and a long history. Swastik Codes focuses on the client, testing and team workflow.
• Pricing. Swastik Codes is free to use today, with no paid plans. Check Postman's own site for its current plans.
• Protocols. Besides HTTP, Swastik Codes includes GraphQL, WebSocket, Socket.IO, Server-Sent Events, gRPC, MQTT and MCP clients in the same app.

If you depend on a Postman-specific integration or on reaching private hosts directly, keep Postman for those collections and try Swastik Codes for the rest. Nothing stops you from running both: you can export back to Postman Collection v2.1 at any time. A detailed side-by-side is on the Swastik Codes vs Postman page.

A suggested migration plan for a team

1. Pick one collection that the team uses every day and has tests.
2. Import it into a team workspace together with its environments.
3. Run it in the collection runner and fix any differences (usually variables).
4. Recreate mocks and monitors for that collection if you used them.
5. Use it for a week. Leave the Postman copy untouched as a fallback.
6. Move the rest once the team is comfortable, using a data dump if you have many collections.

Frequently asked questions

Will my Postman tests run without changes?

In most cases, yes. The sandbox implements the documented pm.* API, chai-style assertions and the commonly used libraries. Tests that call private network hosts, or depend on modules outside the supported list, need adjusting.

Can I import everything at once?

Yes. Export a data dump from Postman and import it. Collections, environments and globals come across in one go. Header presets, mocks and monitors in the dump are not imported and are listed as notes.

Why can't I reach my localhost API?

The web app sends requests through the swastik.codes server, which refuses private and loopback addresses for security. Use a publicly reachable staging URL, or the desktop app for Windows and Linux, which sends from your machine.

Can I go back to Postman later?

Yes. Export any collection as Postman Collection v2.1 (or v2.0, or v3) and environments in Postman format, then import them into Postman.

Is Swastik Codes free?

Yes, it is free to use today and there are no paid plans.

Try it with your own collection

The fastest way to judge any Postman alternative is with a real collection. Create a free account, open the app and import one. The import and export feature page lists every supported format, and the collection runner is where you check that your tests still pass.

This guide walks through that flow using the public Eclipse Mosquitto test broker, test.mosquitto.org, and then covers what to check on your own broker.

What you need

• A broker reachable from the public internet. The Swastik Codes web app does not connect from your browser tab directly: browsers cannot open raw TCP sockets, so the swastik.codes server opens the MQTT connection on your behalf and relays packets to your tab. That relay refuses private, loopback and other reserved addresses, so a broker on localhost or 10.0.0.5 cannot be reached from the web app. The Swastik Codes desktop app for Windows and Linux connects from your own machine, so it reaches local brokers.
• The broker's credentials, if it needs them: username and password, a client certificate, or MQTT 5 enhanced authentication.
• A free Swastik Codes account, because protocol connections run through the server.

For a first try, test.mosquitto.org accepts anonymous connections on port 1883 (plain MQTT over TCP) and port 8080 (MQTT over unencrypted WebSocket). It is a shared public test broker: anyone can read what you publish, so never send real data there, and use a unique topic prefix such as swc-demo/<your-name>/ so you do not collide with other people.

Step 1: create an MQTT request and connect

1. Open the app and sign in.
2. Click + in the tab bar and choose MQTT from the New request menu.
3. Enter the broker URL. The scheme picks the transport:
   • mqtt://host:1883 or tcp://host:1883 for plain MQTT over TCP,
   • mqtts://host:8883 (also ssl:// or tls://) for MQTT over TLS,
   • ws://host:port/path or wss://host:port/path for MQTT over WebSocket, with the mqtt subprotocol.
4. Choose the version next to the URL: MQTT 3.1.1 or MQTT 5.0.
5. Press Connect.

For the demo, enter mqtt://test.mosquitto.org:1883, or ws://test.mosquitto.org:8080 to try the WebSocket transport.

The Settings tab holds the connection options: Client ID (leave it empty for a random id per connection, or generate one), Keep-alive (s), Clean session (called Clean start in MQTT 5), Connection timeout (ms), automatic reconnection with a number of attempts and a delay, and TLS options: Use TLS (mqtts / wss), Verify the broker certificate, Server name (SNI), and PEM fields for a CA certificate, client certificate and client key for mutual TLS. Username and password live on the Authorization tab.

Step 2: subscribe to topics

Open the Topics tab, type a topic filter and click Subscribe. MQTT filters use two wildcards:

• + matches exactly one level: sensors/+/temp matches sensors/kitchen/temp but not sensors/kitchen/1/temp.
• # matches any number of levels and must come last: swc-demo/alice/# matches everything under that prefix.

Pick the QoS for each subscription. The broker delivers each message at the lower of the publisher's QoS and the subscription's QoS. Each subscription has a switch to unsubscribe and subscribe again without deleting it, and you can add a description to remember what a topic is for.

With MQTT 5, each subscription also has subscription options:

• No local: do not receive messages you published yourself.
• Retain as published: keep the retain flag as the publisher set it instead of clearing it.
• Retained messages: Send on subscribe, Only for new subscriptions or Never send, which control whether the broker replays retained messages when you subscribe.
• Subscription id: a number the broker attaches to every message delivered through this subscription.

Incoming messages appear in the log with their topic, QoS, retain flag and payload, and you can filter the log by topic.

Step 3: publish messages

On the Message tab, enter a topic, choose the QoS (QoS 0, QoS 1 or QoS 2), set Retain if you want the broker to keep the message for future subscribers, choose a payload format and write the payload. Formats are Text, JSON, XML, Hex and Base64; Hex and Base64 let you publish binary payloads such as Protobuf or CBOR. Press Publish.

Try this with the demo broker: subscribe to swc-demo/alice/#, then publish to swc-demo/alice/kitchen/temp:

{ "celsius": 21.5, "at": "{{$isoTimestamp}}" }

You should see your own message come back through the subscription. Variables and dynamic values are resolved before publishing.

What the QoS levels mean

• QoS 0, at most once: fire and forget. Fine for frequent telemetry where a lost reading does not matter.
• QoS 1, at least once: the receiver acknowledges with PUBACK and the sender retries until it does. Duplicates are possible, so consumers should be idempotent.
• QoS 2, exactly once: a four-step handshake (PUBLISH, PUBREC, PUBREL, PUBCOMP). Slower, but no duplicates between two hops.

Swastik Codes performs the full handshake for each level in both directions, so you can see how your broker and consumers behave with each.

Retained messages

A retained message is the last known value of a topic. When you publish with Retain on, the broker stores the message and sends it to every new subscriber immediately. To clear a retained message, publish an empty payload with retain on to the same topic. This is a common source of confusion: a dashboard shows stale data because somebody once published a retained message to the topic.

Step 4: last will and MQTT 5 properties

The Last will tab configures the message the broker publishes on your behalf if the client disconnects without a proper DISCONNECT, for example on a network failure. Turn on Send a last-will message and set a topic, payload, QoS and retain flag. A common pattern is a retained status topic: the device publishes online after connecting, and the will publishes offline. In MQTT 5 the will can also have a Delay interval (s) and message properties.

With MQTT 5.0 selected, the Properties tab adds CONNECT properties: Session expiry (s), Receive maximum, Maximum packet size (bytes), Topic alias maximum, Request response information, Request problem information, user properties, and Authentication method and Authentication data for enhanced auth. Individual publishes get message properties under MQTT 5 properties: Content type, Response topic, Correlation data, Message expiry (s), Topic alias, Payload format indicator (UTF-8) and user properties.

Response topic and correlation data are how request/response works over MQTT 5. Publish a command with Response topic: swc-demo/alice/replies and some correlation data, subscribe to swc-demo/alice/replies, and check that your service answers with the same correlation data.

Step 5: save messages

Click Save next to Publish to keep the current message, including its topic, QoS, retain flag and format, with the request. Saved messages are listed on the Saved tab and can be published again with one click while connected. Save the request to a collection with Ctrl+S or Cmd+S and everyone in the workspace gets the broker URL, subscriptions, will and saved messages.

Run your own broker

For a private test broker, Eclipse Mosquitto is a small and well-documented choice. A minimal mosquitto.conf with password authentication and both TCP and WebSocket listeners:

# mosquitto.conf
listener 1883
protocol mqtt

listener 8083
protocol websockets

allow_anonymous false
password_file /mosquitto/config/passwd

Create the password file and start it with Docker:

docker run --rm -v "$PWD:/mosquitto/config" eclipse-mosquitto \
  mosquitto_passwd -c -b /mosquitto/config/passwd tester 's3cret'

docker run -d --name mosquitto -p 1883:1883 -p 8083:8083 \
  -v "$PWD:/mosquitto/config" eclipse-mosquitto

Put TLS in front of it (a listener 8883 with certfile and keyfile, or a TLS-terminating proxy for the WebSocket listener) before exposing it on the internet. To see traffic flowing, run a small simulated device with the mqtt package for Node.js:

// device.mjs  (npm install mqtt)
import mqtt from 'mqtt';

const client = mqtt.connect('mqtts://broker.example.com:8883', {
  username: 'tester',
  password: process.env.MQTT_PASSWORD,
  protocolVersion: 5,
  will: { topic: 'devices/sensor-1/status', payload: 'offline', qos: 1, retain: true },
});

client.on('connect', () => {
  client.publish('devices/sensor-1/status', 'online', { qos: 1, retain: true });
  client.subscribe('devices/sensor-1/commands', { qos: 1 });
  setInterval(() => {
    const reading = { celsius: 20 + Math.random() * 5, at: new Date().toISOString() };
    client.publish('devices/sensor-1/telemetry', JSON.stringify(reading), { qos: 0 });
  }, 5000);
});

client.on('message', (topic, payload) => {
  console.log('command on', topic, payload.toString());
});

Now connect from Swastik Codes, subscribe to devices/#, and publish to devices/sensor-1/commands. Stop the device process abruptly and watch the broker publish the offline will.

Troubleshooting

CONNACK says "not authorized" or "bad user name or password". Check the Authorization tab. On MQTT 5 the reason code in the log tells you exactly which check failed.

The connection is refused for a private address. The relay blocks private and loopback addresses. Use a broker with a public hostname.

TLS errors on mqtts://. Make sure the port really serves TLS (8883 by convention), set Server name (SNI) if you connect by IP, and add the CA certificate if the broker uses a private CA.

WebSocket connection fails. Most brokers serve MQTT over WebSocket on a specific path, often /mqtt. Include it in the URL.

I get disconnected right after connecting. Two clients with the same client id kick each other off. Leave Client ID empty for a random one.

Old messages arrive the moment I subscribe. They are retained messages. Clear them by publishing an empty retained payload, or set Retained messages to Never send on an MQTT 5 subscription.

Frequently asked questions

Which MQTT versions are supported?

MQTT 3.1.1 and MQTT 5.0. MQTT 5 adds reason codes, properties, subscription options, session expiry and enhanced authentication, and all of those are available in the editor.

Can I connect over WebSocket?

Yes. Use a ws:// or wss:// URL and the client speaks MQTT over WebSocket with the mqtt subprotocol. Plain TCP (mqtt://) and TLS (mqtts://) work as well.

Can I publish binary payloads?

Yes. Choose Hex or Base64 as the payload format and the bytes are decoded before publishing.

Can I test a broker on my local network?

Not from the web app, because the relay refuses private and loopback addresses. Use the desktop app, which connects from your own computer, or expose a test broker on a public hostname, protected by a password and TLS.

Is test.mosquitto.org safe to use?

It is fine for learning and quick checks, but it is public: anything you publish can be read by anyone. Use a unique topic prefix and never send credentials or personal data.

Try it

Open Swastik Codes, create an MQTT request, connect to mqtt://test.mosquitto.org:1883 and subscribe to your own topic prefix. You will need a free account to connect. The MQTT client feature page lists every option. If your system also pushes data to browsers, see how to test Server-Sent Events and how to test a WebSocket API.

This guide explains each grant type, what to register with your provider, how to share a token across a whole collection, and how to fix the errors you are most likely to meet.

Before you start

• Register a client with your provider (Auth0, Okta, Keycloak, Azure AD / Entra ID, Google, or your own server). You will get a client ID and, for confidential clients, a client secret.
• Register the callback URL. For the Swastik Codes web app it is:

https://swastik.codes/oauth/callback

The authorization code, PKCE and implicit grants redirect the popup there. Providers compare redirect URIs exactly, so copy it character for character.

• Have a free account. Token requests and API calls are sent through the swastik.codes server, which needs you signed in. The server also refuses private and loopback addresses, so the provider's token endpoint must be publicly reachable. An identity server on localhost will not work from the web app; use the desktop app for that.

Step 1: choose where the auth lives

Authorization can be set on a request, a folder or a collection. Requests default to Inherit, which uses the nearest folder or collection auth; the Authorization tab tells you which one is in effect ("This request uses OAuth 2.0 from …").

For an API where every endpoint needs the same token, configure OAuth 2.0 once on the collection (open the collection and select its Authorization tab) and leave the requests on Inherit. Override it on a folder or request only where an endpoint needs something different, such as No Auth for a public health check.

Step 2: configure the grant

Open the Authorization tab, choose OAuth 2.0 and fill in the Configure new token section. The fields depend on the Grant type.

Authorization Code (With PKCE) – for most user-facing APIs

This is the grant to use when a user signs in at the provider and approves access. PKCE protects the code exchange and is required by OAuth 2.1 and by many providers for public clients.

Press Get New Access Token. A popup opens at the provider; sign in and approve. The provider redirects the popup to the callback URL with a code, the app checks the state, and the code is exchanged for tokens. Allow popups for swastik.codes if your browser blocks it.

For Google the URLs are https://accounts.google.com/o/oauth2/v2/auth and https://oauth2.googleapis.com/token; for other providers, look for their OpenID Connect discovery document (/.well-known/openid-configuration), which lists authorization_endpoint and token_endpoint.

Authorization Code (without PKCE)

The same flow for confidential clients that do not use PKCE. Prefer the PKCE variant when the provider supports it.

Client Credentials – for service-to-service APIs

No user and no popup: the client authenticates as itself. Fill in Access Token URL, Client ID, Client Secret and Scope, then press Get New Access Token. This is the usual grant for machine APIs and for running a collection on a schedule in a monitor.

Password Credentials – legacy only

The client sends a username and password directly to the token endpoint. OAuth 2.1 removes this grant and many providers disable it, but older internal APIs still use it. Fill in Username and Password in addition to the token URL and client details.

Implicit – legacy only

The token is returned directly in the redirect, without a code exchange. It is also removed in OAuth 2.1. It is supported for older providers; for anything new, use the authorization code grant with PKCE.

Client authentication and extra parameters

Client Authentication decides how the client ID and secret reach the token endpoint: Send as Basic Auth header (the default) or Send client credentials in body. If the provider answers invalid_client although the secret is right, try the other option.

Under the advanced fields you can set Audience and Resource (Auth0 and resource-indicator providers need these), a separate Refresh Token URL, and two tables of extra parameters: Extra authorization request parameters (for example prompt=consent or access_type=offline for Google, to get a refresh token) and Extra token request parameters, where each row can be sent in the request body, a header or the URL.

Step 3: use the token

When the token arrives it is shown in a dialog; press Use Token. The Current token section then holds the access token and controls how it is sent:

• Header Prefix – Bearer by default.
• Add token to – Request Headers (Authorization: Bearer …) or Request URL for APIs that expect it as a query parameter.
• Use Token Type – when the provider also returned an OpenID Connect ID token, choose whether to send the access token or the ID token.

Send any request in the collection and it carries the token. To check, open the console: it shows the request headers that were actually sent.

Keep tokens out of shared documents

Fields accept variables, so the client secret can be {{clientSecret}} with the value stored in an environment. Variable current values stay on your device and are not synced, so a secret kept as a current value is not shared with your team. The vault keeps encrypted secrets that resolve only for hosts you allow. See environments and variables.

Step 4: refresh and manage tokens

Access tokens expire. If the provider returned a refresh token:

• Auto-refresh token (on by default) swaps an expired token for a fresh one through the refresh grant just before a request is sent.
• Refresh token in the Current token section refreshes on demand.

Manage opens the list of saved tokens. Each token has a name (from Token Name), its expiry and its refresh token, and you can use, refresh or delete it, or clear all expired ones. Expired tokens are marked in the token selector.

Getting a token in a script instead

Sometimes a token comes from a non-standard login endpoint. A pre-request script with swc.sendRequest can fetch it and store it:

// Collection pre-request script
const expiresAt = swc.environment.get('tokenExpiresAt');
if (!expiresAt || Date.now() > Number(expiresAt)) {
  swc.sendRequest({
    url: swc.environment.get('loginUrl'),
    method: 'POST',
    header: [{ key: 'Content-Type', value: 'application/json' }],
    body: { mode: 'raw', raw: JSON.stringify({
      username: swc.environment.get('user'),
      password: swc.environment.get('password')
    }) }
  }, function (err, res) {
    if (err) { console.log('login failed', err); return; }
    const body = res.json();
    swc.environment.set('token', body.access_token);
    swc.environment.set('tokenExpiresAt', Date.now() + (body.expires_in - 30) * 1000);
  });
}

Then set the collection's auth to Bearer Token with the value {{token}}. More script patterns are in writing API tests with swc.* scripts.

Other schemes in the same tab

OAuth 2.0 is one of several authorization types. The same tab handles API Key, Bearer Token, JWT (signed for you), Basic, Digest, OAuth 1.0, Hawk, AWS Signature v4, NTLM, Akamai EdgeGrid and ASAP. See the authorization feature page for the full list.

Troubleshooting

redirect_uri_mismatch or "invalid redirect". The callback URL registered with the provider must equal https://swastik.codes/oauth/callback exactly, including the scheme and with no trailing slash.

"Popup blocked". Allow popups for swastik.codes and press Get New Access Token again.

"OAuth state mismatch". An old popup answered after a newer attempt started. Close stray popups and retry.

invalid_client. Wrong secret, or the provider expects the credentials in the other place: switch Client Authentication between the Basic Auth header and the body.

invalid_grant on refresh. The refresh token was revoked or rotated. Get a new token with the original grant.

The token request never reaches the provider. If the token URL is on a private network or localhost, the swastik.codes server refuses it. Use a publicly reachable identity server.

Requests still return 401. Check the scopes and audience the API expects, and decode the token (the JWT payload is base64) to see what it actually contains.

Frequently asked questions

What callback URL should I register for Swastik Codes?

https://swastik.codes/oauth/callback for the web app.

Is PKCE supported?

Yes. Choose Authorization Code (With PKCE). The code verifier is generated automatically when the field is empty, and the challenge method can be SHA-256 (recommended) or plain.

Can one token be shared by every request in a collection?

Yes. Configure OAuth 2.0 on the collection or a folder and leave the requests on Inherit.

Can I test an MCP server that uses OAuth?

Yes. MCP requests include a discovery debugger that walks through protected resource metadata, authorization server metadata and dynamic client registration before getting a token. See testing an MCP server.

Are my client secrets synced?

Values you keep as a variable's current value stay on your device. Values you type directly into a saved request's auth fields are part of that request and are stored with the collection, so prefer variables or the vault for secrets.

Try it

Open the app, set OAuth 2.0 on a collection and get your first token; token requests need a free account. The authorization feature page lists every supported scheme, and environments and variables explains how to keep credentials per environment. If you are moving from another client, importing a Postman collection keeps its auth settings.

Swastik Codes runs these scripts in a sandboxed JavaScript engine that implements Postman's documented pm.* API, so most scripts written for Postman work unchanged. The examples use swc.*, Swastik Codes' name for the same API: swc and pm are one object, so every swc. below can also be written pm., and imported pm.* scripts can be converted to swc.* in one click. This guide is a set of working examples you can paste into the app, from the basic status check to chained requests and runner control.

Where scripts live

Open a request in the app and select the Scripts tab. It has two editors:

• Pre-request – runs before the request is sent.
• Post-response – runs after the response arrives. This is where tests go.

Collections and folders have a Scripts tab too. When a request is sent, the pre-request scripts run in order collection → folder(s) → request, then the request is sent, then the post-response scripts run in the same order. Put shared logic (an auth header, a common status check) at the collection level and request-specific checks on the request.

The editor offers snippets for common tasks, such as Status code is 200, JSON value check, Validate JSON schema and Save a token from the response, so you rarely start from an empty file.

Results appear in the response panel's Test Results tab, with a passed/total count, and console.log output goes to the console panel.

Sending requires a free account, because the web app sends them through the swastik.codes server; that server also refuses private and loopback addresses, so the API must be publicly reachable. The examples below use https://jsonplaceholder.typicode.com and https://httpbin.org, which you can call right away.

The basics: status, time, headers

Create a GET request to https://jsonplaceholder.typicode.com/users/1 and add this post-response script:

swc.test('status is 200', function () {
  swc.response.to.have.status(200);
});

swc.test('responds within 1500 ms', function () {
  swc.expect(swc.response.responseTime).to.be.below(1500);
});

swc.test('returns JSON', function () {
  swc.response.to.have.header('Content-Type');
  swc.expect(swc.response.headers.get('Content-Type')).to.include('application/json');
});

Other status helpers read well in tests: swc.response.to.be.ok (exactly 200), swc.response.to.be.success (any 2XX), swc.response.to.be.clientError, swc.response.to.be.notFound, swc.response.to.be.unauthorized and swc.response.to.be.rateLimited.

Asserting on the JSON body

swc.response.json() parses the body. From there it is ordinary chai:

const user = swc.response.json();

swc.test('user has the expected identity', function () {
  swc.expect(user.id).to.eql(1);
  swc.expect(user.email).to.match(/@/);
  swc.expect(user).to.have.property('address');
  swc.expect(user.address.geo).to.have.all.keys('lat', 'lng');
});

swc.test('company name is a non-empty string', function () {
  swc.expect(user.company.name).to.be.a('string').and.not.empty;
});

For quick checks without parsing, jsonBody takes a lodash-style path:

swc.test('city is present', function () {
  swc.response.to.have.jsonBody('address.city');
});

swc.test('username is Bret', function () {
  swc.response.to.have.jsonBody('username', 'Bret');
});

And swc.response.to.have.body(/Leanne/) checks the raw text against a regular expression.

Validating against a JSON Schema

Checking individual fields catches the fields you thought of. A schema catches the rest: wrong types, missing required fields, unexpected nulls. jsonSchema validates with Ajv:

const userSchema = {
  type: 'object',
  required: ['id', 'name', 'email', 'address'],
  properties: {
    id: { type: 'integer', minimum: 1 },
    name: { type: 'string' },
    email: { type: 'string' },
    address: {
      type: 'object',
      required: ['city', 'zipcode'],
      properties: {
        city: { type: 'string' },
        zipcode: { type: 'string' }
      }
    }
  }
};

swc.test('matches the user schema', function () {
  swc.response.to.have.jsonSchema(userSchema);
});

If a test fails, the message lists every schema error, because Ajv runs with allErrors. Older scripts that use tv4.validate(data, schema) also work: tv4 is one of the bundled libraries.

Variables and scopes

Variables are written as {{name}} in URLs, headers and bodies, and read or written in scripts:

swc.variables.get('name') resolves through all scopes, with the narrowest winning (local, then data, environment, collection, global). swc.variables.replaceIn('{{baseUrl}}/users') expands a string the same way.

A common pattern is saving a value from one response for the next request:

// Post-response script of POST /posts
const created = swc.response.json();

swc.test('post was created', function () {
  swc.response.to.have.status(201);
  swc.expect(created.id).to.be.a('number');
});

swc.collectionVariables.set('postId', created.id);

The next request can then call GET https://jsonplaceholder.typicode.com/posts/{{postId}}. (JSONPlaceholder fakes writes, so that id will not really exist there, but the pattern is the same on a real API.)

Pre-request scripts

Pre-request scripts prepare the request. They can change it directly through swc.request:

// Pre-request: add a timestamp and a request id
swc.variables.set('now', new Date().toISOString());
swc.request.headers.upsert({ key: 'X-Request-Id', value: require('uuid').v4() });

Signing a request with an HMAC is a typical job for crypto-js:

const CryptoJS = require('crypto-js');
const secret = swc.environment.get('signingSecret');
const body = swc.request.body ? swc.request.body.raw || '' : '';
const ts = Math.floor(Date.now() / 1000).toString();
const signature = CryptoJS.HmacSHA256(ts + '.' + body, secret).toString(CryptoJS.enc.Hex);

swc.request.headers.upsert({ key: 'X-Timestamp', value: ts });
swc.request.headers.upsert({ key: 'X-Signature', value: 'sha256=' + signature });

If a pre-request script throws, the request is not sent and the error is shown, which is how the desktop Postman app behaves. In a collection run the request is still sent, as Newman does.

Calling another endpoint from a script

swc.sendRequest sends an extra request from inside a script. It accepts a URL string or a request object, and works with a callback or as a promise:

// Pre-request: fetch a token if we do not have one yet
if (!swc.environment.get('token')) {
  swc.sendRequest({
    url: 'https://httpbin.org/post',
    method: 'POST',
    header: [{ key: 'Content-Type', value: 'application/json' }],
    body: { mode: 'raw', raw: JSON.stringify({ token: 'demo-token' }) }
  }, function (err, res) {
    if (err) { console.log(err); return; }
    swc.environment.set('token', res.json().json.token);
  });
}

httpbin echoes the JSON you post under json, so this saves demo-token. Against a real identity provider you would post credentials and read access_token. For OAuth 2.0 it is usually simpler to use the built-in OAuth 2.0 authorization type instead; see OAuth 2.0 in an API client.

Requests made with swc.sendRequest appear in the console as swc.sendRequest entries, so you can see exactly what the script sent and received.

Controlling a collection run

When requests run in the collection runner (or in a monitor), scripts can change the order:

// Post-response: stop polling once the job is done
const job = swc.response.json();
if (job.status === 'done') {
  swc.execution.setNextRequest('Download result');
} else {
  swc.execution.setNextRequest('Check job status'); // run this request again
}

swc.execution.setNextRequest(null) ends the current iteration. swc.execution.skipRequest(), called from a pre-request script, skips the send:

// Pre-request: only run on staging
if (swc.environment.get('env') !== 'staging') {
  swc.execution.skipRequest();
}

Skipped requests are counted separately in the run results. The legacy postman.setNextRequest('name') spelling also works.

Bundled libraries

require() gives access to these libraries without installing anything: chai, lodash, moment, crypto-js, uuid, ajv, tv4, xml2js, cheerio, csv-parse/lib/sync, handlebars, and Node-style modules such as buffer, url, querystring, util, events, path, assert and crypto. atob and btoa are available too.

Parsing XML, for example:

const xml2js = require('xml2js');
xml2js.parseString(swc.response.text(), function (err, result) {
  swc.test('XML parses', function () {
    swc.expect(err).to.be.null;
  });
});

Visualizing a response

swc.visualizer.set(template, data) renders a Handlebars template in the response's Visualize view, which is handy for turning a JSON list into a readable table:

const template = `
<table>
  <tr><th>Name</th><th>Email</th></tr>
  {{#each users}}
  <tr><td>{{name}}</td><td>{{email}}</td></tr>
  {{/each}}
</table>`;

// GET https://jsonplaceholder.typicode.com/users
swc.visualizer.set(template, { users: swc.response.json() });

Older script styles

Collections that have been around for a while often contain legacy syntax. It still runs:

tests['Status code is 200'] = responseCode.code === 200;
tests['Body mentions Leanne'] = responseBody.has('Leanne');
postman.setEnvironmentVariable('lastStatus', responseCode.code);

Converting to swc.test is worth it when you next touch the script, because named tests with assertion messages are much easier to debug.

Troubleshooting

swc.response.json() throws. The body is not JSON: check the status (an HTML error page is common) and the Content-Type. Test the status first, so the failure says what really happened.

A variable is empty. Check which scope you set and which you read. swc.environment.set does nothing useful without an active environment; use swc.collectionVariables when the value belongs to the collection.

Tests pass locally but fail in a run. In the runner, variable changes always carry to the next request within an iteration, but they carry into the next iteration only when Persist variables between requests is on; the order follows the collection unless scripts call setNextRequest.

A module is not found. Only the bundled libraries listed above can be required.

Frequently asked questions

Are Postman test scripts compatible?

Scripts that use Postman's documented pm.* API (tests, expectations, variables, sendRequest, cookies, visualizer, execution control) and the legacy tests[]/postman.* globals are supported. Compatibility is built against the public documentation.

Can tests run on a schedule?

Yes. Collections with tests can run on a cron schedule as monitors, with email or webhook alerts when they fail.

Can I run the same tests with different data?

Yes. Attach a CSV or JSON file in the collection runner and read the current row with swc.iterationData. See data-driven API testing.

Do async tests work?

Yes. A test function can return a promise, or take a done callback, and its result is recorded when it settles.

Try it

Open the app, paste the first example into a request's Post-response script and send it with a free account. The API testing feature page summarises the scripting support. When you have a few requests with tests, run them as a collection with a data file, or import your existing Postman collection and keep the scripts you already have.