Dify Plugin

Install the Busabase plugin from the Dify Marketplace so Dify workflows, chatflows, and agents can read your workspace and write back as Change Requests.

The Busabase plugin on the Dify Marketplace gives Dify workflows, chatflows, and Agents 19 tools for a Busabase workspace: read Bases, records, docs, and files, search the workspace, follow your team's playbooks, and write back. The plugin is open source at github.com/busabase/dify-plugin-busabase.

Writes are Change Requests

Every write carries a commit message, a diff, and history. It merges right away when the API key has write access, and waits in the Busabase Inbox for review when the key can only propose changes.

1. Install the plugin

Open Busabase on the Dify Marketplace and install it into your Dify workspace.

2. Create an API key

In Busabase, open Account → API Keys and create a key. The permission level decides what happens to writes:

Permission level	What a write from Dify does
Write data	Merges right away. The output has the new or changed object's id.
Change Request	Waits for review in the Busabase Inbox. Nothing changes until someone approves it.
Read-view-only	Reads work; write tools fail.

See API keys for expiry and how keys relate to spaces.

3. Authorize the plugin in Dify

Open Tools → Busabase → Authorize and fill in:

Credential	Value
Base URL	`https://busabase.com` for Busabase Cloud. For a self-hosted or local server, its URL.
API Key	The key from step 2. Leave empty only for a local server without auth.
Space ID	Optional. Only needed when your account has more than one space.

Dify checks the credentials by listing your Bases.

Connect a local open-source server

npx busabase server listens on http://localhost:15419. If Dify runs in Docker, localhost is the container itself: start the server with --host 0.0.0.0 and use http://host.docker.internal:15419 on Docker Desktop (macOS and Windows), or the Docker bridge gateway IP on Linux (for example http://172.17.0.1:15419).

4. Add the tools to an app

Add only the tools an app needs to a workflow, chatflow, or Agent. Each tool returns a short text summary plus structured JSON for workflow variables.

Group	Tools
Records	List Bases, List Records, Find Records by Field Value, Get Record, Create Record, Update Record
Nodes and docs	List Nodes, Search Nodes by Name, Get Node, Read Lines, Create Folder, Create Doc, Update Doc
Files in skills, drives, and AirApps	List Files, Read File, Write File
Playbooks	Search Playbooks, Get Playbook
Search	Search Workspace

Bases, folders, docs, and other nodes can be given by id, slug, or exact name. When something does not exist, the call fails and lists the valid options.

Read the write result

Write tools return a status:

merged: the change is applied. The output includes recordId or nodeId and the changeRequestId.
in_review: the change waits for a reviewer in Busabase. Branch on this in a workflow to tell the user.
unchanged: Update Doc or Write File found the content already identical, so nothing was sent.

Write tools take a Commit Message. Reviewers see it and the history keeps it; if you leave it empty, the plugin writes a short one.

Current limits

No delete, archive, move, or rename for records or nodes.
No bulk writes and no Base schema changes. Create Bases and fields in Busabase.
Update Doc appends or replaces the whole body; Write File replaces the whole file.
Find Records by Field Value matches the whole value exactly. Use Search Workspace for partial matches.
Authentication is by API key only.

Troubleshooting

Authorization fails: check the Base URL and that the key has not expired.
Requests are rejected as ambiguous: your account has more than one space. Fill in Space ID.
A local server is unreachable from Dify in Docker: use host.docker.internal or the bridge gateway IP instead of localhost, and start the server with --host 0.0.0.0.

Dify Plugin

On this page