---
**Docs:** [Hoko Docs](https://docs.hoko.to/llms.txt)
This is the Markdown version of this reference page.
---
# n8n
Use Hoko link actions in a private n8n community node.
**Category:** Integrations
## Use the private node

The Hoko n8n node calls Hoko's unversioned resource REST API and the shared
engine. No dedicated Hoko job runner is needed. The preview targets n8n `2.42.x` with Node.js 24.

Download the package at
[`n8n-nodes-hoko.tgz`](https://docs.hoko.to/integrations/n8n/n8n-nodes-hoko.tgz).
For a self-hosted n8n instance, copy the file to the instance and run:

```sh
mkdir -p ~/.n8n/nodes
cd ~/.n8n/nodes
npm install /path/to/n8n-nodes-hoko.tgz
```

Restart n8n after installation. Enable community nodes if your deployment
requires that setting. The disposable Hoko engine and native Create and Find
workflow and credential proofs passed on n8n `2.42.6` with Node.js `24.19.0`.
n8n Cloud installation and execution are not verified. This is not a community
listing.

## Configure the credential

Create a Hoko API key in **Dashboard → Integrations → API Keys**. Give it
`linksRead` and `linksWrite` for `Create Link`. `Find Link` and the credential
test need `linksRead`.

Store the key in n8n's **Hoko API** credential. The node uses the fixed Hoko
origin `https://api.hoko.to`. The key selects the workspace. Do not add a
workspace ID or another origin to the node.

## Create and find links

`Create Link` accepts a destination URL, collection ID, external ID, and a
caller correlation ID. The URL must be HTTP or HTTPS, have no embedded
credentials, and stay within 2,048 characters. Resolve the collection ID from
`GET /collections`. The external ID stays within 255 characters. Correlation
IDs use visible ASCII and stay within 128 characters.

Before the first write, call `GET https://api.hoko.to/collections` with the
same credential and copy the returned collection ID. Resolve saved collection
references through this lookup before creating a new mapping.

`Find Link` returns zero, one, or multiple exact external-ID matches. Use the
same external ID for a later reconciliation lookup.

## Handle retries

Disable **Retry On Fail** on `Create Link`. Link creation is not idempotent.
Save the prepared intent before the Hoko write. If the response is uncertain,
look up the exact external ID and stop for operator review. Do not retry blindly
or replace a conflicting link.

Treat `401` as an invalid or revoked key, `403` as a missing scope, and `429`
as a rate limit. Respect `Retry-After`. Each HTTP dispatch receives a unique
terminal Hoko `requestId`. `Create Link` can make a preflight, write, and
readback dispatch. Successful output includes the verification-call
`requestId`, the caller's `correlationId`, and that terminal call's validated
rate-limit metadata.

## Keep the preview private

This slice excludes analytics, API-key management, billing, profile uploads,
destructive workspace actions, webhooks, event triggers, OAuth, and public n8n
distribution. Existing n8n HTTP Request and MCP Client workflows remain
usable.

Use disposable PostgreSQL and a disposable self-hosted n8n instance for
acceptance. Do not use production, staging, or Playground as a test database.
Record the n8n version, package version,
credential test, create, exact lookup, denied scope, revoked key, rate limit,
uncertain-write handling, secret redaction, and cleanup before calling the node
verified.

See the [n8n package README](https://docs.hoko.to/integrations/n8n/README.md),
[n8n community-node installation](https://docs.n8n.io/integrations/community-nodes/installation/manual-install/),
and [n8n node development](https://docs.n8n.io/integrations/creating-nodes/).

## Upgrade or remove the node

Keep the previous tarball and an n8n backup before an upgrade. Install the
replacement tarball in the self-hosted n8n user directory and restart n8n.
Run disposable Create and Find workflows before using the replacement with a
real workspace.

To roll back, reinstall the previous tarball and restart n8n. Remove temporary
workflows and revoke their Hoko keys. Remove the package after no workflow
uses it.