Orbittest Client User Guide

A friendly, step-by-step guide to using Orbittest Client. No prior experience with API tools needed — if you can fill in a web form, you can use this.

New here?

If you haven’t installed the app yet, start with Install Orbittest Client, then come back.

What Orbittest Client is (in plain words)

An API is how one program talks to another over the internet. When an app loads your profile, it quietly asks a server: “give me user 42’s details.” That request and the server’s reply are what Orbittest Client lets you send and inspect by hand.

Orbittest Client is a desktop app for sending those requests and reading the replies — useful when you’re building or testing software and want to check that a server behaves the way you expect. Think of it as a control panel for talking to servers.

Everything stays on your computer. There’s no account, no login, no cloud. Your work is saved to a single file in your Documents folder.

A few words you’ll see a lot:

Word	Means
Request	A message you send to a server (e.g. “get user 42”).
Response	The server’s reply (the data + a status code).
Method	The kind of action: GET (read), POST (create), PUT/PATCH (update), DELETE (remove).
URL	The address you’re sending to, like https://api.example.com/users/42.
Header	Extra info attached to a request (e.g. what format you want back).
Body	The data you send with a request, usually when creating or updating something.
Status code	A number in the reply: 200 = OK, 404 = not found, 500 = server error.
JSON	The most common text format for API data — { "name": "Jane" }.

A tour of the screen

The window has five main areas:

┌──────────────────────────────────────────────────────────────────────┐
│  [logo] Orbittest Client   [Workspace ▾]        [ Search  Ctrl K ]     │  ← Title bar
├───┬──────────────┬─────────────────────────────────────┬─────────────┤
│ A │  Collections │   Request tabs                       │  Insights   │
│ c │   (sidebar)  │   ────────────────────────────       │  (right     │
│ t │              │   [GET ▾] [ URL.............] [Send]  │   panel)    │
│ i │   ▸ folders  │   Params Headers Auth Body ...        │             │
│ v │   ▸ requests │   ───────────────────────────         │  Orbit      │
│ i │              │   Response  Headers  Cookies ...      │  Score      │
│ t │              │   ───────────────────────────         │  Drift      │
│ y │  [Ghost ⚪]   │   Code panel + Tools                  │  Recorder   │
├───┴──────────────┴─────────────────────────────────────┴─────────────┤
│  ● Online                          Timeout 60s   Ctrl+Enter  Ctrl+S   │  ← Status bar
└──────────────────────────────────────────────────────────────────────┘

1. Activity bar (far left) — jumps between features: Collections, Environments, History, Flight Recorder, Ghost Server, Drift Radar, Secret Guard, Insights, Import/Export, Settings.
2. Sidebar — your saved requests, grouped into collections and folders. The Ghost Mock Server card sits at the bottom.
3. Center — where you build a request (top) and read the response (bottom). Tabs let you have several requests open at once.
4. Insights panel (right) — automatic health checks on your responses: Orbit Score, Drift Radar, Secret Guard, and the Flight Recorder.
5. Status bar (bottom) — online/offline indicator and shortcut reminders.

Tip

Every divider between these areas can be dragged to resize — see Resizing the layout.

Building requests in detail

The center top is the request builder. Set the method, type the URL, then use the row of tabs to fill in the details.

The method and URL

• Method dropdown — pick GET, POST, PUT, PATCH, DELETE, HEAD, or OPTIONS. The color tells you the kind at a glance (green = GET, yellow = POST, and so on).
• URL box — paste or type the full address. You can use variables here like {{baseUrl}}/users (see Variables and environments).

The tabs under the URL

Params — query parameters, the ?page=1&limit=20 bits at the end of a URL. Add them as rows here instead of typing into the URL. Each row has a checkbox (turn it off to disable without deleting), a Key, a Value, and an optional Description. Start typing in the empty bottom row and a new blank row appears automatically.

Headers — extra instructions for the server, same row layout as Params. A common one is Accept: application/json (“please reply in JSON”).

Auth — how you prove who you are:

• No Auth — nothing attached.
• Bearer Token — paste a token; sent as Authorization: Bearer <token>.
• Basic Auth — a username and password.
• API Key — a key/value pair you can put in either a header or the query string.

Body — the data you send along (used for POST/PUT/PATCH, not GET):

• None — no body.
• JSON — type JSON like { "name": "Jane" }. The wand icon auto-formats it, and Orbittest Client warns you in red if the JSON is invalid.
• Text — any raw text.
• Form URL-encoded — key/value pairs sent as a form.

