Skip to content

Collections

Collections are the unit of organisation in Restura: a tree of folders and requests, with auth and variables that cascade.

New to Restura? With no collections yet, choose Try sample collection (in the Collections sidebar or the empty workspace) to add Restura Echo (sample) — ready-to-send HTTP, GraphQL, gRPC and SSE requests against the echo server, with a folder, a collection variable and a test script to explore.

  • Collection — top-level folder. Can carry its own auth, scripts, variables, and markdown docs (with a live preview in collection settings).
  • Folder — nested inside a collection or another folder. Carries its own auth, scripts, and variables (right-click → Folder settings).
  • Request — leaf node. Inherits from parents unless overridden.

Save to Collection stores the request exactly as configured in its tab: HTTP, GraphQL, and gRPC requests (gRPC with its schema snapshot and timeout), SSE requests with their URL, headers, query params, auth, event filter, and reconnect setting, and MCP requests as one operation — the method (for example tools/call, resources/read, prompts/get) plus its parameters. Opening a saved item restores that configuration in the builder.

WebSocket and Socket.IO tabs save as native collection items — see WebSocket and Socket.IO connections below.

On desktop, Save to Collection on a Kafka or MQTT tab stores a connection preset: the broker connection (brokers / URL, auth mode, TLS file paths, client id) plus what you were about to send or receive — the Kafka topic, key, payload template, headers and consumer group/topics, or the MQTT publish / subscribe drafts and saved publish templates. Opening the preset from the sidebar (it shows a KAFKA / MQTT badge) opens the matching panel prefilled; it doesn’t connect until you press Connect.

  • Credentials stay local. SASL passwords, OAuth tokens, TLS key passphrases and MQTT passwords (including ones typed but not yet connected) are copied into the desktop’s encrypted store under the preset, never into the collection. They’re never exported, written to a git-native collection or shared — a teammate enters their own after importing. Deleting a preset (or its folder / collection) removes them; duplicating copies them. A user:password@ part typed into a broker or registry address is not saved — use the password fields.
  • Save changes (tab menu or Ctrl/Cmd+S) on a tab opened from a preset updates that preset in place.
  • The collection runner and the CLI skip presets (the runner lists how many).
  • Per-environment presets. Brokers, topics, keys, payloads and headers can hold {{variables}}; they’re resolved from the active environment when you connect, produce, subscribe or publish (unresolved ones are sent as typed and flagged in the message log).
  • Presets export through OpenCollection (x-restura-kafka / x-restura-mqtt, see the reference) and git-native collections. Postman v3 export carries Kafka / MQTT items but reports broker-only options (SASL, TLS paths, schema registry, …) as not exported; Insomnia and Bruno exports write a named “not supported” stub instead.
  • On the web build, imported presets are listed but open the desktop-only panel.

