Import an OpenAPI specification

An existing OpenAPI specification can supply endpoint cards for a canvas. You could import booking and dispatch tags into separate documents, then attach them to API objects.

Analyzing a specification requires docs:read; importing and reimporting require docs:write.

Import the specification

On Home or a space's page, select Import API.
Choose Paste, File or URL. Supply JSON or YAML in OpenAPI 3.0, OpenAPI 3.1 or Swagger 2.0 format. A URL must be publicly accessible; paste or upload a specification from a private source.
Select Analyze. This reads the specification and shows its tags and operation counts without creating documents.

Analyzed Lanefold Shipper API specification with Carriers and Loads tags, operation counts and import destination controls.

Select the tags to import. Choose a Space and, if needed, a Folder. Use Drafts (no space) to leave the documents unfiled.
If you want the documents attached to objects, select Also create an API object for each tag. Leave it off to keep them in the normal document list.
Select Import. Open a document under Created documents, and check any Warnings or Skipped tags before selecting Done.

The import creates one document per selected tag. An operation with several tags goes into its first tag's document; an untagged operation goes into default. Each operation becomes an editable REST endpoint card. The import doesn't draw dependency arrows between endpoints.

With the object option selected, a new API object's document fills its API spec slot. If an object with the generated name already exists in the organization, the import reuses it, whatever its kind or space. If its slot is already filled, the document is attached as a custom doc and the result includes a warning. For API objects, open attached documents from the object's Docs tab, as described in Object kinds and doc slots.

Limits and mapping gaps

The specification size limit is 5 MB (5,242,880 bytes). Each import can contain up to 200 selected operations, with at most 150 in any tag's document. Select fewer tags if the total is too large. If a single tag exceeds the per-document limit, split that tag in the source specification before importing it.

Imports also count toward your organization's document quota. If the quota stops an import partway through, the documents already created stay available and the remaining tags appear under Skipped tags.

The cards contain a view of the contract, not a full copy of the specification. Request bodies use a short schema label; responses show status codes and descriptions, with schema names when available. Check the warnings for details the cards can't represent or references the import could not resolve. Editing these cards doesn't write changes back to your OpenAPI specification.

Reimport a changed specification

Reimport updates an imported document in place. Run it when the source contract changes; storing a source URL doesn't schedule updates.

Open the imported document's three-dot menu and select Re-import spec.
Choose Re-fetch stored URL if the original import used a URL, or Paste updated specification to supply the new JSON or YAML. File and paste imports need the specification pasted again.
Select Preview changes. Review Added, Changed, Removed and Unchanged before applying anything.
Leave Recompute the layout off to keep matching cards at the positions saved in the document's YAML. Positions you changed only on the canvas are lost on reimport. Turn it on to recalculate the layout.
Select Apply. When there are removals, the button includes the removal count. Removed operations disappear from the document.

Reimport updates only the tag the document was created from. To add a new tag, run a new import. If the original tag has been renamed or removed from the specification, reimport reports that it can't find the tag.