N8n Package

Beta — breaking changes may still occur without major version bump.

Beta: Export workflows, folders, or projects as an n8n package

post

Beta — breaking changes may still occur without major version bump.

Export workflows and/or folders, or projects, as a gzipped tar archive (.n8np). Provide workflowIds/folderIds, or projectIds, but not both groups. Each exported folder includes its nested folders. Empty projects export project metadata only. The response is streamed as application/gzip with a Content-Disposition attachment header. Requires the n8n Packages feature to be licensed.

API key scopes: workflow:export is required when exporting workflows or folders, and project:export is required when exporting projects.

Authorizations

ApiKeyAuthBearerAuth

X-N8N-API-KEYstringRequired

Body

application/json

Selects what to export. Provide workflowIds and/or folderIds to export loose workflows and folders, or projectIds to export whole projects, but not both groups in the same request. At least one id must be supplied.

workflowIdsstring[] · max: 300Optional

IDs of the workflows to include in the exported package.

Example: ["2tUt1wbLX592XDdX"]

folderIdsstring[] · max: 300Optional

IDs of the folders to include in the exported package. Each folder is exported with its nested folders.

Example: ["9xKp2mNqRzAbCdEf"]

projectIdsstring[]Optional

IDs of the projects to include in the exported package.

Example: ["Ox8O54VQrmBrb4qL"]

Responses

200

A gzipped tar archive containing the exported package contents.

application/gzip

string · binaryOptional

400

The request is invalid or provides malformed data.

401

Unauthorized

403

Forbidden

404

The specified resource was not found.

post/n8n-packages/export

HTTPcURLJavaScriptPython

POST /api/v1/n8n-packages/export HTTP/1.1
X-N8N-API-KEY: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 103

{
  "workflowIds": [
    "2tUt1wbLX592XDdX"
  ],
  "folderIds": [
    "9xKp2mNqRzAbCdEf"
  ],
  "projectIds": [
    "Ox8O54VQrmBrb4qL"
  ]
}

binary

Beta: Import an n8n package into a project

post

Beta — breaking changes may still occur without major version bump.

Imports a gzip-compressed tar package (.n8np) into the target project. Send the archive as the multipart field package. Optional routing uses form fields projectId and folderId (omit or send empty for defaults). The optional credentialMatchingMode, credentialMissingMode, bindings, workflowIdPolicy, and workflowPublishingPolicy fields take their defaults when omitted. The required workflowConflictPolicy field controls what happens when a package workflow matches an existing workflow by source id in the target project. Maximum upload size is N8N_ENDPOINTS_PAYLOAD_SIZE_MAX MB (default 16).

The package must declare its manifest at manifest.json and include every file referenced by the manifest. The caller is authorised through the workflow:import scope. With the default workflowIdPolicy=new, newly created workflows receive a fresh local id; imported workflows arrive inactive unless workflowPublishingPolicy publishes them after import.

Credential references are resolved before any workflow is written. Credentials owned by, shared with, or global to the target project (with credential:read) match.

Authorizations

ApiKeyAuthBearerAuth

X-N8N-API-KEYstringRequired

Body

multipart/form-data

packagestring · binaryRequired

Gzip-compressed tar package (.n8np).

projectIdstringOptional

Target project id. Omit or send empty to import into the caller's personal project.

folderIdstringOptional

Optional folder within the target project. Omit or send empty for project root.

credentialMatchingModestring · enumOptional

How credential references in requirements.credentials are matched on the target instance. id-only (default) matches by id. name-and-type matches credentials with the exact same name and type. type-only matches any credential of the same type. For name-and-type and type-only, candidates are ranked by scope — a credential owned by the target project wins over one merely shared into it, which in turn wins over a global credential; if several candidates remain in the winning scope, the most recently updated one is chosen.

Default: id-onlyPossible values:

credentialMissingModestring · enumOptional

What to do when a credential reference cannot be resolved. create-stub (default) creates empty credential placeholders in the target project for missing references. must-preexist requires every referenced credential to already exist.

