Import & Export

Routebase is not a place your API contract gets locked into. An OpenAPI file goes in, an OpenAPI file comes out, and the same is true for Postman and Insomnia collections on the way in. This page covers both directions.

Importing

Where to import

There are two entry points, and they do not accept the same formats:

Entry point	Where	Accepts
Import OpenAPI	The dashboard, and the project list	OpenAPI only
Import in the specification wizard	Inside a project, when you create a specification	OpenAPI, Postman Collection, Insomnia Export

The dashboard route creates the project, the specification, and the environments in one go — the fastest path when you are starting from an existing file. If you are holding a Postman or Insomnia export, take the second route: create the project first, then import the collection through the specification wizard.

Both accept .yaml, .yml, and .json.

The import preview

Before anything is created, Routebase validates the file and shows you what it found: how many endpoints, folders, and schemas — split into schemas it could link and schemas that stay inline — plus the reusable components it recognized (responses, request bodies, parameters, security schemes). Warnings appear here too rather than after the fact.

Read the preview before you confirm. It is the cheapest moment to notice that a file contains half of what you expected.

Import options

Option	Default	What it does
Convert to OpenAPI 3.1	off	Only offered for OpenAPI 3.0 files. Upgrades nullable syntax and exclusive min/max to the 3.1 form.
Organize endpoints by tags	on	Creates folders from the OpenAPI tags and groups endpoints into them. For a Postman collection it follows the folder structure instead; for an Insomnia export, the request groups.
Shorten schema names	off	Keeps only the last dot-segment of a schema name — Foo.Bar.Response becomes Response — and only where the short name stays unique within the spec.

Turning on Shorten schema names reveals a follow-up choice that matters more than it looks, especially for specs generated from .NET or Java:

• Keep original names internally — the full namespaced names are stored alongside the short ones. Take this if you will re-import the file or diff against it later.
• Discard namespaces permanently — the original names are not kept. Later comparisons against the source file will report every schema as renamed.

Importing from Postman or Insomnia

Collections describe requests, not contracts. There is no schema in a Postman collection — only example bodies. Routebase therefore infers schemas from the examples it finds and says so plainly: "Schemas were inferred from example data and may be incomplete."

Treat an inferred schema as a first draft. A field that happened to be null in the example will be typed from that, and a field absent from the example does not exist at all. The import gets you a structured starting point in minutes; the contract is still yours to finish.

When validation fails

You do not have to leave and re-upload. The wizard shows a Validation failed — N errors panel listing every error — "Edit the content below and re-validate. Click an error to jump to its location." — above an inline editor with the offending lines highlighted. Fix the file in place and click Re-validate.

When the failure is a recognizable class, a one-click fix appears. The common one: a spec that declares OpenAPI 3.0 but uses 3.1-only keywords. Routebase offers "This looks fixable automatically" with a Retry as OpenAPI 3.1 button instead of making you find every occurrence by hand.

Exporting

Every frozen version can be downloaded in four formats:

Format	Use
YAML	The usual OpenAPI form — readable in review, friendly to version control.
JSON	The same document for tools that prefer JSON.
Postman	A collection your consumers can open and call straight away.
Insomnia	The same, for Insomnia.

Exports need a frozen snapshot. The download buttons appear once a version is actually frozen — a promotion into an environment that does not freeze leaves the version a draft, and a draft has no snapshot to export. This is deliberate: an export is a copy of a contract, and a contract that can still change underneath the file you handed out is not one.

You reach the exports from the release receipt of the Release Version wizard, and from the version itself afterwards.

What travels with the export

The export is a complete OpenAPI document, not a Routebase-flavored one. Tag descriptions, enum labels and per-value descriptions (x-enumNames, x-enumDescriptions), deprecation metadata and your reusable components are all in the file — so a generator on the other side produces the same names and the same documentation your portal shows.

Permissions

Importing creates a specification and requires specs:write, included in the Member role. Exporting requires specs:read.

Related

• API Design Settings — the specification wizard and per-spec settings
• Versioning — freezing a version, which is what makes it exportable
• Endpoints — what you work with after the import
• Schemas — including enum labels and how they export
• Getting Started — the path from an existing file to a first project