How to use Swastik Codes: the complete guide

This guide walks through the whole product. Each section explains what a part of Swastik Codes is for, how to use it, and where to read more. If you prefer short lessons with screenshots, the Learn section covers the same ground one task at a time.

Where Swastik Codes runs

Swastik Codes is one API platform you can use in five places. Your collections, environments and tests are the same in all of them.

Swastik Codes is free to use, including teams, and there are no paid plans.

Create your account and workspace

1. Open swastik.codes/signup and sign up with GitHub or an email address. GitHub sign-in reads only your profile and verified email, never your repositories.
2. Verify your email if you signed up with one. A verified address is needed to create API keys and send team invitations.
3. Open the app. You start in a personal workspace.

Workspaces hold collections, environments, specs, mocks, monitors and flows. They are personal (only you), team (everyone in a team, by role) or public (readable by any signed-in user, useful for sample collections). Switch between them from the workspace menu at the top left.

Turn on two-factor sign-in under Account settings → Security with any authenticator app. API keys for the CLI, the VS Code extension and the public API are under Account settings → API keys.

Send your first request

Click New and choose HTTP. Then:

1. Pick a method (GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS, or type a custom one) and type the URL. Write path variables as :id and they appear as rows to fill in.
2. Params: query parameters stay in sync with the URL. Untick a row to leave it out without deleting it.
3. Authorization: choose a scheme, or leave it on inherit to use the folder's or collection's.
4. Headers: add the headers your API expects.
5. Body: none, form-data (text and file fields), x-www-form-urlencoded, raw (JSON, XML, HTML, JavaScript or text), binary (a file as the whole body) or GraphQL.
6. Click Send.

The response shows the status, total time, size and a timing breakdown (DNS lookup, TCP connect, TLS handshake, time to first byte, download). View the body pretty-printed, raw or as a preview, and search it; headers and cookies have their own tabs.

Paste a cURL command into the URL box and it becomes a request, with method, headers and body filled in. Going the other way, Code turns any request into a snippet in one of 30 targets: cURL, JavaScript, Python, Go, Java, C#, PHP, Ruby, Swift, Kotlin, Rust and more.

Every request you send goes to History (the newest 500 per workspace), and the Console shows exactly what went out, with script logs and errors.

Read more: REST API client, first request lesson.

Organise requests in collections

A collection is a set of requests in folders, with its own variables, auth, scripts and documentation. Save a request with Save and choose a collection and folder, or create one from the sidebar.

• Folders group requests and can nest inside each other.
• Auth and scripts at every level: set auth or scripts on the collection or a folder, and every request inside inherits them unless it sets its own.
• Examples: save a response as an example (Save as example) to document what the API returns. Examples also feed mock servers and documentation.
• Collection tabs: open a collection to see its overview, variables, auth, scripts, roles, packages, catalog entry and test coverage.

Copy, fork or move a collection to another workspace from its ⋯ menu. Deleted collections go to the trash first.

Environments, variables and secrets

Write {{baseUrl}}/orders once and switch between local, staging and production with the environment selector.

Scopes, from most specific to least: local (set by a script for one request), data (the current row of a data file in a run), the active environment, collection variables and globals. Variables work in URLs, params, headers, bodies, auth fields and protocol settings. They are highlighted, autocompleted, and marked in red when nothing defines them.

Initial and current values. The initial value is shared with your team; the current value stays on your device and is stripped before anything is saved to the server. Put your personal token in the current value.

Dynamic values such as {{$guid}}, {{$timestamp}}, {{$randomInt}}, {{$randomEmail}} and {{$isoTimestamp}} are generated fresh on every send.

Secrets. The vault keeps secrets encrypted on your device with a passphrase; reference them as {{vault:name}} and limit each to the domains it may be sent to. The secret scanner finds keys, tokens and passwords in collections, environments and globals, and warns when you save one as plain text.

Run as a different user. On a collection's Roles tab, define roles (admin, user, guest) with their own variables, then pick one with Run as next to the environment selector to send the same requests as that user.

Read more: environments and variables, authorization.

Write tests

Every request, folder and collection has a pre-request script (runs before sending) and a test script (runs after the response). Scripts are JavaScript with the swc.* API. Postman's pm.* is the same object, so existing Postman scripts run unchanged.

swc.test("status is 201", () => {
  swc.response.to.have.status(201);
});

swc.test("returns an id", () => {
  const body = swc.response.json();
  swc.expect(body).to.have.property("id");
  swc.environment.set("orderId", body.id);   // use it in the next request
});

swc.test("is fast enough", () => {
  swc.expect(swc.response.responseTime).to.be.below(800);
});

