Import and Export

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

  1. Choose File > Import > Postman Collection…. You can also click the Add button (+) at the bottom of the sidebar and choose Import > Postman Collection….
  2. Choose where the collection comes from:
    • File: Drag a .json file 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.
  3. 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.
  4. 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.
  5. Optionally, enter a Collection name. Both names default to the collection's name.
  6. 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 :id is 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 typeRelay authentication
noauthNo Auth
bearerBearer Token
basicBasic Auth
apikeyAPI Key
jwtJWT Bearer
digestDigest Auth
ntlmNTLM
awsv4AWS Signature
hawkHawk
oauth1OAuth 1.0
oauth2, with the authorization code grant (with or without PKCE) or the client credentials grantOAuth 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 settingRelay setting
followRedirectsFollow Redirects
maxRedirectsMaximum Redirects
followOriginalHttpMethodFollow Original Method
followAuthorizationHeaderKeep Authorization Across Origins
strictSSLVerify 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.

  1. Choose File > Import > Postman Collection….
  2. 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.
  3. Next to Workspace, choose the workspace to add it to.
  4. 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.
  5. 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