Documentation

Getting Started

Relay is a native macOS REST client built for speed and simplicity. It launches in under 500ms, sends requests with minimal overhead, and keeps your workflow focused.

Your first request

1. Open Relay and press ⌘T to create a new request.
2. Type a URL in the URL bar (e.g. https://jsonplaceholder.typicode.com/posts).
3. Press ⌘↩ to send.
4. The response appears in the panel below with status, timing, and body.

Interface overview

• Sidebar: Collections, folders, and your working set of recent/pinned requests. Resizable from 200–400pt.
• URL bar: Located in the title bar. Shows the HTTP method selector and request URL with variable highlighting.
• Request config: Tabs for Params (⌘1), Headers (⌘2), Auth (⌘3), Body (⌘4), Extract, and Tests.
• Response panel: Displays the response body with format-specific viewers, headers, cookies, and timing metrics.
• Console: Toggle with ⌘J to see a log of all requests and responses with expandable details.
• Inspector: Toggle with ⌘⌥I for a side panel showing response headers, cookies, and timing breakdown.

Requests

HTTP methods

Relay supports nine HTTP methods: GET, POST, PUT, DELETE, PATCH, HEAD, OPTIONS, TRACE, and CONNECT.

By default only the five common methods are shown. Enable all nine in Preferences → General → Show all HTTP methods. Cycle through methods with ⌘⇧→ and ⌘⇧←.

Query parameters

Add parameters in the Params tab as key-value pairs. Each parameter has an enable/disable toggle. Disabled parameters are excluded from the URL without being deleted. Parameters sync bidirectionally with the URL bar.

Headers

Add custom headers in the Headers tab. Like parameters, each header has an enable/disable toggle. Headers support {{variable}} interpolation.

Set default headers that apply to every new request in Preferences → Default Headers.

Request body

• JSON: Raw JSON editor with syntax highlighting.
• Form Data: Key-value pairs with text and file field types. File fields automatically detect MIME types.
• File: Upload a file directly as the request body.

Redirects

By default Relay follows HTTP redirects. Toggle this per-request in the Inspector panel.

Timeout

The default request timeout is 30 seconds, configurable in Preferences → General.

Collections & Folders

Collections group related requests together. Each collection is stored as a folder on disk with individual JSON files for each request, easy to version-control or back up.

Creating & organizing

• Click + New Collection at the bottom of the sidebar, or press ⌘⇧N.
• Right-click a collection to create folders, add requests, rename, or delete.
• Drag requests between folders or reorder them within a collection.
• Folders can be nested for complex API structures.

Working set

The Working Set at the top of the sidebar shows your recently opened and pinned requests. Pin a request with ⌘D to keep it easily accessible.

Favorites

Star a collection to pin it in the Favorites section of the sidebar for quick access.

Collection & folder settings

Click a collection or folder name to open its settings panel. Here you can configure inherited headers and variables that apply to all requests within that scope.

Authentication

Configure auth in the Auth tab (⌘3). The selected auth method is applied automatically when sending the request.

Variables & Environments

Use {{variableName}} anywhere: URLs, params, headers, auth tokens, and request bodies. Relay highlights variables inline with color-coded source indicators.

Variable scopes

Variables resolve with a clear precedence order. When the same key exists at multiple levels, the most specific scope wins:

Managing variables

• Global variables: Manage in Preferences → General or via the gear icon in the sidebar Collections header.
• Collection variables: Click a collection name in the sidebar to open its settings.
• Folder variables: Click a folder name to configure variables inherited by all requests inside it.
• Environments: Create named environment sets (e.g. Development, Staging, Production) and switch between them from the toolbar dropdown. Each environment has its own set of variables.

Autocomplete

Type {{ in any variable-enabled field to see an autocomplete dropdown of available variables with their current values and source scope.

Response Viewer

Relay automatically selects the best viewer based on the response content type. Use ⌘F to search within the response body.

Large responses

Responses over 10 MB display a Save to File option prominently. The first 1 MB is rendered with a “Load More” option for the rest.

Response history & diff

Relay keeps a history of responses for each request. Compare any two past responses side-by-side with the built-in diff viewer to spot changes in API behavior over time.

Code Generation

Press ⌘K to open the code generator. Relay converts your current request, including params, headers, auth, and body, into ready-to-use code.

Importing

Migrate from other tools or import API specs. Relay preserves folder structure, auth configs, and request bodies.

• Postman v2.1: Full import of collections, folders, auth, form-data, and scripts (preserved as notes).
• Insomnia v4: JSON and YAML formats. Workspaces map to collections, request groups to folders.
• OpenAPI: Generates requests from API specs with example values based on schemas.
• cURL: Paste a cURL command with ⌘⇧V to import it as a request instantly.

Import from the File menu: ⌘O for file import, ⌘⇧O for URL import.

Variable references like {{baseUrl}} from Postman and Insomnia are preserved as-is. Create matching variables in Relay to activate them.

Console

Toggle the console with ⌘J. It logs every request and response with timestamps, HTTP method badges, status codes, response times, and body sizes.

• Click any entry to expand and see full request/response headers and body previews.
• Failed requests show error details inline.
• Proxied requests are flagged with a badge.
• The console panel is resizable by dragging its top edge.

Extractors & Assertions

Extractors

Pull values out of responses automatically using JSONPath expressions and store them as variables. Useful for chaining requests. Extract an auth token from a login response, then reference it as {{token}} in subsequent requests.

• Configure extractors in the Extract tab.
• Choose the target scope: collection, environment, or global.
• Results appear after each request with the extracted values.

Assertions

Add test conditions in the Tests tab. After sending a request, Relay evaluates each assertion and shows a pass/fail summary banner.

Cookie Jar

Each collection has its own cookie jar that automatically captures cookies from Set-Cookie response headers and sends matching cookies on subsequent requests to the same domain.

• Enable or disable the cookie jar per collection in its settings.
• Cookies follow RFC 6265 domain and path matching rules.
• Expired cookies are automatically purged.
• View, add, edit, or delete cookies manually in collection settings.

Proxy & Client Certificates

Proxy

Configure a proxy in Preferences → Proxy. Relay supports HTTP, HTTPS, and SOCKS5 proxies with optional authentication and a bypass list for specific hosts.

Client certificates (mTLS)

For mutual TLS authentication, configure a PKCS12 certificate (.p12 / .pfx) in Preferences → Certificates. Passwords are stored securely in macOS Keychain.

Set a global certificate for all requests, or override per-collection in the collection settings.

iCloud Sync

Sync your collections across all your Macs with iCloud. Enable in Preferences → Sync. Requires an iCloud account signed in via System Settings.

When sync is enabled, Relay manages the storage location automatically. Changes propagate across devices within minutes.

Keyboard Shortcuts