Import and export

The API client reads the formats other API tools write, so you can bring a Postman workspace, a spec or a teammate’s cURL command over in one step, and it writes them back out for people who use other tools. The client works out the format from the content, so you don’t have to say what you’re importing.

Import

123

Choose files or paste text; the format is detected for you.

1. Choose one or more files
2. Or paste JSON, YAML or a cURL command
3. Import what you pasted

×

Choose files

1. Click Import in the toolbar, or + › Import… in the Collections sidebar.
2. Click Choose Files… and select one or more .json, .yaml, .yml or .har files.
3. Each file is imported. If one fails, an alert says “Couldn’t import” with the file name and the reason, and the others still import.

Paste

1. Click Import in the toolbar.
2. Paste a collection, environment, spec, HAR file, Insomnia export or cURL command into the text area.
3. Click Import.

If the text can’t be read, the sheet says “Couldn’t import:” with the reason. A pasted HAR file becomes a collection called “Pasted”.

Drag and drop

Drag files from Finder onto the API client window. Each is imported the same way as with Choose Files….

What each format becomes

Format	Detected by	Becomes
cURL command	Text that starts with curl	A new unsaved request tab.
OpenAPI 3 or Swagger 2, JSON or YAML	An openapi or swagger field	A collection, plus the spec in Specs.
Postman environment	A values list and no info	A new environment.
Postman globals	A globals export (_postman_variable_scope is globals)	Variables added to Globals.
HAR	A log.entries list	A collection named after the file, with one folder per host.
Insomnia v4 export	_type is export with resources	One collection per Insomnia workspace, plus its environments.
Postman collection v2.0 or v2.1	Anything else with an info object	A collection. Exports from the Postman API, wrapped in {"collection": …}, work too.

Postman collections

Postman collections come in with almost everything:

Postman	In Cloak Proxy
Folders and requests, in order	Folders and requests. A request given as a bare URL string works too.
Descriptions	Docs on the collection, folders and requests.
Collection variables	Collection variables. Variables of type secret are marked secret.
Auth on the collection, folders and requests	The same auth, including inherit. Types the client doesn’t support, such as NTLM, become No Auth so the import still works. See Authorization.
Pre-request and test scripts	Pre-request and post-response scripts. See Scripts and tests.
URL, query and path variables	URL, Params and Path Variables.
Headers, including disabled ones	Headers, with disabled ones switched off.
Bodies: raw (with language), urlencoded, form-data (with files), file, GraphQL	The matching body type. A GraphQL body makes the request a GraphQL request.
Saved responses	Examples.
followRedirects: false and strictSSL: false	Follow redirects and Verify TLS certificates turned off in the request’s settings.

Form-data and binary file paths point at files on the machine that exported them; pick the files again on your Mac.

OpenAPI and Swagger specs

1. Import the spec (or drop the file onto the window).
2. The client creates a collection named after the spec’s info.title, with its description as docs, and adds the spec to Specs.
3. Set the collection’s baseUrl variable if the spec’s server URL isn’t the one you want to call.

Spec	In the collection
The first server, with its variables’ defaults filled in (OpenAPI), or the first scheme, host and basePath (Swagger)	The collection variable baseUrl. Without one, http://localhost.
Tags	One folder per tag, in the order the spec lists them. Operations go in their first tag’s folder; untagged ones at the top level.
Each operation	A request named after its summary (or operation ID, or method and path), with URL {{baseUrl}}/path.
Path parameters, {id}	:id path variables, with example values and descriptions.
Query and header parameters	Params and headers with example values. Required ones are switched on, optional ones off.
Request bodies	JSON bodies built from the spec’s example or schema; form and multipart bodies as form fields (binary properties become file fields).
Responses	One example per response code, with a body from the spec’s example or schema.
Security schemes	Collection auth from the first scheme, with credential variables.
deprecated: true	Docs that start with “Deprecated.”