• Assertions are chai-style, with helpers for status, headers, cookies, JSON bodies and JSON Schema (to.have.jsonSchema).
• Chaining: set variables from one response and use them in the next; swc.sendRequest makes an extra call from a script, for example to fetch a token.
• Libraries: require() gives you chai, lodash, moment, crypto-js, uuid, ajv, xml2js, cheerio and more.
• Packages: shared helpers your team reuses live on a collection's Packages tab and load with swc.require.
• Contract tests can be generated from your API definition.

Test results appear in the response panel's Test Results tab. Read more: API testing, first tests lesson.

Run whole collections

Click Run on a collection or folder to open the collection runner.

1. Choose what runs (the whole collection, a folder or one request) and reorder it for this run if you like.
2. Pick an environment, a number of iterations, and optionally a CSV or JSON data file: each row becomes {{column}} variables and swc.iterationData.
3. Set a delay between requests and a bail rule (stop on the first failed test, the first error, either, or never).
4. Start the run. You see each request's status, time and tests live, then a summary.

Export results as JSON, JUnit XML or an HTML report. Scripts can change the order with swc.execution.setNextRequest("Name") or skip a request with swc.execution.skipRequest().

The runner also has labs for deeper checks:

• Compare environments: sends the same requests to two environments and lists every difference, field by field.
• Find flaky tests: repeats requests and marks each stable, flaky or failing, with the reason.
• Security checks: looks for open CORS, missing security headers, unsafe cookies and endpoints that answer without credentials.
• Invalid input: sends variations of your bodies to see what the API accepts.
• Coverage: which requests have no tests and which documented responses are never checked.

Run in CI writes a pipeline file for GitHub Actions, GitLab CI, Jenkins, Azure Pipelines, CircleCI or a shell script, using the swc CLI. Read more: collection runner, run a collection, CI lesson.

Beyond REST: every protocol

Click New and pick the protocol.

• GraphQL: introspect a schema or load SDL, explore types, write queries with autocomplete, and run subscriptions over WebSocket. GraphQL client.
• gRPC: load services from .proto files or server reflection, make unary and streaming calls with metadata and deadlines. gRPC client.
• WebSocket: connect with headers and auth, send text or binary frames, save messages and search a timestamped log. WebSocket client.
• Socket.IO: v2, v3 and v4; emit events with arguments, wait for acks and listen to the events you choose. Socket.IO client.
• Server-Sent Events: subscribe with headers and auth, filter event types and resume from Last-Event-ID. SSE client.
• MQTT: MQTT 3.1.1 and 5 over mqtt://, mqtts://, ws:// or wss://, with QoS, retain, last will and MQTT 5 properties. MQTT client.
• MCP: connect to remote Model Context Protocol servers, list and call tools, read resources and prompts, and debug OAuth. The desktop app also runs local STDIO servers. MCP client.

Protocol sessions save into collections like HTTP requests, with their own scripts and tests where the protocol allows.

Design your API with OpenAPI

Open APIs in the sidebar to create or import a definition: OpenAPI 3, Swagger 2 or AsyncAPI, including multi-file definitions.

• Linting points at the line that breaks a rule.
• Generate a collection from the definition, then keep it in sync as the definition changes.
• Contract tests check that real responses match the definition.
• Versions tag releases and show a changelog between them, so breaking changes are visible before they ship.

Read more: API design, breaking changes lesson.

Mock an API before it exists

A mock server answers with the examples saved in a collection, at a public URL such as https://swastik.codes/api/mock/<mock-id>/v1/orders/42.

1. Save examples on the requests (status, headers, body).
2. Create a mock server for the collection, optionally with an environment and a delay.
3. Point your front end or tests at the mock URL.

Calls are matched on query, headers and body. Clients can pick a response with headers such as x-mock-response-code: 404 or x-mock-response-name, and example bodies can echo the request with templates like {{$pathSegments '2'}}. Mark a mock private to require an API key. swc mock collection.json --port 4010 runs the same mock on your computer. Read more: mock servers, mock servers lesson.

Load test and monitor

Load testing runs saved requests with virtual users and a fixed, ramp-up, spike or peak profile, and shows throughput, errors and latency percentiles live, with pass or fail thresholds. Load testing.

Monitors run a collection on a schedule, from every minute to weekly, with retries, timeouts and an environment. Alerts go by email (up to 20 addresses), to a signed webhook, or to Slack, Microsoft Teams or Discord, on failure, on every run or on recovery. Each monitor keeps its newest 200 runs, and the Reliability report shows pass rates and the requests that fail most. API monitoring.

Publish documentation

From a collection's Share menu, choose Publish documentation. The public page lists every request with its description, parameters, examples and code samples, with search, custom Markdown pages and a Run in Swastik Codes button. Credentials are masked, you choose which environment readers see, and you can download it as one offline HTML file. API documentation.

To have your own server show documentation instead, like FastAPI's /docs:

