n8n-nodes-promptui-client

This is an n8n community node. It lets you list, fetch and execute PromptUI prompts from your n8n workflows via PromptUI's public API.

PromptUI is a self-hosted UI for managing and running multi-step, multimodal (text / image / video) prompts across providers. This node wraps PromptUI's /api/v1 so you don't have to build raw HTTP requests.

Installation · Credentials · Operations · Usage · Resources

Installation

Follow the community nodes installation guide and use the package name n8n-nodes-promptui-client.

To build and use it locally from this monorepo:

corepack pnpm install
cd packages/n8n-nodes-promptui
corepack pnpm build
# then link the package into your n8n custom nodes directory (~/.n8n/custom)

Credentials

Create a PromptUI API credential:

• Base URL — your PromptUI instance, e.g. https://promptui.example.com (without the /api/v1 suffix).
• API Token — a personal token generated under Settings → API Tokens in PromptUI.
• Callback Secret (optional) — the server's CALLBACK_SECRET env value. Only needed for the PromptUI Trigger node to verify incoming job callbacks; leave empty otherwise.

The credential adds Authorization: Bearer <token> to every request. Use Test to verify the connection.

Operations

Prompt

| Operation | Description | |---|---| | Get Many | List visible prompts. Supports server-side search (q), modality filter, and Return All / Limit (cursor pagination). | | Get Definition | Retrieve a prompt's full definition (steps, inputs, outputs). | | Get Step | Retrieve a single step by zero-based index. | | Execute | Run the whole prompt chain. Inputs are loaded dynamically from the selected prompt. |

The Prompt selector scales to large catalogs: pick from a searchable, paginated list, or pass an ID/Name directly via an expression.

Execute inputs

• Text / number / select inputs appear as typed fields (auto-loaded from the prompt definition).
• Image / video inputs are mapped under Binary Inputs: pick the prompt's media input and the name of the binary property on the incoming item. The file is base64-encoded and sent automatically.
• Model Overrides (optional) override the recommended model per step for this run only (ephemeral, not saved).
• Callback URL / Payload (optional) let the server notify you (HMAC-signed) when the job finishes, instead of polling. Requires callbacks to be enabled on the server.
• Wait for Completion (optional) polls the job until it finishes and returns the result directly (with configurable poll interval and timeout). Leave off for long jobs (video) and use async + callback instead.

Job

| Operation | Description | |---|---| | Get Status | Current status, error, queue position, expiry. | | Get Result | Download the ephemeral result within its TTL — text as a string, media as binary data. |

Trigger

The PromptUI Trigger node starts a workflow when a job finishes, instead of polling. It exposes a webhook that receives the server's HMAC-signed job-completion callback.

Setup:

1. Add a PromptUI Trigger node and select the same PromptUI API credential, with the Callback Secret filled in (matching the server's CALLBACK_SECRET).
2. Activate the workflow and copy the trigger's Production webhook URL.
3. In a Prompt → Execute node, paste that URL into Callback URL (under Options). Optionally set a Callback Payload to correlate the job.
4. On the server, enable callbacks: CALLBACK_ENABLED=true and an identical CALLBACK_SECRET.

Options:

• Trigger On Statuses — only fire for done / failed (default both). Other statuses are verified and acknowledged (200) but don't start the workflow.
• Timestamp Skew (Seconds) — max allowed clock difference for the signed timestamp (default 300), as replay protection.

Verification: the trigger checks the X-PromptUI-Signature (HMAC-SHA256 over "{timestamp}.{body}") against the raw request body and the X-PromptUI-Timestamp against the skew window. Invalid or expired callbacks are rejected with HTTP 401 and do not trigger the workflow.

Output: one item with { jobId, status, resultRef, error, payload } (payload echoes the Callback Payload you sent). Use Job → Get Result with the jobId to download the result within its TTL.

Usage

A typical synchronous flow:

1. PromptUI → Prompt → Execute, pick a prompt, fill the inputs, enable Wait for Completion.
2. The node returns the result — text in result, or binary media on the data property.

A typical asynchronous flow (recommended for video):

1. PromptUI → Prompt → Execute (Wait off) → returns jobId.
2. Later, PromptUI → Job → Get Status until DONE, then Job → Get Result. Or receive the server callback via a Webhook.

Publishing

This package is published to npm automatically by a GitHub Action (.github/workflows/publish-n8n.yml):

• It runs on pushes to main that touch packages/n8n-nodes-promptui/** (or via manual dispatch).
• A version gate compares the local package.json version with the one published on npm and only publishes on a version bump — re-running without a bump is a no-op.
• The repository must define the secret NPM_TOKEN (an npm automation token with publish rights).

To release: bump version in this package's package.json and merge to main.

Resources

• PromptUI public API (/api/v1)
• n8n community nodes documentation

License

MIT