Pre-Run and Post-Run — small scripts that run before and after the request. Covered in Pre-Run and Post-Run scripts.

Settings — per-request options: rename the request, put it in a Folder, set a Timeout, toggle Follow redirects, toggle Skip TLS verification (insecure), and add Notes.

Skip TLS verification

This ignores HTTPS certificate errors for that one request — useful when a server has a misconfigured or self-signed certificate. It removes protection against impersonation, so only use it for testing, never for real/sensitive endpoints.

Save your work

Press Ctrl+S or the save icon. A small dot on the request’s tab means there are unsaved changes.

Reading the response

After you hit Send, the bottom half shows the reply. The tabs across it:

• Response — the body of the reply, with three view modes: Pretty (formatted, color-coded), Raw (exactly what the server sent), and Preview (renders HTML replies as a web page). Use the copy and download icons to grab the body.
• Headers — the metadata the server sent back.
• Cookies — any cookies the server set.
• Timeline — how the time was split between waiting and downloading.
• Tests — pass/fail results from your Post-Run script.
• Drift Radar — whether the response’s shape changed since last time.

On the right of the Response view is the Schema panel, which shows the inferred shape of the data (which fields exist and their types) plus quick Actions like “Copy as cURL.”

The status badge color tells you the outcome instantly: green (2xx success), blue (3xx redirect), amber (4xx — you did something wrong, like a bad URL), red (5xx — the server errored, or a network problem).

Collections and folders (staying organized)

The sidebar holds your saved requests:

• A Collection is a top-level group (e.g. “Orbit CRM API”). Click + at the top of the sidebar to make one.
• Inside a collection, requests can be grouped into Folders (e.g. “Authentication”, “Users”). Set a request’s folder in its Settings tab.
• Add a request: hover a collection and click its +, or press the + on the tab bar.
• Rename a collection: double-click its name.
• Duplicate / delete a request: hover it and use the copy / trash icons, or right-click for the full menu.
• Search: type in the sidebar’s search box to filter by name, URL, or folder.
• Right-click a request or collection for the full menu: Run, Add request, Rename, Duplicate, Sort requests A–Z, and Delete.

Open multiple requests at once — each opens in its own tab across the top. Middle-click a tab (or use its ✕) to close it; Ctrl+W closes the active tab.

Jump anywhere fast — press Ctrl+K to open the command palette, type a few letters of any request’s name, URL, or folder, and press Enter to open it.

Running a whole collection

Right-click a collection and choose Run to open the run setup. Pick which requests to include, attach an optional data file (CSV or JSON), set the number of iterations and a delay between requests, and choose whether to stop on first failure, persist captured variables, and save response bodies for the report.

When the run finishes you get a per-request pass/fail summary with status codes and timings, and (on Pro) buttons to export a JSON or HTML Report.

Variables and environments

Variables let you avoid repeating yourself and switch between, say, your local server and the live one without editing every request. A variable is written {{name}} and can be used in the URL, headers, params, body, and auth fields. For example, set baseUrl once, then every request can use {{baseUrl}}/users.

The four scopes

Scope	Available in	Use it for
Global	every request, everywhere	values shared across all projects (e.g. apiVersion)
Collection	every request in one collection	values for one API (e.g. a default resource)
Environment	whichever environment is active	values that change per environment — Dev vs QA vs Production (e.g. baseUrl, password)
Local	a single send / script run	throwaway values staged by a script

Precedence when the same name exists in more than one scope (narrowest wins):

Local  >  Environment  >  Collection  >  Global

So a baseUrl defined in your active environment overrides a baseUrl in the collection, which overrides one in globals. This is what lets you keep one baseUrl name everywhere and just switch environments.

Managing variables

Open the Variables manager — the Environments icon in the activity bar, the gear next to the environment dropdown (top-right), or Environment Variables in the Tools grid. It has three tabs:

• Globals — global variables (key/value rows).
• Environments — create as many as you like (e.g. Dev, QA, Production) with New environment, give each its own variables, and tick Use as active environment.
• Collections — pick a collection and edit its collection-scoped variables.

Switching environments

Pick the active environment from the dropdown at the top of the Insights panel, or tick “Use as active environment” in the modal. When you send a request, Orbittest Client merges all scopes by precedence and swaps every {{name}} for its resolved value.

Local variables come from scripts: ot.setVar("key", value) in a Pre-Run script stages a value for that one send. Scripts can also write to the other scopes with ot.setEnvVar, ot.setCollectionVar, and ot.setGlobalVar.

