Importing OpenAPI
Build an API and the tools behind it from a document you already have, and re-import to pick up upstream changes.
If the service you want to expose already has an OpenAPI document, you do not have to declare its operations by hand. An import reads the document and creates, for each operation it can expose:
- a tool that calls the upstream operation through a connection, and
- an API operation pointing at that tool, with its method, path and inputs mapped over.
What you get is an ordinary draft API and ordinary tools. Nothing about them is special afterwards, and you can edit either.
Importing
Go to API Endpoints and choose Import OpenAPI. You need two things:
| Input | Notes |
|---|---|
| Connection | How the tools reach the upstream service: its base URL and credentials. |
| The document | YAML or JSON. |
Then a name, a URL slug and a contract version for the API, exactly as if you were creating one by hand.
Preview first
The dialog previews before it writes anything. The preview tells you:
- Which operations can be exposed, and which are skipped with the reason. A document usually contains some that cannot be mapped.
- Which tools already exist under the aliases this document would use.
- Which of those have unpublished edits a re-import would publish over, by name.
- Which API already serves this URL, and what re-importing would do to it.
Nothing is created until you confirm, and a refusal at any point leaves nothing behind. That matters more than it sounds: a failure halfway through would leave some tools updated, some not, and no record of where it stopped.
Aliases, and why re-importing works
Each operation gets a stable alias derived from the document and the connection. The alias is how a re-import finds the tool it created last time instead of making a second copy.
This is why importing the same document twice updates rather than duplicates. Two operations can never share an alias; if they ever did, both would resolve to one tool and the import would report every operation as fine while silently mis-wiring them, so the import refuses outright rather than risk it.
Re-importing
Point the same document, or an updated one, at the same slug and contract version. Because the URL is already claimed, the import has to be told explicitly that an update is what you meant:
| Situation | What happens |
|---|---|
| The URL is claimed and you have not asked for an update | 409, with the reconciliation so you can see what it would do. |
| You confirm the update | The existing API's draft is rewritten. |
| Some tools have unpublished edits | Refused, naming them, unless you confirm replacing them. |
The refusals are there because both mistakes are easy to make. Re-importing is the point of all this, but so is the author who meant to create a new API and typed a slug that is already in use.
Reconciliation
The preview groups the document's operations against what the API currently has:
| Group | Meaning |
|---|---|
| Added | In the document, not in the API. Will be created. |
| Updated | In both. The API's operation is rewritten from the document. |
| Removed | In the API, not in the document. Will be dropped from the draft. |
Read the removed group before confirming. It is how an upstream operation that has been retired disappears, and also how a document you exported from the wrong environment deletes half your contract.
A re-import writes the draft, never a published revision. Callers keep reaching the published contract until you have read the diff and published it yourself. That is what makes dropping an operation acceptable rather than alarming.
What an import does not do
- It does not publish. You review the draft and publish it.
- It does not grant anything. No key can call the new API until you add a grant.
- It does not preserve hand edits to an updated operation. An operation in the updated group is rewritten from the document. If you have tuned its inputs, safety or transform by hand, re-importing will undo that.
That last one is the practical cost of re-importing, and the reason to keep hand-written refinements in the tool where a re-import updates the definition around them, rather than in the API operation that gets rewritten.