> For the complete documentation index, see [llms.txt](https://docs.n8n.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.n8n.io/connect/n8n-api/n8n-package.md).
# N8n Package
Beta — operations about n8n packages. Disabled by default; enable with `N8N_PUBLIC_API_PACKAGES_ENABLED=true`.
## Beta: Export workflows as an n8n package
> \*\*Beta — disabled by default.\*\* Set \`N8N\_PUBLIC\_API\_PACKAGES\_ENABLED=true\` on the\
> instance to enable this endpoint. While disabled, requests return \`404\`.\
> \
> Export one or more workflows as a gzipped tar archive (.n8np). The response is\
> streamed as \`application/gzip\` with a \`Content-Disposition\` attachment header.\
> Requires the n8n Packages feature to be licensed.
```json
{"openapi":"3.0.0","info":{"title":"n8n Public API","version":"1.1.1"},"tags":[{"name":"N8nPackage","description":"Beta — operations about n8n packages. Disabled by default; enable with `N8N_PUBLIC_API_PACKAGES_ENABLED=true`."}],"servers":[{"url":"/api/v1"}],"security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-N8N-API-KEY"},"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"exportWorkflowsRequest":{"type":"object","additionalProperties":false,"required":["workflowIds"],"properties":{"workflowIds":{"type":"array","minItems":1,"maxItems":300,"description":"IDs of the workflows to include in the exported package.","items":{"type":"string","minLength":1}}}}},"responses":{"badRequest":{"description":"The request is invalid or provides malformed data."},"unauthorized":{"description":"Unauthorized"},"forbidden":{"description":"Forbidden"},"notFound":{"description":"The specified resource was not found."}}},"paths":{"/n8n-packages/export":{"post":{"tags":["N8nPackage"],"summary":"Beta: Export workflows as an n8n package","description":"**Beta — disabled by default.** Set `N8N_PUBLIC_API_PACKAGES_ENABLED=true` on the\ninstance to enable this endpoint. While disabled, requests return `404`.\n\nExport one or more workflows as a gzipped tar archive (.n8np). The response is\nstreamed as `application/gzip` with a `Content-Disposition` attachment header.\nRequires the n8n Packages feature to be licensed.\n","requestBody":{"description":"Workflows to include in the exported package.","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/exportWorkflowsRequest"}}}},"responses":{"200":{"description":"A gzipped tar archive containing the exported workflows.","content":{"application/gzip":{"schema":{"type":"string","format":"binary"}}}},"400":{"$ref":"#/components/responses/badRequest"},"401":{"$ref":"#/components/responses/unauthorized"},"403":{"$ref":"#/components/responses/forbidden"},"404":{"$ref":"#/components/responses/notFound"}}}}}}
```
## Beta: Import an n8n package into a project
> \*\*Beta — disabled by default.\*\* Set \`N8N\_PUBLIC\_API\_PACKAGES\_ENABLED=true\` on the\
> instance to enable this endpoint. While disabled, requests return \`404\`.\
> \
> 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\`, \`credentialBindings\`,\
> \`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. Only credentials owned by the\
> target project (with \`credential:read\`) or global credentials (with \`credential:read\`)\
> match. Credentials shared into the project as \`credential:user\` are not matched.
```json
{"openapi":"3.0.0","info":{"title":"n8n Public API","version":"1.1.1"},"tags":[{"name":"N8nPackage","description":"Beta — operations about n8n packages. Disabled by default; enable with `N8N_PUBLIC_API_PACKAGES_ENABLED=true`."}],"servers":[{"url":"/api/v1"}],"security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-N8N-API-KEY"},"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"responses":{"badRequest":{"description":"The request is invalid or provides malformed data."},"unauthorized":{"description":"Unauthorized"},"forbidden":{"description":"Forbidden"},"notFound":{"description":"The specified resource was not found."}},"schemas":{"importBlockingIssue":{"oneOf":[{"type":"object","description":"A workflow whose source id already matches one in the target project, under the `fail` conflict policy.\n","required":["type","sourceWorkflowId","existingWorkflowId","name"],"properties":{"type":{"type":"string","enum":["workflow-conflict"]},"sourceWorkflowId":{"type":"string"},"existingWorkflowId":{"type":"string"},"name":{"type":"string"}}},{"type":"object","description":"A `source`-policy workflow whose id is already taken on the instance. Workflow ids are globally unique, so the id cannot be created in the target project. The existing workflow may live in any project — including the target project itself — and may be archived (archived workflows keep their id but are never matched for updates).\n","required":["type","sourceWorkflowId","existingWorkflowId","existingProjectId","isArchived","name"],"properties":{"type":{"type":"string","enum":["workflow-id-conflict"]},"sourceWorkflowId":{"type":"string"},"existingWorkflowId":{"type":"string"},"existingProjectId":{"type":"string","nullable":true,"description":"Project that owns the existing workflow, or null when no owning project could be determined.\n"},"isArchived":{"type":"boolean","description":"Whether the existing workflow is archived."},"name":{"type":"string"}}},{"type":"object","description":"A workflow whose source id already matches one in the target project but lives outside the requested import folder. Folder-targeted imports cannot update workflows in place at a different location.\n","required":["type","sourceWorkflowId","existingWorkflowId","existingParentFolderId","targetFolderId","name"],"properties":{"type":{"type":"string","enum":["workflow-folder-conflict"]},"sourceWorkflowId":{"type":"string"},"existingWorkflowId":{"type":"string"},"existingParentFolderId":{"type":"string","nullable":true,"description":"Folder that currently contains the matched workflow, or null when it lives at the project root.\n"},"targetFolderId":{"type":"string","description":"Folder the import was requested to land in."},"name":{"type":"string"}}},{"type":"object","description":"A credential reference that could not be resolved in the target project.","required":["type","kind","sourceId","usedByWorkflows"],"properties":{"type":{"type":"string","enum":["credential-unresolved"]},"kind":{"type":"string","enum":["not_found","unknown_type","source_not_found","type_mismatch"]},"sourceId":{"type":"string"},"targetId":{"type":"string","description":"Target credential id for an explicit credential binding."},"expectedType":{"type":"string","description":"For `type_mismatch`: the credential type the package's workflow node requires.\n"},"actualType":{"type":"string","description":"For `type_mismatch`: the actual type of the resolved target credential.\n"},"usedByWorkflows":{"type":"array","items":{"type":"string"}}}}]}}},"paths":{"/n8n-packages/import":{"post":{"tags":["N8nPackage"],"summary":"Beta: Import an n8n package into a project","description":"**Beta — disabled by default.** Set `N8N_PUBLIC_API_PACKAGES_ENABLED=true` on the\ninstance to enable this endpoint. While disabled, requests return `404`.\n\nImports a gzip-compressed tar package (`.n8np`) into the target project. Send the\narchive as the multipart field `package`. Optional routing uses form fields\n`projectId` and `folderId` (omit or send empty for defaults). The optional\n`credentialMatchingMode`, `credentialMissingMode`, `credentialBindings`,\n`workflowIdPolicy`, and `workflowPublishingPolicy` fields take their defaults when omitted. The required\n`workflowConflictPolicy` field controls what happens when a package workflow\nmatches an existing workflow by source id in the target project. Maximum upload\nsize is `N8N_ENDPOINTS_PAYLOAD_SIZE_MAX` MB (default 16).\n\nThe package must declare its manifest at `manifest.json` and include every file\nreferenced by the manifest. The caller is authorised through the `workflow:import`\nscope. With the default `workflowIdPolicy=new`, newly created workflows receive a\nfresh local id; imported workflows arrive inactive unless `workflowPublishingPolicy`\npublishes them after import.\n\nCredential references are resolved before any workflow is written. Only credentials owned by the\ntarget project (with `credential:read`) or global credentials (with `credential:read`)\nmatch. Credentials shared into the project as `credential:user` are not matched.\n","requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["package","workflowConflictPolicy"],"properties":{"package":{"type":"string","format":"binary","description":"Gzip-compressed tar package (`.n8np`)."},"projectId":{"type":"string","description":"Target project id. Omit or send empty to import into the caller's personal project.\n"},"folderId":{"type":"string","description":"Optional folder within the target project. Omit or send empty for project root.\n"},"credentialMatchingMode":{"type":"string","enum":["id-only"],"default":"id-only","description":"How credential references in `requirements.credentials` are matched on the target instance. Only `id-only` is supported today.\n"},"credentialMissingMode":{"type":"string","enum":["must-preexist","create-stub"],"default":"create-stub","description":"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.\n"},"credentialBindings":{"type":"string","default":"{}","description":"Optional JSON object mapping credential ids from the package manifest to credential ids on the target instance. These explicit bindings are validated and applied before `credentialMatchingMode` resolution runs.\n"},"workflowConflictPolicy":{"type":"string","enum":["new-version","fail","skip"],"description":"`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.\n"},"workflowIdPolicy":{"type":"string","enum":["new","source"],"default":"new","description":"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.\n"},"workflowPublishingPolicy":{"type":"string","enum":["preserve-published-state","match-source","publish-all","unpublish-all"],"default":"preserve-published-state","description":"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.\n"}}}}}},"responses":{"200":{"description":"Import succeeded; the listed workflows were written to the target project.","content":{"application/json":{"schema":{"type":"object","required":["package","workflows","bindings","credentials"],"properties":{"package":{"type":"object","required":["sourceN8nVersion","sourceId","exportedAt"],"properties":{"sourceN8nVersion":{"type":"string"},"sourceId":{"type":"string"},"exportedAt":{"type":"string","format":"date-time"}}},"workflows":{"type":"array","items":{"type":"object","required":["sourceWorkflowId","localId","name","projectId","parentFolderId","activeVersionId","publishing","status"],"properties":{"sourceWorkflowId":{"type":"string","description":"Workflow id as it appeared in the package."},"localId":{"type":"string","description":"Workflow id on the target instance: newly assigned for `created` (fresh under `workflowIdPolicy=new`, the package id under `source`), the existing workflow's id for `updated`/`skipped`.\n"},"name":{"type":"string"},"projectId":{"type":"string"},"parentFolderId":{"type":"string","nullable":true},"activeVersionId":{"type":"string","nullable":true,"description":"Published version on the target instance, if any. `null` when the workflow is not published after import.\n"},"publishing":{"type":"object","required":["state"],"description":"Outcome of applying the selected publishing policy to this workflow.\n","properties":{"state":{"type":"string","enum":["published","unpublished","unchanged","blocked","failed"],"description":"`blocked` means the imported version could not be published and no version is active (for example because the workflow uses a stubbed credential). When a prior published version remains active, `state` is `unchanged` with `skippedPublishReason` instead. `failed` means publish or unpublish was attempted but did not succeed.\n"},"error":{"type":"string","description":"Present when `state` is `failed`. Explains why publish or unpublish could not be applied.\n"},"blockedReason":{"type":"string","enum":["stub-credential"],"description":"Present when `state` is `blocked`: the imported version could not be published and no version is active.\n"},"skippedPublishReason":{"type":"string","enum":["stub-credential"],"description":"Present when `state` is `unchanged` but the policy wanted to publish the imported version: a prior published version is still active (for example after an update with stubbed credentials).\n"}}},"status":{"type":"string","enum":["created","updated","skipped"],"description":"Import outcome for this package workflow."}}}},"credentials":{"type":"object","description":"Source credential ids grouped by whether they matched an existing credential or were created as stubs. Full source→target id mapping is in `bindings.credentials`.\n","required":["matched","stubbed"],"properties":{"matched":{"type":"array","items":{"type":"string"},"description":"Source credential ids from the package that matched existing credentials on the target instance.\n"},"stubbed":{"type":"array","items":{"type":"string"},"description":"Source credential ids for which empty placeholder credentials were created in the target project.\n"}}},"bindings":{"type":"object","description":"Source id → target id mappings produced during import, one map per entity type. Each value maps an id as it appeared in the package to the id on the target instance.\n","required":["workflows","credentials"],"properties":{"workflows":{"type":"object","additionalProperties":{"type":"string"}},"credentials":{"type":"object","description":"Credential id from `requirements.credentials` in the package manifest → matched credential id on the target instance.\n","additionalProperties":{"type":"string"}}}}}}}}},"400":{"$ref":"#/components/responses/badRequest"},"401":{"$ref":"#/components/responses/unauthorized"},"403":{"$ref":"#/components/responses/forbidden"},"404":{"$ref":"#/components/responses/notFound"},"409":{"description":"Import blocked, with at least one workflow source-id conflict among the issues.\n","content":{"application/json":{"schema":{"type":"object","required":["message","issues"],"properties":{"message":{"type":"string"},"issues":{"type":"array","items":{"$ref":"#/components/schemas/importBlockingIssue"}}}}}}},"422":{"description":"Import blocked by non-conflict issues only (e.g. unresolved credentials).\n","content":{"application/json":{"schema":{"type":"object","required":["message","issues"],"properties":{"message":{"type":"string"},"issues":{"type":"array","items":{"$ref":"#/components/schemas/importBlockingIssue"}}}}}}}}}}}}
```
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://docs.n8n.io/connect/n8n-api/n8n-package.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.