MCP Tools

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 content and url, or url isn't an http or https URL.
  • You pass workspaceId with destination set to newWorkspace, or pass newWorkspace for an environment.
  • Relay has more than one workspace and you don't pass workspaceId for 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