Migrate your API specifications from the API Builder to Spec Hub

You can migrate your existing API Builder objects to Postman’s Spec Hub and collections. Spec Hub supports API-first development with features like reusable components, live documentation preview, and structured outline navigation. It also offers native autocompletion and syntax checking to help reduce errors as you work.

Spec Hub can generate collections from your specifications (and specifications from collections), enabling you to create mock servers and monitor your API. As you update your API, you can manually keep them in sync. You can also import a specification from your computer or a repository to continue building it out in Spec Hub.

Spec Hub supports OpenAPI, AsyncAPI, protobuf, and GraphQL specifications.

Supported API Builder definitions

You can migrate OpenAPI, AsyncAPI, protobuf, and GraphQL specifications from the API Builder to Spec Hub.

Migration doesn’t support OpenAPI 1.0, RAML, or WASDL formats.

Migrate from API Builder to Spec Hub

To migrate your API Builder definitions and collections to Spec Hub, do the following:

1. In the sidebar, click Items and expand APIs, then select the definition that you want to migrate.

2. Click View more actions > Migrate to Spec Hub. Or click Migrate to Spec Hub in the upgrade notice located in the workbench. The Select Workspace to Move API window will appear.

3. In the Select Workspace to Move API window, choose whether to create a new workspace or migrate your definition into an existing workspace:

   • In the Create a new Workspace text box, enter a name for the new workspace.
   • Click select an existing workspace to select an existing workspace. Then, select a workspace from the dropdown list.

4. Click Migrate to Spec Hub to finish.

After the migration completes, you’ll receive an in-app notification. Click Check Workspace or Go to Workspace to navigate to your migrated Spec Hub specification.

If the migrated API was associated with a collection in the API Builder, the collection is also migrated to the same workspace.

Migrate from Git-linked API Builder to Spec Hub

Git-linked API Builder definitions are definitions connected to a remote repository. They use Git-based version control for developing and managing changes to your definition. The remote repository can be hosted in the cloud or on-premises.

To migrate a Git-linked API from API Builder to Spec Hub, do the following:

1. In the sidebar, click Items and expand APIs, then select the Git-linked API that you want to migrate.

2. Click View more actions > Migrate to Spec Hub. Or click Migrate to Spec Hub in the upgrade notice located in the workbench. The Select Workspace to Move API window will appear.

3. In the Select Workspace to Move API window, enter the new workspace’s name in the Create a new Workspace text box.

   Only one Git-linked API can be linked to a workspace.

4. (Optional) In the Directory path text box, enter the directory path with the API specification and collection in the repository. This is recommended for repositories with multiple APIs connected to the same repository.

5. Click Migrate to Spec Hub. This clones the Git repository locally so that you can access the specification and its related resources in the created workspace.

6. After the migration completes, you’ll receive an in-app notification. Click Check Workspace or Go to Workspace to navigate to your migrated Spec Hub specification.

7. Click Files in the bottom of the sidebar. You can then choose to:

   • Click Clone repo to clone the repository.
   • Click Open local folder to access your local files.

If the migrated API was associated with a collection in the API Builder, the collection is also migrated to the same workspace.