On web and desktop, Save to Collection on a WebSocket or Socket.IO tab stores the connection (#1209): the URL, handshake headers and the protocol settings (WebSocket subprotocols, reconnect, heartbeat, permessage-deflate and frame assertion; Socket.IO namespace, path, transports, query rows, handshake auth as rows or JSON, reconnect, timeout and emit options, subscribed events), the message you were composing and your saved messages / emits. Values are stored as typed — {{variables}} stay unresolved and are resolved when you connect or send.

  • Opening the item from the sidebar (it shows a WS / SIO badge), the command palette or a deep link opens a connection tab prefilled; it doesn’t connect until you press Connect. Save changes (tab menu or Ctrl/Cmd+S) on that tab updates the item in place.
  • They are connections, not requests: the collection runner and the CLI skip them with a notice (the runner counts them as skipped presets).
  • They round-trip through OpenCollection and git-native collections — WebSocket as a native websocket item, Socket.IO in x-restura-socketio (see the reference) — and through Postman v3 (websocket-request / socket.io-request). Postman v2.1 cannot hold them (reported), and Insomnia / Bruno exports write a named “not supported” stub.
  • Secrets. Handshake headers, query rows and Socket.IO auth rows are stored like the live connection keeps them — in the collection, not converted to keychain handles. On export (with secrets excluded) credential-named header and query values, URL credentials (user:password@ and ?access_token=-style query values) and every Socket.IO handshake auth value are blanked — in a JSON auth payload, every literal value at any depth ({{variable}} references are kept). Message payloads and subprotocols are not redacted, like HTTP bodies — keep secrets in variables.

Anything you set on a folder cascades to every descendant unless that descendant explicitly overrides it. Concretely:

  • Auth — Inherit from parent is the default on new requests.
  • Scripts — collection scripts run first, then folder scripts (outermost first), then the request’s own, in a collection run.
  • Variables — visible to all descendants; the nearest folder wins over outer folders and the collection, and all of them win over the active environment. See resolution order.
  • Drag requests or folders between locations.
  • Duplicate with right-click → Duplicate.
  • Rename inline with double-click.
  • Sort by name or by drag order.
  • Select several — Ctrl/Cmd-click toggles an item; Shift-click selects the range from the last selected item.
  • Keyboard — the sidebar is one tree across all collections: ↑/↓ move between rows (collection headers included), Home/End jump to the first and last row, →/← expand and collapse, Enter/Space open or toggle, F2 renames and Delete asks to delete.
  • Delete — the confirm names what goes: the request, or the folder with how many items and requests it holds (or each selected item). Deleting a collection names it with its request count and any linked workflows; open tabs stay open as unsaved copies. An in-memory collection can be brought back with Undo on the toast. For a filesystem-backed collection the files stay on disk and Restura stops tracking them — that can’t be undone in Restura.

The History sidebar lists past sends grouped by time. Filter by HTTP method or by protocol (a chip appears for each non-HTTP protocol in your history), remove a single entry with its delete button, or Clear history — it asks first and says how many entries go, favorites included.

Restura imports and exports OpenCollection natively (see reference) and supports Postman (v2.0 / v2.1 and the v3 folder format; see Import & export), Insomnia, Hoppscotch, Bruno, and OpenAPI / Swagger import. Postman export defaults to Postman v3 (folder / zip); pick Postman v2.1 (single file · Newman) for Newman or other v2.1 tooling, since Newman cannot run v3 collections. Export your work to share with teammates or commit to your repo.

On the desktop client, you can also point Restura at a filesystem-backed workspace and use Git on the directory.

While a run is in progress the runner dialog can’t be closed: it says Stop the run to close this dialog and offers Stop & close.

The collection runner records status, timing, assertions, and a safe response-evidence summary in the Runs panel. Choose one retention mode when starting a run:

  • Metadata only (the default) stores no body excerpt or hash.
  • Failures only keeps a redacted excerpt of failed text responses, capped at 64 KiB each.
  • All responses keeps a redacted excerpt of each text response, capped at 16 KiB each.

Restura redacts credential headers, cookies, recognizable secrets, and sensitive diagnostic values before any evidence is saved or exported. Binary/base64 responses are never retained. Evidence is also capped at 2 MiB per run and 20 MiB total; when needed, the oldest evidence is evicted while the run metadata remains visible.

From a saved run you can inspect evidence after reload, export JSON/JUnit/HTML reports, compare it with the most recent run for the same collection, and rerun failed or individual requests. Reruns use the current collection, environment, secrets, security policy, and platform capabilities. If the original run used a CSV or JSON data file, choose it again: input rows are never retained.

Open or clone an OpenCollection directory, then open the collection menu and choose Git…. Restura uses your installed Git and its existing SSH agent or credential manager; it does not ask for or store Git credentials.

The Git dialog supports status and diffs, staging, commits, branches, fetch/pull/push, and branch merges:

  1. Fetch to refresh remote-tracking branches.
  2. Under Branches, select a non-current local or remote branch and choose Merge branch. Restura pins the merge to the commit shown when you selected it, so a moving remote ref cannot silently change the operation.
  3. If Git reports conflicts, choose each file under Merge interrupted:
    • OpenCollection YAML gets field-level choices for mapping values. Lists remain atomic, avoiding surprising item-by-item merges.
    • Other text files show base, local, and incoming versions with an editable result.
    • Binary, oversized, and symlink conflicts offer whole-file choices. Submodules must be resolved with Git outside Restura.
  4. When all conflicts are resolved, review the merge message and choose Commit merge. This is an ordinary non-fast-forward Git commit, so configured signing still applies.

You can close the dialog or restart Restura during a conflict; reopening Git… reconstructs the merge from Git’s metadata and index. Abort merge restores the exact pre-merge state after confirmation.

Restura runs Git with repository hooks disabled (core.hooksPath set to the null device) and diff.external turned off, so hooks such as husky or commitlint do not run for commits, merges or pulls made from Restura’s Git dialog; run them from a terminal if you rely on them. Restura’s file access also refuses paths inside .git/.

Merging requires a clean working tree and an attached branch. Restura will not start a merge during a rebase, cherry-pick, or revert. Pull remains fast-forward-only; use the explicit merge workflow when histories diverge.

See workflows for portable workflows stored alongside collection files.