Importing Postman collections and environments
Bring Postman collections, with their folders, auth and scripts, and Postman environments into Relay.
Overview
If you've been working in Postman, you can bring your collections and environments into Relay. A collection keeps its nested folders, variables, authentication at every level, scripts and request settings. An environment becomes an environment in the workspace you choose.
Relay imports Postman Collection v2.0 and v2.1 files and Postman environment exports, all in JSON. In Postman, export a collection as Collection v2.1.
Import a collection
- Choose File > Import > Postman Collection…. You can also click the Add button (+) at the bottom of the sidebar and choose Import > Postman Collection….
- Choose where the collection comes from:
- File: Drag a
.jsonfile onto the sheet, or click Choose File…. - URL: Enter the address of the collection's raw JSON file and click Fetch.
- Paste: Paste the collection's JSON. If the clipboard holds a collection when you open the sheet, Relay pastes it for you.
- File: Drag a
- Check the Preview. It shows the collection's name and format, how many requests and folders it creates, its authentication, the variables it adds, any warnings and the list of requests.
- Next to Import into, select New workspace or Existing workspace.
- For a new workspace, enter a Workspace name.
- For an existing workspace, choose it next to Workspace.
- Optionally, enter a Collection name. Both names default to the collection's name.
- Click Import.
Relay opens the new collection in the sidebar and selects its first request. To remove everything the import created, choose Edit > Undo.
You can also drag a collection file onto a Relay window. Relay reads it and opens the importer with the file already loaded.
Relay explains what to do instead when you give it a Postman Collection v1 file, a globals file or a full data export. If the document is an OpenAPI spec, click Import as OpenAPI Spec to import it with the OpenAPI importer.
Learn what the import creates
The import creates one collection, named after the Postman collection:
- Folders: Folders keep their nesting and order, along with their variables, authentication, scripts and settings. To see a folder's settings, Control-click it in the sidebar and choose Edit Variables…, Edit Auth… or Edit Scripts….
- Requests: Each request keeps its method, URL, query parameters, headers and body, including GraphQL bodies. Rows that are turned off in Postman stay turned off. A path variable such as
:idis filled in with its value, or becomes a{{id}}placeholder when it has none. - Documentation: A request's description appears in its Documentation tab. Collection and folder descriptions aren't imported.
- Dynamic variables: Tokens such as
{{$guid}}and{{$timestamp}}stay as written, and Relay generates their values when you send. For more, see Generating dynamic values.
Some things don't come across, and the Preview warns you about each:
- File fields in form-data bodies, and binary file bodies. Add the files in Relay.
- Saved example responses.
- OAuth 2.0 access tokens saved in the collection. Get new tokens in the Auth tab.
- Requests whose method Relay can't send.
- Variable names Relay can't use. Relay renames them, replacing each character other than letters, digits,
_,.and-with_, and updates the requests that use them.
Variables
The collection's variables become workspace variables when you import into a new workspace, so every request in the workspace can use them. They become variables of the new collection instead when you import into an existing workspace, or when the collection has scripts, which read and write them through pm.collectionVariables.
If requests use variables the collection doesn't define, the Preview lists them. They usually come from a Postman environment; import it as described below.
Authentication
Authentication is imported at every level: the collection's, each folder's and each request's. The collection's authentication becomes the workspace's in a new workspace, or the collection's in an existing one. A level set to inherit in Postman inherits in Relay too.
Postman auth type | Relay authentication |
|---|---|
noauth | No Auth |
bearer | Bearer Token |
basic | Basic Auth |
apikey | API Key |
jwt | JWT Bearer |
digest | Digest Auth |
ntlm | NTLM |
awsv4 | AWS Signature |
hawk | Hawk |
oauth1 | OAuth 1.0 |
oauth2, with the authorization code grant (with or without PKCE) or the client credentials grant | OAuth 2.0 |
Akamai EdgeGrid, ASAP and the OAuth 2.0 implicit and password grants aren't supported. Items that use them are imported without authentication, and the Preview warns you. For more, see Inheriting authentication.
Scripts
Pre-request and test scripts become pre-request and post-response scripts on the collection, folders and requests they belong to. A script can come from anyone who shared the collection, so imported scripts don't run until you allow them. Open a request's Scripts tab, or Control-click a collection or folder and choose Edit Scripts…, review the script under This script changed outside Relay, and click Allow. For more, see Allowing scripts to run.
Settings
Postman's per-request settings, stored in its exports as protocolProfileBehavior, are imported at every level, and requests inherit them from their folders and collection:
| Postman setting | Relay setting |
|---|---|
followRedirects | Follow Redirects |
maxRedirects | Maximum Redirects |
followOriginalHttpMethod | Follow Original Method |
followAuthorizationHeader | Keep Authorization Across Origins |
strictSSL | Verify Certificates |
The Preview lists any other settings it couldn't import. For more, see Configuring request settings.
Import an environment
A Postman environment becomes an environment in an existing workspace.
- Choose File > Import > Postman Collection….
- Choose, fetch or paste the environment's JSON file. The sheet's title changes to Import Postman Environment, and the Preview lists the environment's variables.
- Next to Workspace, choose the workspace to add it to.
- Optionally, enter an Environment name. It defaults to the environment's name in Postman. If the workspace already has an environment with that name, Relay keeps both.
- Click Import.
The window switches to that workspace. If it's the workspace's first environment, it becomes the active one; otherwise, choose it from the workspace menu. Variables that Postman marks secret are marked secret in Relay, so their values stay on your Mac. Postman leaves secret values out of exports, so fill them in after importing. For more, see Managing environments.
To bring over a collection and the environment it uses, import the collection into a new workspace first, then import the environment into that workspace.
See Also
- Migrating scripts from Postman and Bruno: Run your existing Postman and Bruno scripts in Relay and learn what's different.
- Managing environments: Switch between sets of variables for development, staging and production.
- Configuring collections and folders: Give a collection or folder variables, authentication, scripts and settings that its requests inherit.
- Importing OpenAPI specs: Create a collection of requests from an OpenAPI 3.0 or 3.1 spec.