Description

n8n-nodes-busabase

An n8n community node for Busabase. It reads and writes the whole workspace: Bases and records, docs, folders, skill/drive/AirApp files, playbooks (skills and custom prompts) and full-text search. It also has an instant trigger that starts a workflow when a record is created or updated, using Busabase’s own webhook push instead of polling.

npm install n8n-nodes-busabase

Then add it under Settings → Community Nodes in your n8n instance, or install it locally for self-hosted n8n. Requires n8n’s community-node API version 1 (n8n-workflow peer dependency). The package has no runtime dependencies.

Credential

Add a Busabase API credential:

| Field | |
| — | — |
| Base URL | Your server or Busabase Cloud (default https://busabase.com). A pasted /api/v1 is stripped. |
| API Key | A Busabase API key (a Bearer token). Not needed for a local, unauthenticated open-source server. |
| Space ID | Busabase Cloud only, when the key can reach more than one space. Leave empty otherwise. |

The key is only ever sent by n8n’s credential system. The node does not read BUSABASE* environment variables, so a BUSABASEAPIKEY or BUSABASESPACE_ID set on the n8n host cannot leak into requests made with a different credential. That matters because busabase-sdk‘s client does fall back to those variables, and this node deliberately does not run the SDK client (see “How it is built”).

Busabase’s OAuth (PKCE, no client secret, a non-standard resource parameter, and a shared client that only accepts loopback redirect URIs) does not map onto n8n’s generic OAuth2 credential without dynamic client registration glue, so there is no OAuth credential yet.

Busabase node

Every operation of the Busabase node, the Busabase API call(s) behind it, and what it outputs:

| Resource | Operation | Busabase API (SDK procedure) | Output |
| — | — | — | — |
| Base | List | bases.list | One item per Base: id, slug, name, fields (slug, name, type, choices) |
| Base | Get | bases.get | The Base with its fields |
| Record | List | records.list (cursor paging) | One item per record |
| Record | Find by Field Value | records.search | Every record whose field exactly equals a value |
| Record | Get | records.get (by ID, or by exact field value) | The record |
| Record | Create | bases.createChangeRequest | status, changeRequestId, recordId, fields |
| Record | Update | records.get then records.changeRequest | status, changeRequestId, recordId, fields |
| Node | List | nodes.list | The tree (with depth), the nodes of one type, or a folder’s contents |
| Node | Search by Name | nodes.searchByName | Nodes whose name or slug contains the query |
| Node | Get | nodes.get | A doc’s body, a folder’s children, a skill/drive/AirApp’s files, … |
| Doc | Create | docs.create | status, changeRequestId, nodeId, slug |
| Doc | Get | nodes.get | The markdown body and line count |
| Doc | Read Lines | nodes.readLines | A line range (lines, text) |
| Doc | Update | nodes.get then nodes.updateContent (append or replace) | status, changeRequestId (unchanged when nothing would change) |
| Folder | Create | nodes.createChangeRequest | status, changeRequestId, nodeId, slug |
| File | List | fileTrees.listFiles | One item per file of a skill, drive or AirApp |
| File | Read | fileTrees.readFile | Text content and contentHash, or an assetUrl for a binary file |
| File | Write | fileTrees.readFile then fileTrees.createChangeRequest | status, changeRequestId, operation (create / update / none) |
| Playbook | Search | playbooks.search | Matching skills and custom prompts, nearest first |
| Playbook | Get | playbooks.get | The playbook’s full instructions (content) |
| Workspace | Search | grep | One item per match in docs, files, records or prompts |

Every reference can be an ID, a slug or a name. Bases come from a live picker, and docs, folders, skills/drives/AirApps and nodes come from searchable pickers (“From List”), or you can type them in “By ID, Slug or Name” mode.

Writes go through Change Requests. The node never sends autoMerge. Busabase applies a change immediately when the credential has write access, and otherwise keeps it as a Change Request for a reviewer. Every write output says which happened:

• status: merged, in_review (or another review state), or unchanged when the content was already exactly that and nothing was sent
• changeRequestId: the Change Request’s ID

Record → Create / Update show a Fields mapper built from the picked Base’s real fields. Number, checkbox and date fields map onto n8n’s own types. select/multiselect fields get a dropdown of the Base’s choices; the choice name is used, which is what a record reads back.

Examples

• Log a form submission and file a note. Trigger → Busabase Record → Create (Base Leads, map the form fields) → Busabase Doc → Update (Doc Inbound log, Mode Append, Text - {{$json.fields.name}} via webform). The first node’s status tells you whether the lead landed or waits for review.
• Keep a skill’s file in sync with a Git repo. Schedule → HTTP Request (raw file) → Busabase File → Write (Skill release-notes, Path SKILL.md, Mode Create or Update). The output is unchanged when the file already matches, so nothing piles up in review.
• Let an AI agent follow your playbooks. The node is usable as a tool. Give the agent Playbook → Search and Playbook → Get: it finds the right skill or prompt for the task and reads its instructions before acting.
• Answer from the workspace. Workspace → Search (Pattern refund, Source Docs and Other Nodes) → Doc → Read Lines around each match.

Working with older Busabase servers

Some versions of the Busabase server answer certain mistakes with a quiet wrong result instead of an error. The node checks these client-side, so the same workflow behaves the same on every server version:

| Server behaviour | What the node does |
| — | — |
| records.list / records.search with a Base slug return no rows | Resolves every Base reference to its ID first (ID, slug, then name) |
| A record write keyed by a field’s display name (“Email”) drops that value | Maps keys to field slugs (slug, ID or name in any language); an unknown key is an error that lists the valid fields |
| nodes.list with a parent slug (or with a type filter) returns [] or ignores the parent | Resolves the parent to a folder ID and filters by type itself |
| nodes.updateContent, playbooks.get and docs.create‘s parent take an ID only | Resolves every node reference (ID, slug, exact name) to its ID |
| docs.create with a slug already used in the same folder returns the existing doc unchanged | Checks the slug first, and verifies the returned doc is the one it sent |
| A file update of a missing path silently creates it | Reads first and picks create/update itself; Update Only refuses a missing path |
| playbooks.search with an unknown key browses everything | Only ever sends queries, and retries once with single words when a phrase finds nothing |

Saved 0.1.x workflows

They keep working unchanged. A workflow saved with 0.1.x is node version 1: with no resource saved it lands on Record, every Record parameter kept its name, value and default, and version 1 keeps its Auto-Merge toggle and the raw API response as output. The one difference is that autoMerge: true is no longer sent, because it is the server’s own default. An explicit Auto-Merge off is still sent and still forces review. New nodes are version 2: no Auto-Merge toggle, and normalized write output.

Busabase Trigger node

Registers a webhook-kind rule on activation (create()), removes it on deactivation (delete()), and re-registers it if a health check finds it missing (checkExists(), on a 404 only). That is the standard n8n webhook-trigger lifecycle. Event is New Record or Updated Record. Base is optional; leave it blank for every Base in the space.

Every delivery is verified before it reaches your workflow. Busabase HMAC-SHA256-signs the request body (X-Busabase-Signature) with a secret generated at registration time, and this node checks that signature against the raw request bytes. n8n’s own GitHub/Stripe/Shopify triggers use the same mechanism, for the same reason: re-serializing an already-parsed JSON body is not guaranteed to reproduce the exact bytes that were signed. A missing signature, a wrong one, or a request with no raw body to check is rejected with HTTP 401. Nothing gets through unverified.

How it is built

Request and response shapes come from busabase-sdk‘s typed contract. Each route’s method and path come from nodes/Busabase/routes.generated.ts, which is generated from that same contract:

• import type from busabase-sdk only. A renamed procedure, a changed input field or a changed output type is a compile error.
• pnpm generate:routes regenerates the route table. pnpm typecheck fails when the table is stale (--check).
• HTTP goes through n8n’s helpers.httpRequestWithAuthentication, so the credential, proxy and TLS settings apply as for any node.

The SDK’s runtime is not bundled. Its dependencies (zod v4 and @orpc/*) use globalThis, setInterval, process and new Function when the module loads. Bundled, that is 17 errors from n8n’s community package scanner (@n8n/scan-community-package), which lints every .js file in the published tarball. With the types-only approach the published dist/ is about 83 kB and passes the scanner.

What this does not do (yet)

• No delete actions. Busabase deletes are review-first archives, which do not fit a single n8n “delete” action cleanly.
• No binary upload. File → Write writes text files. Binary files can be read (an asset URL) but not written.
• No OAuth credential. See above.