import_collection
Imports an OpenAPI spec, a Postman collection or a Postman environment.
Overview
import_collection imports a document and detects its format: an OpenAPI 3.0 or 3.1 spec in JSON or YAML, a Postman Collection v2.0 or v2.1, or a Postman environment. Pass the document's text as content, or an http or https URL to download it from. Use url for documents over a few megabytes.
A spec or collection becomes a collection of requests. By default it goes in a new workspace, stored in Relay, along with its variables and auth:
{
"url": "https://api.example.com/openapi.yaml"
}To add the collection to a workspace you already have, pass its workspaceId. The collection's variables and auth then go on the collection, where they apply only to its requests:
{
"content": "{ \"info\": { \"name\": \"Orders\", \"schema\": \"https://schema.getpostman.com/json/collection/v2.1.0/collection.json\" }, \"item\": [] }",
"workspaceId": "7D1E6C2A-4F0B-4C55-9A57-3B8E2F1D9C40"
}A Postman environment is always added to an existing workspace as a new environment.
Parameters
Prop
Type
Return Value
For a spec or collection, kind is collection:
{
"kind": "collection",
"format": "openapi",
"formatVersion": "3.1.0",
"workspaceId": "4A8C1E3F-5B7D-4920-8E6A-0C2D4F6B8A19",
"workspaceName": "Orders API",
"collectionId": "A1F3D5B7-0C2E-4A6B-8D9F-1E3C5A7B9D02",
"collectionName": "Orders API",
"requestCount": 14,
"folderCount": 3,
"baseUrl": "https://api.example.com/v2",
"auth": "Bearer Token",
"authScope": "workspace",
"variablesAdded": ["baseUrl", "bearerToken"],
"variableScope": "workspace",
"renamedVariables": [],
"warnings": []
}Prop
Type
For a Postman environment, kind is environment:
{
"kind": "environment",
"format": "postman",
"workspaceId": "7D1E6C2A-4F0B-4C55-9A57-3B8E2F1D9C40",
"workspaceName": "Orders API",
"environmentId": "C3A9F0E2-1B7D-4E8A-8F21-6D5C0B9A7E13",
"environmentName": "Staging",
"isActive": false,
"variablesAdded": ["baseUrl", "accessToken"],
"secretVariables": ["accessToken"],
"warnings": []
}Prop
Type
Discussion
An import into a new workspace puts the collection's variables on the workspace, unless the collection has scripts, in which case they go on the collection so the scripts can read them as collection variables. variableScope says which. An import into an existing workspace always puts them on the collection.
From a Postman collection, Relay keeps nested folders and their variables, auth at every level, request settings and pre-request and test scripts. Imported scripts don't run until you review them and click Allow in Relay. File fields in form bodies and auth types Relay doesn't have are left out, each with a warning. From an OpenAPI spec, Relay creates a folder per tag, a baseUrl variable and empty variables for credentials, and maps the spec's security schemes onto Relay auth.
The tool returns an error when:
- You give both or neither of
contentandurl, orurlisn't anhttporhttpsURL. - You pass
workspaceIdwithdestinationset tonewWorkspace, or passnewWorkspacefor an environment. - Relay has more than one workspace and you don't pass
workspaceIdfor an existing workspace or an environment. - The target workspace is read-only or unavailable.
- The document isn't a format Relay imports, such as Swagger 2.0, Postman Collection v1, a Postman globals file or a Postman data export, or is over 20 MB.
The import isn't added to any window's undo history, and no window switches to a new workspace.
See Also
- import_openapi: Imports an OpenAPI 3.0 or 3.1 spec as a collection of requests.
- Importing OpenAPI specs: Create a collection of requests from an OpenAPI 3.0 or 3.1 spec.
- Importing Postman collections and environments: Bring Postman collections, with their folders, auth and scripts, and Postman environments into Relay.
- Supported formats: The import formats, body types, auth types and limits Relay supports.