How to use Carom

#Your first request

Ten seconds from launch to a response.

1. Press CtrlN for a new request — or use the + in the tab strip.
2. Choose the method, type the URL. {{baseUrl}}/pokemon/pikachu works once you have defined baseUrl (see Variables).
3. Press CtrlEnter — or Enter while you are in the URL field — to send.
4. The response appears on the right: status, time, size, and the body formatted.

#Workspaces, folders and tabs

A workspace holds folders, requests and environments. Switch between them with CtrlR or from the menu at the top of the sidebar.

• Folders group requests, can be nested, and can carry their own variables, authentication and scripts that apply to everything inside.
• Drag and drop to reorder or move a request into a folder. Dragging is switched off while a filter is active, so nothing lands in the wrong place.
• Filter the tree with the box above it, or jump straight to a request with CtrlP.
• Right-click a tab to locate it in the tree, close it, close the others or close all. CtrlW closes the active tab; CtrlShiftE searches the open ones.
• CtrlB hides and shows the sidebar.

#Building a request

Each request has a set of tabs under the URL bar:

Set authentication once on a folder and every request inside inherits it; a request can still choose its own.

#Variables and environments

Write {{name}} anywhere — URL, headers, body, auth — and Carom fills it in when you send.

Where a value comes from

1. The folder the request is in. With nested folders, the innermost one wins.
2. The active environment, chosen in the picker at the top right.
3. The base environment, shared by all the others.

Hover a variable to see its value and which of the three supplied it. A variable that is not defined anywhere is shown in red.

Defining and changing them

• Hover a variable, in the URL or inside a body, and edit it right there — or define it if it does not exist yet.
• Select any text, right-click, and choose Set an existing variable or New variable…. The value goes into whichever environment is selected, and your selection is replaced with the reference.
• CtrlE opens the environments drawer, a quick editor beside your request that shows the active environment and the folder’s variables. Manage environments, in the picker, opens the full dialog to add, rename, colour, copy between and delete environments.

#Generated data

Variables that are made up when the request is sent. Handy for fixtures, forms and load of realistic-looking data.

Write one between braces — {{$randomEmail}} — and it becomes a fresh value on every send. Each occurrence gets its own value, so two {{$randomFullName}} in one body are two different people. That is what sets a generator apart from a variable.

• The names match Postman’s, so a collection that used them keeps working.
• Names, cities, streets and phone numbers follow the language of the interface. Identifiers, numbers and dates have no language and never change.
• To fix the language independently — an API that validates addresses in English, read by someone working in Portuguese — set Generated data in Settings → General.
• A variable you define with the same name wins over the generator.
• A misspelt generator stays red, which is the case worth noticing.

Nothing matches that.

#Scripts

JavaScript that runs before a request is sent or after its response arrives.

Put a script on a request or on a folder. A folder’s scripts wrap every request inside it: pre-request scripts run from the outermost folder inward, post-response scripts from the innermost outward.

// Post-response script: keep the token for the next request
const body = carom.json();
if (body && body.token) carom.set("token", body.token);

Postman’s pm object works too, including pm.test, so scripts from an imported collection run unchanged.

#Reading a response

• Pretty collapses and expands JSON; Raw is exactly what came back; Preview renders HTML.
• Highlight in body finds text and marks every match.
• Headers, Cookies and Console (script output and pm.test results) have their own tabs.
• History keeps the last 15 responses of each request. Click one to look at it again.
• Copy the response, or save it to a file, with the buttons above the body.
• When a response arrives for a request in another tab, a toast tells you.

To hand a request to someone as a command, use Copy as curl beside the URL bar. It is written with your variables already filled in — and with generated values, if the body has any. Copy URL gives you the resolved URL.

#Importing and exporting

Import

Use Import at the bottom of the sidebar. Carom reads Carom exports, Postman collections and environments, Insomnia v4 and v5, OpenAPI / Swagger, HAR files and pasted curl commands. For Postman you choose what to bring in and where it goes, environments included. Anything that does not come across — an Insomnia gRPC request, say — is listed before you confirm.

Export

Use Export for a workspace, a folder (with its subfolders and requests) or a single request, in Carom’s format or as OpenAPI 3.1. Choose the slice — environments included — and where to save it.

#Sharing a workspace with a team

Desktop app only.

From the workspace menu choose Keep this workspace in a folder and pick a folder in your project. An empty folder takes the workspace as it is; a folder that already holds one replaces the workspace with what is in it.

• One request per file: two people adding different requests change different files, and git merges them without asking.
• Folders, requests and environments go in the folder. Responses, unsaved edits and saved versions stay on your machine.
• Variable names always travel. Values travel only where you say so — the next screen asks, and anything that looks like a credential starts switched off.
• Changes are written a moment after you stop typing, and only the files that differ.
• If the folder changes under you — after git pull with the app open — Carom stops writing and says so. Reload from disk and carry on.

#Keyboard shortcuts

The defaults. Every one can be changed under Settings → General → Keyboard shortcuts.

In the code editors

#Themes, colours and language

• Settings → General: the interface language (English, Português, Español — it follows your system until you choose), the language of generated data, pane layout, timeout, redirects, whether the desktop app asks servers for compressed responses, and Keyboard shortcuts.
• Settings → Theme: dark or light, five built-in palettes (Carom, Midnight, Ember, Forest, Paper), and fonts with their size. Change any colour of a built-in palette and it becomes your own copy; Surprise me shuffles a new one.
• On the desktop, Settings → General → Updates checks for a new version, and lets you choose whether Carom checks by itself when it starts.

#When something is off

Found something else? Open an issue and say what you did, what you expected and what happened.