Local $ref references (#/components/…) are followed. To keep a collection in step with a spec as the spec changes, use Sync Collection in Specs.

HAR files

Each request in the HAR becomes a saved request in a folder named after its host, with its response as an example. It’s the same conversion as saving captured requests. To get a HAR file from Cloak Proxy, see Export sessions.

HAR files contain credentials

HAR files include cookies, Authorization headers and tokens in bodies. After importing one, remove credentials from the requests before you commit the workspace or export the collection.

Insomnia exports

Insomnia v4 JSON exports become one collection per Insomnia workspace. Request groups become folders, and requests keep their method, URL, headers (disabled ones switched off), text body and description. Insomnia’s {{ _.name }} variables are rewritten to {{name}}, and Insomnia environments become environments.

Import a cURL command

Paste a curl command into the Import sheet, or straight into a request’s URL field.

A command copied from a browser's developer tools

curl 'https://api.example.com/v1/orders' \
  -H 'Authorization: Bearer {{token}}' \
  -H 'Content-Type: application/json' \
  --data-raw '{"sku":"A-100","qty":2}'

From the Import sheet, the client opens a new unsaved request named after the URL’s last path segment. Pasted into a URL field, it replaces that request’s method, URL, query params, headers and body. A JSON body becomes a Raw JSON body; any other body becomes TEXT.

Flags	Effect
-X, --request	Method. Without it, the method is POST when there’s a body, otherwise GET.
-H, --header	A header.
-d, --data, --data-raw, --data-binary, --data-ascii	Body data. Several are joined with &. Adds Content-Type: application/x-www-form-urlencoded if no type is set.
--data-urlencode	Body data, URL-encoded.
--json	Body data, plus Content-Type and Accept of application/json.
-F, --form	A multipart field. The fields are written into a raw body; @file parts become a <file> placeholder.
-u, --user	An Authorization: Basic header.
-A, --user-agent	A User-Agent header.
-e, --referer	A Referer header.
-b, --cookie	A Cookie header (when it contains =).
-I, --head	Method HEAD.
-G, --get	Moves the data into the query string and uses GET.
--url	The URL.

Flags that don’t change the request, such as -L, -k, --compressed, -s, -v, -o, -x and -m, are ignored. -d @file can’t read the file, so the body says <contents of file> for you to replace. A URL without a scheme gets http://.

For a form upload, switch the body to form-data after importing and choose the files.

Export

Export	Where	File
Postman Collection v2.1	Right-click a collection › Export › Postman Collection v2.1…, or More in the collection’s tab	<name>.postman_collection.json
OpenAPI 3.0 (YAML)	Export › OpenAPI 3.0 (YAML)…	<name>.openapi.yaml
API Documentation (HTML)	Export › API Documentation (HTML)…	<name> docs.html, opened in your browser. See Examples and docs.
Postman environment	Right-click an environment › Export…, or Export… in its tab	<name>.postman_environment.json

Postman Collection v2.1

The export keeps folders, requests, docs, auth (with inheritance), scripts, variables, headers (with disabled ones marked), every body type, path and query variables, examples as saved responses, and the Follow redirects and Verify TLS certificates settings. Postman, Newman and other tools that read Postman collections can open it.

OpenAPI 3.0

The client writes a spec from the collection:

• The baseUrl collection variable becomes the server.
• Each HTTP request becomes an operation. Its path is the URL without {{baseUrl}}, with :id turned into {id}.
• Operations are tagged with their top-level folder’s name.
• Request bodies get a JSON Schema inferred from their JSON.
• Saved examples become the documented responses.

Use it as a starting point for a real spec in Specs, where you can lint and edit it.

What exports leave out

• Secret variables are exported with empty values, in both collections and environments.
• Values in auth fields, headers, URLs and bodies are exported as typed. A token pasted into a Bearer Token field is in the file.

Check exports for credentials

Before you share an exported collection, search it for tokens and keys. Keep credentials in secret variables or the Vault so exports carry only {{token}} or {{vault:name}} references.

You can also export captured traffic, rather than a collection, as a Postman collection or OpenAPI spec from the proxy. See Export sessions.

Related

SpecsEdit, lint and sync OpenAPI specs.

Save captured requestsBring proxy traffic into the client.

Examples and docsBranded HTML documentation.

Export sessionsHAR, Postman and OpenAPI from captured traffic.