How to Maintain an n8n Node When an API Changes

When a SaaS API changes, update the node in four places: the request behavior, the n8n fields users see, the release metadata, and the instructions that explain the change. Then test an existing workflow and a new workflow against the exact package you plan to publish. A version bump by itself does not show that the node still reaches the right endpoint.

There are two version numbers to keep separate. The npm package version tells users which released artifact they install. The n8n node version controls how n8n loads node behavior inside workflows. n8n's versioning documentation says a saved workflow can continue using an older node version after a newer one is published, while a new workflow loads the latest version. That behavior gives you a way to introduce a breaking node change without silently rewriting every saved workflow.

Start with the change, not the release command

Record the API change before touching package.json. Save the provider's changelog, migration note, or updated reference, then map the change to the node:

API change	Node areas to inspect
Endpoint or host changed	Base URL, paths, request helpers, examples, and environment-specific settings
Authentication changed	Credential type, scopes, headers, OAuth flow, credential test, and setup instructions
Required field changed	Node property, validation, placeholder, description, example workflow, and error handling
Response shape changed	Output mapping, pagination, expressions in examples, and any simplified fields
Operation removed or renamed	Action labels, old workflow behavior, migration message, and release notes
Rate or quota rules changed	Polling interval, retries, backoff, error text, and customer guidance

If the provider has not documented the change, reproduce the failure with a redacted request and keep the observation separate from the provider's explanation. A 401 could mean an expired token, a missing scope, a wrong host, or a changed authentication contract. Do not turn one error into a universal API claim.

A real release shows why version numbers are not evidence

The public TidyCal node gives a small but useful release example. The repository published version 1.0.1 on 15 October 2026. The GitHub comparison between the pre-release package commit and the v1.0.1 commit lists changes to package.json, package-lock.json, and LICENSE; it does not show a node source change in that comparison.

The published package still had a larger problem to investigate. Its README said no credentials were required, while TidyCal's API documentation says API access requires a paid plan and authenticated requests. The compiled node also declared no credential and used a placeholder API destination in the prior package inspection. The evidence supports a narrow conclusion: publishing 1.0.1 changed release metadata, but it did not demonstrate an authentication repair or a working API request.

That is the maintenance check to carry into your own project. Ask what changed in the released files, then ask whether the release proves the API behavior users depend on. A patch number, provenance statement, or clean publish job cannot answer the second question.

Decide whether existing workflows need protection

Classify the change by its effect on saved workflows:

1. Same behavior, safer internals. Keep the n8n node version and update the package after tests pass. Document the fix if users need to know about it.
2. New optional behavior. Add the field or operation in a backward-compatible way. Test an old workflow and a new workflow with the new option.
3. Changed request or response contract. Decide whether old workflows can keep their behavior. If they cannot, add a new n8n node version or a migration path instead of changing the meaning of an existing field under the same version.
4. Removed API operation. Keep the old operation only if the provider still supports it, mark it clearly as deprecated, or provide a documented migration. Do not leave a visible action that always fails.

n8n's full node versioning is unavailable for declarative-style nodes. Light versioning is available to all node types, while a full versioned node uses programmatic structures. The NativeShip node-versioning guide covers the technical route; use the current n8n documentation when the change affects an existing node.

Keep the package version and node version in the release record. They answer different support questions: “Which npm artifact did you install?” and “Which behavior does this saved workflow load?”

Reproduce the old path before writing the fix

Make a small test matrix before changing the node:

Test	Why it matters
Existing workflow with the old node version	Shows whether saved workflows keep their previous behavior
New workflow with the latest node version	Shows the fields and defaults a new user receives
Read operation with a test account	Checks host, credential, request parameters, and response mapping
Write or update operation, if supported	Checks side effects and idempotency with controlled test data
Expected failure	Checks that the node surfaces a useful error when the API rejects input
Documentation path	Confirms the README and node help describe the same credential and fields

Record the n8n version, package version, node version, API account or environment, request type, redacted input, response status, and result. If you cannot run the old package because the provider removed the old endpoint, say that in the release record. Do not fill the gap with a guessed success.

For an OpenAPI-driven node, compare the updated specification with the generated operation list, then inspect manual edits and credentials. Reimporting a specification can change labels, paths, or fields without proving that the final package works. The NativeShip OpenAPI workflow guide is the useful starting point for that review.

Choose the npm release deliberately

npm recommends semantic versioning so users can understand the scope of a package update: a patch for backward-compatible fixes, a minor release for backward-compatible features, and a major release for breaking changes. Treat that as a communication contract, then check the actual n8n workflow effect. A change that looks small in package.json can still break a field, credential, or response expression.

Before publishing, review the staged package and confirm:

• the package points to the expected compiled node and credential files;
• the README names the same operations and authentication that the package exposes;
• the repository and release metadata identify the intended source;
• the example workflow uses fields present in the released node;
• the package version and changelog describe the user-visible impact;
• the build, lint, and relevant workflow tests ran against the same release candidate.

Publish through a GitHub Actions workflow with npm provenance, as described in the NativeShip publishing guide. n8n required this for verified nodes first, and from May 1, 2026 it applies to all community nodes, so a maintainer publishing a quick fix from a laptop is no longer an option. Publishing a package does not make it verified or prove that its API calls work.

n8n changes need maintenance too

The provider API is not the only thing that moves. n8n's own releases can break a node that has not changed. n8n 3.0 is a current example (see the v3.0 breaking changes):

n8n 3.0 change	What to check in your node
N8N_UNVERIFIED_PACKAGES_ENABLED defaults to false	Unverified packages stop loading on upgraded self-hosted instances. Plan verification or tell users how to allow the package.
defaults.color removed from node descriptions	Remove it, and make sure the icon works in light and dark themes
$getPairedItem removed	Update README examples and templates to $('Node').item or .itemMatching()
n8n-node dev runs n8n in a container	Install Docker or Podman, or use --external-n8n with N8N_DEV_RELOAD=true

Add the n8n version you tested to the release record so users know which n8n line a package supports. The generated-node testing guide covers the checks to repeat after an upgrade.

Write the migration note before you announce the fix

A useful release note gives users four pieces of information:

1. What changed in the provider API.
2. Which node versions or operations are affected.
3. What a user must change in an existing workflow, if anything.
4. How you tested the replacement path and where to report a failure.

Put the same note in the README's version history; the README checklist shows where it belongs. If no workflow change is required, say why. If the new version changes an output field or credential, show the old and new names and a short migration step. If you only inspected metadata and have not run an authenticated request, say that. A precise limitation is more useful than a confident release announcement that leaves users to discover the failure.

After release, watch support reports for the first affected action. Ask for the package version, n8n version, deployment type, resource and operation, and a redacted error. Compare the report with the test matrix before deciding whether to patch the package, add a new node version, or correct the documentation.

If API changes keep arriving faster than the team can test them, revisit whether the integration has a clear owner and maintenance budget. The SaaS integration decision guide helps frame that ownership decision before you promise a long-lived node to customers.