n8n-nodes-zuuna

An n8n community node for Zuuna, a self-hosted Kanban and project
management tool. It lets an n8n workflow create and update cards, add comments, read boards,
columns and cards, and start when a Zuuna webhook fires.

What this talks to

This node is a client for Zuuna's /api/v1 HTTP API. By default it points at
https://app.zuuna.de, which is a hosted, commercial service run by Zuuna — using it means
sending your data to that service under its terms. You can instead point the Base URL at your
own host if you run a self-hosted Zuuna instance. Nothing about the node changes based on which you
pick; it is the same API either way.

Nodes

• Zuuna — actions:
  • Card → Create (POST /boards/{boardId}/cards)
  • Card → Update (PATCH /cards/{cardId})
  • Card → Add Comment (POST /cards/{cardId}/comments)
  • Card → Get (GET /cards/{cardId})
  • Card → Search (GET /groups/{groupId}/cards) — the API has no full-text search, so the
    node lists a group's cards with the server-side filters it does support (archived, placement,
    updated-since) and applies the optional Title Contains and Board ID filters client-side to
    the fetched rows.
  • Board → Get Many (GET /boards)
  • Board → Get Columns (GET /boards/{boardId}/columns)
• Zuuna Trigger — subscribes to Zuuna webhooks (POST /webhooks) and starts the workflow when a
  selected event fires (card created, moved, changed, and the git/CI/release/deploy events).

Board, column and group pickers are populated live from your account.

Credentials

Create an API token in Zuuna under Developer settings — it looks like zk_live_…. The
credential takes the token plus the Base URL of your instance. Give the token the scopes the
actions you use need (for example cards:write, comments:write, webhooks:manage). The
credential Test button calls GET /api/v1/me, which validates the token, the URL and your
plan's API access.

Webhooks need a plan that includes them

The Zuuna Trigger registers a webhook, and webhooks are a plan capability (Developer plans). If
your plan does not include them, activating the trigger fails with a clear
"This workspace's plan does not include the "webhooks" feature." error — it does not silently
receive nothing. Deliveries are verified against the X-Zuuna-Signature HMAC-SHA256 header by
default; you can turn that off in the node.

Rate limits

The API is rate-limited per workspace, and the limit depends on your plan. A workflow that creates
cards in a tight loop can hit HTTP 429; add a delay or a Split-In-Batches loop with a wait if you
process large sets.

Errors

Zuuna returns structured errors ({ "error": "<code>", "message": "<text>" }). The node passes both
through, so a failure reads e.g. "Zuuna: The column does not belong to this board." with the code
in the error's description, rather than a bare "Bad Request".

Install

This package has not been published to npm by its author. Publishing (and any n8n verification
submission) is the repository owner's step. To try it before then, build it and install it into your
n8n instance as a local community node:

npm install
npm run build      # tsc + copies the icons into dist/
npm run lint       # eslint-plugin-n8n-nodes-base

Then follow n8n's community node installation
docs to load the built package.

Compatibility

Built against n8n-workflow (peer dependency) and Node.js ≥ 20.15. License: MIT.