Impulse Documentation
How to build, send, and share API requests with Impulse — including what is and is not built yet.
Introduction
Impulse is an open-source API client that runs in the browser. You build a request, send it, and read the response — then save it into a collection your whole team can use. It covers REST endpoints and WebSocket connections.
No desktop install
Runs in a browser tab. Nothing to download, nothing to keep updated.
Self-hostable
Run it yourself with Docker and PostgreSQL. Your requests and responses stay in a database you control.
Getting Started
Sign in with GitHub or Google, and a personal workspace is created for you automatically. From there, head to /workspace to start sending requests.
Keyboard shortcuts
Ctrl/⌘ + GCtrl/⌘ + SCtrl/⌘ + KWorkspaces
A workspace is the top-level container. It holds collections and a list of members, so you can keep separate projects — and separate teams — apart.
- Personal WorkspaceCreated for you on first sign-in. Private to your account.
- Shared WorkspacesInvite teammates by link. Everyone sees the same collections and requests, and changes appear on their next load.
Roles
Every member holds one role, and it is enforced on the server for each operation — not just hidden in the UI.
ADMINEverything an Editor can do, plus issuing invite linksEDITORCreate, edit, and delete collections and requestsVIEWERRead collections and send requests, but not modify themCollections
A collection is a named group of saved requests inside a workspace. Create one from the sidebar, then save requests into it. Each saved request keeps its method, URL, query parameters, headers, and body.
Folders
Collections nest. Use New Folder on a collection's menu to group requests by resource or API version, as deeply as you need.
Import and export
Paste or upload a Postman v2.1 export and Impulse recreates the requests with their methods, URLs, query parameters, headers, and bodies — and recreates the folder structure as real nested collections. Export goes the other way, either as Postman v2.1 or as a native format that round-trips without losing body types and auth schemes.
Running a whole collection
Run collection executes every request in a collection and its folders in order, showing status, duration, and assertion results per request. Requests run one after another, not in parallel, because collections routinely depend on each other's side effects.
Not yet supported
Collection-level shared headers and pre-request scripts are not implemented. Variables live on environments rather than on collections.
Sending Requests
Pick a method, type a URL, press Send. You do not need to save a request first — an unsaved tab sends fine.
Methods
GET, POST, PUT, PATCH, and DELETE. A body is sent for everything except GET.
Headers and query parameters
Add them as key/value rows and toggle individual rows off without deleting them. Disabled rows are left out of the request.
Authorization
Bearer token, Basic auth, or an API key sent as a header or a query parameter — instead of hand-writing an Authorization header. A header you set yourself on the Headers tab always wins over the scheme.
Body editor
JSON, text, XML, GraphQL, form-data, or url-encoded. Text-shaped bodies use Monaco — the editor behind VS Code — with syntax highlighting for the chosen type, folding, and invalid-JSON detection; form-data and url-encoded use a key/value grid instead. If you do not set a Content-Type yourself and the body parses as JSON, Impulse sets application/json for you.
Reading the response
Status code, elapsed time, and size, with tabs for a pretty-printed body, the raw body, and the response headers. You can copy the body or download it to a file. Each tab remembers its own last response.
Paste a cURL command
Paste any curl command into the URL bar and the whole request is filled in — method, URL, headers, query params, body, and basic auth.
Export as code
The </> button renders the current request as cURL, fetch, axios, Python requests, or Go. Snippets are generated after variables and auth are resolved, so they reproduce exactly what Send puts on the wire.
Tests
Assert on status, response time, size, headers, raw body, or a JSON field addressed by path such as data.items[0].id. Assertions are declarative — no JavaScript is executed — and results are saved with each run.
History
Every send against a saved request is recorded with its status, duration, size, which execution path was used, and assertion results. Selecting a past run replays it into the response pane.
Not yet supported
File uploads, header autocomplete, and a cookie jar. Form-data carries text fields only — a file cannot be serialized to the server proxy, so offering it in browser mode alone would be worse than not offering it.
Environments
An environment is a named set of variables belonging to a workspace. Write {{name}} anywhere in a request — the URL, a header, a query parameter, an auth field, or the body — and it is replaced with that environment's value when the request is sent.
- Switch environments from the picker in the header to point the same collection at local, staging, or production
- Mark a variable secret to mask it in the UI. It is still sent in requests — this is display masking, not encryption
- Which environment is active is per person, so teammates can work against different ones at the same time
A variable with no value in the active environment is left in the request literally rather than blanked, and the app warns which names went unresolved — sending https:///users silently would be far harder to debug.
Execution Modes
Where a request is sent from decides what it can reach. Impulse gives you both options, chosen with the Send via selector under the URL bar.
Browser
The request leaves from your own machine, so it can reach localhost, private networks, and anything on your VPN. The catch is CORS: a browser will not let a page read a response from another origin unless that API opts in, and most do not. Your cookies are never attached.
Proxy
The server sends the request for you, so CORS does not apply and you see every response header. It cannot reach your machine's localhost, and for safety it refuses private and internal addresses, has a 30 second timeout, and caps responses at 10 MB.
Autodefault
Tries the browser first and falls back to the proxy only when the request never completed. A real answer from the API — including a 404 or a 500 — is always shown as-is, never retried down the other path.
WebSockets
The realtime surface connects to a WebSocket URL and shows a live table of every frame sent and received, with timestamps and direction.
- Connection status with automatic reconnection and attempt tracking
- A Monaco editor for composing JSON payloads, with a format button
- A scrolling log of sent and received frames, clearable at any time
WebSocket connections open from your browser, so they reach local and private servers. Sessions are not saved to the database yet — the log is cleared when you leave the page.
AI Assistance
Impulse uses Google's Gemini models for two specific jobs. Both require you to be signed in and are rate limited per account.
Name a request
From the method and URL, it proposes a few readable names with a short reason for each — so a saved request reads as "Create Charge" rather than "POST /v1/charges".
Generate a JSON body
Describe the payload you want in plain English and it drafts the JSON, with a short explanation and suggestions for fields you might add.
If you are self-hosting, these features need a GOOGLE_GENERATIVE_AI_API_KEY in your environment. Without one, the rest of the app works normally.
Collaboration
Share a workspace by generating an invite link. Anyone who opens it and signs in joins as a Viewer, and an Admin can change their role afterwards.
How invites work
- • Only workspace Admins can generate a link
- • Each link expires after 7 days
- • A link is consumed once it is accepted
- • Opening a link you have already used does nothing, and never changes a role you already hold
A note on “realtime”
Collections and requests are shared, so teammates work from the same data. There is no live presence, shared cursors, or push-based syncing yet — changes show up when the other person loads or refetches.
Still have questions?
If you didn't find what you were looking for, please open an issue on GitHub.