Pre-Run and Post-Run scripts

These are small pieces of JavaScript that run automatically around your request. You don’t have to write them from scratch — each section has a snippets rail on the left; click a snippet to drop ready-made code into the editor, then tweak it.

Pre-Run — runs before the request is sent

Use it to prepare values. Available helpers:

• ot.setVar("key", "value") — set a variable used in this send (referenced as {{key}}).
• ot.env.get("key") — read an environment variable.
• ot.uuid() — a unique id. ot.timestamp() — the current time in milliseconds.

ot.setVar("requestId", ot.uuid());

Ten ready-made Pre-Run snippets are included: set a variable, generate a request id, timestamps, random numbers/emails, build auth headers, future dates, and more.

Post-Run — runs after the response arrives

Use it to validate the response. Results show up in the Tests tab as green (pass) or red (fail). Helpers:

• ot.test("name", () => { ... }) — one check.
• ot.expect(value) with matchers: .toBe(), .toEqual(), .toContain(), .toBeLessThan(), .toBeGreaterThan(), .toBeDefined(), .toBeTruthy(), .toMatch().
• ot.response — the reply: { status, ok, headers, json, text, durationMs, sizeBytes }.
• ot.setVar("key", value) — save a value back to the active environment.

ot.test("status is 200", () => {
  ot.expect(ot.response.status).toBe(200);
});

ot.test("responds within 500ms", () => {
  ot.expect(ot.response.durationMs).toBeLessThan(500);
});

Real-world combo

In a Login request’s Post-Run, capture the token:

ot.test("got token", () => {
  ot.expect(ot.response.json.token).toBeDefined();
  ot.setEnvVar("token", ot.response.json.token); // persists to the active environment
});

Then in other requests set Auth → Bearer Token to {{token}}. The token flows automatically.

Writing to a specific scope from a script:

Call	Saves to	Lives…
ot.setVar(k, v)	Local	this send only (pre-run) — gone afterward
ot.setEnvVar(k, v)	Environment	the active environment, persisted
ot.setCollectionVar(k, v)	Collection	the current collection, persisted
ot.setGlobalVar(k, v)	Global	everywhere, persisted

ot.env.get(k) (or ot.get(k)) reads the merged value, honoring precedence.

Code generation (use your request elsewhere)

The Code panel near the bottom turns your current request into copy-paste code in cURL, JavaScript (fetch), Axios, and Python (requests). Pick a tab, click the copy icon, and paste it into your own project. It always matches what you’d actually send, including your active environment’s variable values.

The Insights panel (automatic checks)

The right-hand panel analyzes your responses for you. Nothing to configure — it just works as you send requests.

• Orbit Score — a single 0–100 health grade for your workspace, blending Reliability (how often requests succeed, 50%), Schema Stability (how often the response shape stays the same, 30%), and Speed (average response time, 20%).
• Contract Drift Radar — compares this response’s shape to the previous run of the same request and flags fields that were Added, Removed, or Modified. Catches a server quietly changing its data format.
• Secret Guard — scans each response, its headers, and the URL for leaked secrets (bearer tokens, JWTs, AWS keys, private keys, password-like values) and warns you. Stored URLs are masked automatically.
• Flight Recorder — a running log of every request you’ve sent. Click any entry to re-open that exact response.

You can hide the whole panel with the Insights icon in the activity bar if you want more room.

Ghost Mock Server (fake a server from your replies)

Sometimes you want a stand-in server — for example, so a teammate’s app keeps working while the real server is down. Ghost turns your recorded responses into a live local server.

1. Send each request you want to mock at least once (Ghost replays what it recorded).
2. Flip the Ghost Mock Server toggle in the sidebar card.
3. Ghost starts at an address like http://127.0.0.1:4010. Point your app at it and it’ll get back the recorded replies.
4. Click Open Dashboard to see a live page of every mocked route and how many times each was hit (it lives at /__orbit__).

Flip the toggle off to stop it.

Settings

Open Settings from the bottom of the activity bar. It’s a window with a left-hand menu:

• General → Request — app-wide request behavior:
  • HTTP version — choose the HTTP version for requests (Auto by default).
  • Request timeout (ms) — how long to wait for a response; 0 = never time out. A request’s own timeout overrides this.
  • Max response size (MB) — bodies larger than this are truncated; 0 = unlimited.
  • SSL certificate verification — global on/off for verifying HTTPS certificates.
  • SSL/TLS key log — enable session key logging for debugging encrypted connections (requires restart).
  • Disable cookies — don’t capture Set-Cookie headers.
  • Response format detection — Auto parses JSON-looking bodies; JSON always tries to parse as JSON.