Default: create-stubPossible values:

bindingsstringOptional

Optional JSON object of explicit source→target id bindings, keyed by entity type. Only credentials is supported today: send {"credentials":{"<packageCredentialId>":"<targetCredentialId>"}} to map credential ids from the package to credential ids on the target instance. These explicit bindings are validated on type and applied before credentialMatchingMode resolution runs.

Default: {}

workflowConflictPolicystring · enumRequired

new-version updates matching workflows and creates a new version, fail rejects the import when any matching workflow exists, and skip leaves matching workflows unchanged.

Possible values:

workflowIdPolicystring · enumOptional

Controls the id each newly created workflow receives. new (default) mints a fresh id and records the package id as sourceWorkflowId, so the same package can be imported repeatedly without id collisions. source reuses the package's own workflow id on the target instance. Workflows matched to an existing workflow in the target project (status updated or skipped) always keep that workflow's current id, regardless of policy.

Default: newPossible values:

workflowPublishingPolicystring · enumOptional

Controls whether imported workflows are published after content is written. preserve-published-state keeps new workflows inactive and republishes an updated workflow only when it was already published and the package workflow is published too, so drafts are never published. match-source follows the package workflow's published flag. publish-all publishes every imported workflow. unpublish-all leaves new workflows inactive and unpublishes updated workflows that were published.

Default: preserve-published-statePossible values:

folderConflictPolicystring · enumOptional

Controls what happens when a package folder (matched by id in the target project) already exists at the same position. merge (default) reuses the existing folder as-is and merges the package's children into it; fail rejects the import. A folder whose id exists under a different parent, or belongs to another project, always blocks the import. Requires the folder:create scope and a license that supports folders when the package contains folders.

Default: mergePossible values:

Responses

200

Import succeeded; the listed workflows were written to the target project.

application/json

400

The request is invalid or provides malformed data.

401

Unauthorized

403

Forbidden

404

The specified resource was not found.

409

Import blocked by at least one conflict among the issues — a workflow source-id conflict or a folder conflict (id under a different parent, id owned by another project, or a fail-policy match).

application/json

422

Import blocked by non-conflict issues only (e.g. unresolved credentials).

application/json

post/n8n-packages/import

HTTPcURLJavaScriptPython

POST /api/v1/n8n-packages/import HTTP/1.1
X-N8N-API-KEY: YOUR_API_KEY
Content-Type: multipart/form-data
Accept: */*
Content-Length: 295

{
  "package": "binary",
  "projectId": "text",
  "folderId": "text",
  "credentialMatchingMode": "id-only",
  "credentialMissingMode": "create-stub",
  "bindings": "{}",
  "workflowConflictPolicy": "new-version",
  "workflowIdPolicy": "new",
  "workflowPublishingPolicy": "preserve-published-state",
  "folderConflictPolicy": "merge"
}

{
  "package": {
    "sourceN8nVersion": "text",
    "sourceId": "text",
    "exportedAt": "2026-07-19T15:42:05.657Z"
  },
  "workflows": [
    {
      "sourceWorkflowId": "text",
      "localId": "text",
      "name": "text",
      "projectId": "text",
      "parentFolderId": "text",
      "activeVersionId": "text",
      "publishing": {
        "state": "published",
        "error": "text",
        "blockedReason": "stub-credential",
        "skippedPublishReason": "stub-credential"
      },
      "status": "created"
    }
  ],
  "folders": [
    {
      "sourceFolderId": "text",
      "localId": "text",
      "name": "text",
      "parentFolderId": "text",
      "status": "created"
    }
  ],
  "projects": [
    {
      "sourceProjectId": "text",
      "localId": "text",
      "name": "text",
      "status": "created"
    }
  ],
  "credentials": {
    "matched": [
      "text"
    ],
    "stubbed": [
      "text"
    ]
  },
  "bindings": {
    "workflows": {
      "ANY_ADDITIONAL_PROPERTY": "text"
    },
    "credentials": {
      "ANY_ADDITIONAL_PROPERTY": "text"
    }
  }
}