Migrate from Postman: import guide and limits

Still deciding? See Tetiva as a Postman alternative first, or download Tetiva and try the import on a real collection.

Moving over takes two actions: export your Postman collection as Collection v2.1, then import that file into Tetiva. Folder structure, requests, headers, bodies, auth, descriptions and saved responses come across, and environments come across as separate files. Scripts come across when you tick Import scripts during the import. Collection variables become an environment named after the collection. Anything tied to the Postman cloud does not come across, and the checklist below says exactly what to look at.

Step 1. Export from Postman#

1. In the collection menu choose Export and the Collection v2.1 format. Save the .json.
2. Export environments separately — one file per environment.

Format v2.0 is rejected: the import stops with unsupported schema, only Postman Collection v2.1 is supported. If someone handed you a file and you are not sure, open it and check info.schema — it must contain v2.1.

Step 2. Import into Tetiva#

• Into the sidebar root — the Import button above the collection tree → Import File….
• Inside an existing collection — right-click it and choose Import File…. The imported tree lands inside that collection.
• Pick the .json. A confirmation dialog opens first: how many folders, requests and examples the file holds, where the collection goes, the hosts its requests call, what changed on import, and the scripts in the file. Scripts come in only when you tick Import scripts. Click Import, and a toast such as Imported “Payments API”: 4 folders · 27 requests · 3 examples confirms it while the new collection opens in a tab.
• Environments — the environment selector in the request bar → Manage Environments… → the import button (tooltip Import a Postman or Hoppscotch environment). Import File… in the sidebar takes an environment file too.

The Postman collection itself becomes a normal Tetiva collection and its folders become nested collections. Nesting depth is not capped.

Tetiva

v1.3.1

Concept mapping#

What does not carry over#

Check these after the import#

Inherited auth. A request with no auth block of its own is imported with Inherit and, as in Postman, uses the auth of the folder or collection above it. An explicit noauth becomes No Auth. How the lookup walks up the tree is covered in Authentication.

Scripts. They come across only when Import scripts is ticked in the confirmation dialog. Tetiva implements part of the pm object, so unsupported pm.* calls need fixing by hand — see the table below.

Schemes with no equivalent. NTLM, Hawk and the rest arrive as No Auth, but not silently: a toast stays up after the import with a line per auth block, naming the collection, folder or request it came from and the reason. Walk that list and configure those requests again — see Authentication.

Files. A binary body and form-data file fields arrive without their files: pick the file again in the Body tab.

Environment variables. Variables disabled in Postman stay disabled. Collection variables go into an environment of their own, and their {{variables}} won't resolve until you pick it.

Secrets. Secret-typed variables stay secret in Tetiva, but the Postman export file holds their values in plain text — do not leave it in a shared folder.

Scripting: pm.* coverage#

Tetiva scripts run on the goja engine — JavaScript, but neither Node nor a browser. The pm object is implemented partially: tests built on pm.test and pm.expect usually run as is, while pm.sendRequest, pm.globals and require need replacing. The full reference lives in Scripting.

A typical Postman test runs unchanged:

pm.test("status is 200", function () {
    pm.response.to.have.status(200);
});
pm.environment.set("token", pm.response.json().access_token);

A test fails when an assertion fails or the function throws. A failed assertion shows just its message next to the test name in the Tests tab, as in Postman; any other error also names the line it broke on. A pre-request script that throws outside pm.test stops the send, as in Postman: the response pane says Request not sent with the error and its line. A failing post-response script keeps the tests that passed before it broke.

Exporting back to Postman#

The door swings both ways: right-click a collection and choose Export as Postman to write a v2.1 file named <collection>.postman_collection.json. Environments export from Manage Environments… with Export as Postman.

Scripts and response examples are exported. gRPC requests have no place in the Postman format, so they are skipped with a warning. A WebSocket request keeps its address and headers, but not its messages. More detail in Import and export.