An API Spec is the product label for an imported OpenAPI or Swagger document. It describes what operations an API exposes; it holds no credentials by itself. Attach a connector and it borrows those.
Outcome
An API Request step calls a documented operation with its parameters typed and its response shape already known, instead of a hand-written URL.
1. Import the document
Connectors → API Specs → Import Spec takes a .json, .yaml, or .yml
file up to 5 MB, by drop or by browse.
It parses immediately and shows what it found — the document's title, version, and every operation with its method, path, and summary — before you save.
Give it a Name, and optionally a Connector. The connector supplies the base URL and the authentication used when a bound operation actually runs, so an HTTP connector pointing at the same API is usually what you want. See Outbound connectors.
Checkpoint: the spec is listed with its operation count.
2. Bind a step to an operation
Add an API Request step in the builder. Its inspector asks for an API Spec, then an Operation — listed as method and path, with the operation's summary beneath.
Choosing one populates typed Path parameters, Query parameters, and
Header parameters sections, each field marked required or optional and
labelled with its type, plus a Request body box that accepts {{field}}
template variables from upstream steps.
There is no URL or method to edit. Both come from the operation.
Checkpoint: the Output schema section lists the fields the operation's documented response will make available to the steps below — no test needed.
3. Replace a spec when the API changes
Re-upload on a spec's page compares the new document against the old one before committing anything.
Review spec changes counts what was added, changed, removed, and left alone, and names how many workflow steps across how many workflows are affected. Continue & overwrite applies it.
Bound workflows then show as stale until their sources are re-sampled — see Configure and test a step.
Checkpoint: the affected workflows show the drift banner, and re-sampling clears it.
Common problems
The import was rejected. The file must be a valid OpenAPI or Swagger
document under 5 MB, with a .json, .yaml, or .yml extension.
Operations run but come back unauthorised. The spec has no connector attached, or the attached connector's credentials are wrong. The spec describes the call; the connector authenticates it.
An operation is missing from the picker. It was not in the document you uploaded. Re-upload a newer version and review the changes.
Deleting the spec is refused. Workflow steps are still bound to it. Reassign or delete those steps first.
A bound step went stale after a re-upload. That is the drift gate doing its job: the operation's shape changed, so mappings that used its fields need checking. Re-sample the source and confirm the mappings.
Next step
Step types for what else a step can do, or Naming, reuse, rotation, and deletion.