# API Specs

> Import an OpenAPI or Swagger document so a workflow step can call one of its operations with typed parameters.

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](/help/credentials-connections/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](/help/workflows/configure-and-test-steps).

**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](/help/workflows/step-types) for what else a step can do, or
[Naming, reuse, rotation, and
deletion](/help/credentials-connections/lifecycle).