pip install swastik-codes          # FastAPI, Flask, Django
npm install @swastik-codes/docs    # Express, NestJS, Fastify, Hono, Koa

Then add mount(app) in FastAPI or app.use(swastikCodes({ spec })) in Express, and open /swc/docs and /swc/collection. A swastik-codes.json file changes the title, introduction, servers, sections and request names without code changes. Read more: Docs for your server, the FastAPI guide, the Express, NestJS and Fastify guide and the comparison with Swagger UI.

Automate with flows

A flow chains saved requests on a canvas with conditions, loops, delays and expressions, passing data from one step to the next. Run it by hand, inspect every step, or trigger it from a webhook. Flows.

Work as a team

1. Create a team and invite people by email (invitations last seven days).
2. Give each member a role: Admin (manages the team), Editor (changes collections, environments, specs, mocks, monitors and flows) or Viewer (reads and comments).
3. Create a team workspace, or move a personal one into the team.

Then work together:

• Live presence shows who is looking at the same request.
• Comments on collections, folders and requests, with @mentions and resolvable threads.
• Version history: every save records a version you can compare and restore.
• Forks and pull requests: fork a collection, change it, open a pull request; reviewers approve or request changes, and merging is a three-way merge with conflicts listed.
• Share one collection with a person or a team without giving them the whole workspace, as viewer or editor.
• Webhooks for events such as collection.updated or monitor.run.failed, and an audit log for admins.

Read more: collaboration, sharing lesson.

Import, export and GitHub

Import (the button at the top) takes Postman collections (v2.0, v2.1 and v3), environments, globals and data dumps, Insomnia exports, OpenAPI 3, Swagger 2, cURL, HAR, RAML, WSDL and GraphQL schemas, from a file, a link, pasted text or a GitHub repository. A compatibility report shows what will carry over before you import. Export writes Postman v2.1, v2.0 or v3, or OpenAPI 3. Import and export.

GitHub sync builds a collection from the API routes in your code: connect GitHub, pick a repository and a branch, and every push updates the collection while keeping the names, examples and tests you added. It reads Express, NestJS, Fastify, FastAPI, Flask, Django, Spring, Laravel, Rails, Go frameworks and more. GitHub sync.

Share and discover APIs on the marketplace

The marketplace lists public APIs published by people and organisations. Star an API to keep it, or Fork it into your workspace and start sending requests at once. To publish, register an organisation or create a personal profile, then choose Publish to marketplace on a collection; organisations can verify their domain for a badge. Publish lesson, fork lesson.

The desktop app

Download the app for Windows (installer), macOS (one .dmg for Apple silicon and Intel) or Linux (.deb, .rpm or AppImage). It is the same app as the web version, but every request runs in a native engine on your computer, so it reaches localhost, Docker containers, your LAN and VPN-only hosts with no CORS limits. It works without an account; sign in to sync the same workspaces as the web app.

The swc command line

Install it with one command, then run it in any project:

curl -fsSL https://swastik.codes/install.sh | sh     # macOS and Linux
irm https://swastik.codes/install.ps1 | iex          # Windows PowerShell
npm install -g @swastik-codes/cli                    # any platform with Node.js

Run swc --help for every command and option. Read more: CLI.

The VS Code extension

In VS Code, open the Extensions view, search for Swastik Codes and click Install (or run code --install-extension swastik-codes.swastik-codes). Sign in with an API key, then:

• open requests from the Collections view, send with Ctrl+Enter and save with Ctrl+S;
• choose Run as Tests on a collection to see every request and assertion in the Test Explorer;
• use Scan and Link Project to turn your routes into a collection, then Sync now or Sync on save;
• keep tokens in the system keychain with Set a value on this computer only.

Read more: VS Code extension.

Security and privacy

• Current values of variables stay on your device; secrets can live in the encrypted vault.
• The web app's server refuses private, loopback and link-local addresses, so it can't be used to reach other people's internal networks.
• Two-factor sign-in, API keys only for verified accounts, and an audit log for team admins.
• Export your data at any time, and delete your account under Account settings → Security → Delete account.

See the security page and privacy policy for the details.

Frequently asked questions

Do I need to install anything?

No. The web app runs in a modern browser. Install the desktop app, the CLI or the VS Code extension only when you want them.

Can I use my Postman collections and scripts?

Yes. Import them from Import; scripts written against pm.* run unchanged, and can be renamed to swc.* on import.

How do I call an API on localhost from the web app?

Run swc bridge on your computer and switch on Local bridge in the app's status bar. Requests then run on your machine. The desktop app reaches localhost without the bridge.

How do I run my tests in CI?

Click Run in CI next to the runner's Run button to get a pipeline file for your CI system, or call swc run yourself with an API key stored as a CI secret.

Where do I get help?

Start with the lessons and the FAQ, or write to us on the contact page.