n8n-nodes-claude-refine

This is an n8n community node package for the Anthropic Claude API — the REST API behind the Claude models. It covers the parts of the API the built-in n8n Anthropic nodes don't: prompt caching with explicit breakpoints, message batches at 50% cost, token counting, extended thinking and effort control, structured outputs, citations, server tools (web search, web fetch, code execution) and the Files and Models APIs — all from one node, with an escape hatch to call any other endpoint.

It ships one node:

• Claude Refine — Message, Batch, File, Model and Custom API Call resources on your Anthropic account.

💾 Why "refine"? The node is built around the features that make Claude cheap and precise in production automations: cached prefixes cost ~10% to read and don't count toward input-token rate limits, and batches halve the price of bulk work.

Installation · Credentials · Resources & operations · Prompt caching · Usage examples · Model parameter rules · Known limitations

Installation

Follow the installation guide in the n8n community nodes documentation.

Self-hosted n8n: Settings → Community Nodes → Install and enter n8n-nodes-claude-refine.

Requirements:

• n8n ≥ 1.86.0 (the node uses the modern connection types and can be used as an AI Agent tool)
• An Anthropic API key (console.anthropic.com)

Credentials

Create a Claude Refine API credential:

🔐 Recommendation: use a workspace-scoped API key so the node only sees the files and batches of that workspace.

The credential test lists models, so a key with basic access is enough to validate it.

Resources & operations

Message

Send supports three input types:

• Simple Prompt — one user message.
• Messages Builder — multi-turn conversations built in the UI, with a per-message Cache Up to Here breakpoint.
• Raw Messages (JSON) — the raw messages array, for full control (tool_result loops, thinking blocks passed back, custom cache_control placement, mid-conversation system messages on supported models).

Plus, as dedicated sections:

• Attachments — images and documents (URL, binary property, base64 or an uploaded Anthropic file ID), with document citations.
• Prompt Caching — breakpoints on the system prompt, tool definitions and/or the conversation, each with a 5-minute or 1-hour TTL.
• Extended Thinking — adaptive (recommended on Claude 4.6+), disabled, or legacy token budgets for older models, with display control.
• Tools — custom tools (JSON definitions returned as tool_use blocks), plus Anthropic server tools: Web Search (with domain filters), Web Fetch and Code Execution.
• Output — effort (low → max) and structured outputs (JSON Schema-constrained responses, parsed into a parsed field).
• Options — temperature/top-p/top-k, stop sequences, metadata.user_id, service tier, inference region, custom anthropic-beta headers, response rate-limit headers, request timeout and a Request Body Overrides JSON merged last (MCP connector, container reuse, context management, fallbacks, task budgets…).

The default Simplify Output returns { id, model, text, stopReason, stopDetails?, thinking?, toolUses?, citations?, serverToolResults?, parsed?, usage }. The usage block always includes cache_creation_input_tokens and cache_read_input_tokens, so you can verify caching works. Disable it to get the raw API response.

Batch

Create has two modes: Build From Input Items (every incoming item becomes one request of a single batch — use expressions for the per-item prompt and custom ID) and Raw JSON (provide the requests array yourself, with any Messages API feature in params).

File

Model

Custom API Call

Call any other Anthropic endpoint (skills, usage/admin endpoints…) with the node credential: method, path, query, JSON body, custom anthropic-beta headers, optional full response.

Prompt caching

The headline feature. Place up to 4 breakpoints per request (the node exposes 3 fixed ones plus per-message breakpoints in the builder):

1. Cache Tool Definitions — after the last tool.
2. Cache System Prompt — after the system prompt.
3. Cache Conversation — on the last message (ideal for chat loops: each turn re-reads the previous turns from cache).

Rules to know (enforced by the API, surfaced in the node descriptions):

• Prefix caching is byte-exact and ordered tools → system → messages: keep stable content first, volatile content (timestamps, per-run IDs) after the last breakpoint.
• Prefixes below the model minimum (512–4096 tokens depending on the model) are silently not cached.
• Writes cost 1.25× (5m) or 2× (1h); reads cost ~0.1× and don't count toward input-token rate limits.
• Verify with usage.cache_read_input_tokens in the output — if it stays 0 across identical runs, something in your prefix changes every time.

Usage examples

• Cached RAG / chat memory — Send (Messages Builder) → paste the knowledge base into the System Prompt → Prompt Caching → Cache System Prompt: 1 Hour. Subsequent runs read the base from cache at ~10% cost.
• Bulk classification at half price — feed 1,000 items → Batch (Create, Build From Input Items, prompt ={{ $json.text }}) → Wait → Batch (Get) in a loop until ended → Batch (Get Results) → merge by customId.
• Vision / PDF analysis — Send with an Attachment (Binary Property) of type Document + Enable Citations → the simplified output includes the cited passages.
• Pre-flight cost check — Count Tokens with the exact same fields as your Send node → route on input_tokens before paying for a huge request.
• Agent tool — the node is usableAsTool, so an n8n AI Agent can call it (e.g. to trigger a batch or count tokens) as a tool.
• Web research with citations — Send + Tools → Web Search (limit domains with the allow-list) → serverToolResults and citations in the simplified output.

Model parameter rules

The API rejects certain parameter/model combinations with a 400. Cheat sheet (also in the field descriptions):

Use Model → Get to inspect a model's capabilities tree at runtime when in doubt.

Known limitations

• No streaming — n8n nodes return complete items. Very large Max Tokens values (over ~16,000) can hit HTTP timeouts; raise the Timeout option if needed.
• Tool-use loops are manual — when Claude returns toolUses, execute them in your workflow and send tool_result blocks back via Raw Messages (JSON). (A future version may automate the loop.)
• Beta features without dedicated fields (MCP connector, skills/containers, fallbacks, task budgets, context management) are reachable through Request Body Overrides + Anthropic Beta Headers, not first-class UI.
• The Files API is an Anthropic beta — the node sends the files-api-2025-04-14 header for you.

Resources

• Anthropic API documentation
• Prompt caching guide
• Batch processing guide
• n8n community nodes documentation

Version history

See CHANGELOG.md.

License

MIT — © Picture Element / Ben Gosciniak

Disclaimer

This is a community-maintained package. It is not affiliated with, endorsed by, or sponsored by Anthropic. "Claude" and "Anthropic" are trademarks of Anthropic, PBC.