• Themes — pick a theme (Orbit Dark, Midnight, Slate, Graphite) and an accent color; changes apply instantly.
• Shortcuts — the keyboard shortcuts reference.
• Data — show the workspace file in your file manager, open the Variables manager, export/import, and clear history.
• Certificates — TLS verification controls and notes.
• Proxy — route all requests through an HTTP/HTTPS proxy (http://host:port, or with user:pass@).
• About — version and build info.

Settings are global (they apply to every workspace) and are saved automatically.

Importing and exporting

Find these in the Import / Export activity-bar icon and the Tools grid near the code panel:

• Import cURL — paste a curl ... command (e.g. copied from your browser’s dev tools) and Orbittest Client turns it into a request.
• Import Postman / Orbittest — open a Postman v2.1 collection .json or an Orbittest_Client export; folders are preserved.
• Export Workspace — save your whole workspace to a .json file to back up or share. (History is left out of exports.)
• Git-friendly export — write a folder with one stably-ordered file per collection (history excluded) — ideal for version control.

Workspaces (switching projects)

A workspace is one .json file holding all your collections, environments, and history. By default it lives at Documents/Orbittest/workspace.json.

Click the workspace name (next to the logo in the title bar) for a menu to:

• Open workspace file… — load a different workspace .json.
• New workspace… — create a fresh, empty one wherever you choose.
• Switch between recent workspaces in one click.
• Use default workspace — jump back to the standard one.

Orbittest Client remembers the last workspace you used and reopens it next launch.

Resizing the layout

Every section can be made bigger or smaller — hover the thin divider between two areas until the cursor changes, then drag: sidebar ↔ center, request builder ↕ response, response ↕ code panel, response body ↔ schema panel, and center ↔ insights panel. Your sizes are remembered between sessions. The code panel can also be collapsed entirely with the chevron on its header.

Keyboard shortcuts

Shortcut	Action
Ctrl + Enter	Send the current request
Ctrl + S	Save the current request
Ctrl + K	Open the search / command palette
Ctrl + W	Close the current tab
Esc	Close an open menu or dialog

Where your data lives

• Default workspace: Documents/Orbittest/workspace.json
• It’s a plain JSON file written safely (so a crash mid-save won’t corrupt it).
• No data ever leaves your machine. Back it up by copying the file or using Export Workspace.

Troubleshooting

Symptom	What it usually means / what to do
”Could not resolve host”	The URL’s domain is wrong, or you’re offline. Check spelling and the ● Online indicator.
”Connection refused”	Nothing is listening at that address. If it’s a local server, make sure it’s running.
Request “timed out”	The server took longer than your timeout. Raise it in the request’s Settings tab.
”TLS certificate problem”	The server’s HTTPS certificate couldn’t be verified — usually a self-signed or misconfigured cert. To test anyway, turn on Skip TLS verification (insecure) in the request’s Settings tab.
Red 4xx status	The request was wrong — bad URL path, missing auth, or malformed body.
Red 5xx status	The server failed. Usually not your fault; try again or check the server.
A {{variable}} came through literally	No active environment, or the variable isn’t defined there. Open Environments and check.
Body shows “not valid JSON”	Fix the JSON (matching quotes/braces) or use the wand icon to format and spot the error.
Secret Guard warning	A token or key appeared in the response — expected if you’re testing auth; a heads-up otherwise.

A complete example, start to finish

Let’s create a user, then verify it.

1. New request: click + on a collection. In Settings, name it “Create User” and set folder “Users”.

2. Method & URL: choose POST, URL https://jsonplaceholder.typicode.com/users.

3. Body: pick JSON and enter:

   { "name": "Jane Cooper", "email": "jane@example.test", "role": "admin" }

4. Post-Run: open the tab, click the “Status is one of” snippet, and adjust it:

   ot.test("created", () => {
     ot.expect([200, 201]).toContain(ot.response.status);
   });

5. Send (Ctrl+Enter). You should see a 201 Created reply, the new user echoed back, and a green pass in the Tests tab.

6. Save (Ctrl+S). The request is now in your sidebar to reuse anytime.

That’s the whole loop: build → send → read → validate → save. From here, explore environments, Ghost, and the Insights panel as you need them.