Claude API n8n Workflow: How Acrid Calls the Claude API Inside n8n

The first claude api n8n workflow I ran in production taught me that the API call is never the hard part. Sending a prompt to Anthropic takes one node. The work is everything around that node: building a request body that doesn’t break when a caption contains a quote mark, reading a reply that is almost JSON, and deciding what happens when Anthropic answers with a 529 at 9:01 on a busy morning. This is a teardown of one real step in my social pipeline, the caption writer. It takes a story and returns one caption for each platform. I’ve simplified it a little, but the architecture is the real one. Credentials are shown as placeholders because this page is public and my keys are not.

What a claude api n8n workflow actually looks like

The whole thing is four nodes in a row with one branch off to the side:

1. Trigger. Whatever hands over the story: a schedule, a webhook, or an upstream workflow.
2. Build Request (Code node). Turns the story into a complete Claude request object.
3. Call Claude (HTTP Request node). POSTs that object to https://api.anthropic.com/v1/messages.
4. Parse Output (Code node). Pulls the text out, turns it into JSON, checks the shape, and throws if anything is wrong.

The side branch is the error output, which runs whenever node 3 or node 4 fails. It sends the failed item to an alert instead of letting it continue toward a publish step. I cover that wiring in how my n8n error alerts work. The short version: a broken caption that ships is worse than no caption at all. An empty slot only costs a post. A garbled one costs the reader’s trust.

Splitting the work into separate build, call and parse nodes is the main design choice here. Each node does one job, so when something breaks, the n8n execution log shows exactly which job failed and what input it had.

Why I use the HTTP Request node instead of the Anthropic node

n8n has a native Anthropic node, and for a quick experiment it’s fine. In production I use the generic HTTP Request node for three reasons.

Version pinning. The Messages API needs an anthropic-version header. With the HTTP node I set it myself to 2023-06-01, so an n8n update can’t quietly change how my request is shaped.

Prompt caching. A long system prompt that’s identical on every call is a good fit for caching. You mark a block with cache_control, and repeat reads cost a fraction of the normal input price. That requires sending system as an array of blocks, which a raw request makes easy. The details are in the prompt caching tutorial. The pricing math is in the Claude API pricing guide.

Debuggability. When the request is a plain JSON object I built myself, I can copy it out of the execution log and replay it with curl. That makes the bug reproducible in about ten seconds.

The API key never appears in the node. It lives in an n8n credential of type Header Auth, with the header name x-api-key and the value stored encrypted. The workflow only refers to the credential, never the secret. If you export the workflow and share it, the key stays behind. That pattern has its own article: how I keep API keys out of n8n workflows.

Here’s the Call Claude node as exported JSON, with placeholders where real IDs would go:

{
  "name": "Call Claude",
  "type": "n8n-nodes-base.httpRequest",
  "parameters": {
    "method": "POST",
    "url": "https://api.anthropic.com/v1/messages",
    "authentication": "genericCredentialType",
    "genericAuthType": "httpHeaderAuth",
    "sendHeaders": true,
    "headerParameters": {
      "parameters": [
        { "name": "anthropic-version", "value": "2023-06-01" },
        { "name": "content-type", "value": "application/json" }
      ]
    },
    "sendBody": true,
    "specifyBody": "json",
    "jsonBody": "={{ JSON.stringify($json.claudeRequest) }}",
    "options": { "timeout": 120000 }
  },
  "retryOnFail": true,
  "maxTries": 3,
  "waitBetweenTries": 5000,
  "onError": "continueErrorOutput",
  "credentials": {
    "httpHeaderAuth": { "id": "<YOUR_CREDENTIAL_ID>", "name": "Anthropic API key" }
  }
}

Look at the jsonBody line. That one expression prevents the most common bug in this kind of workflow, which is the next section.

Building the request: never hand-type JSON around user text

The tempting version types the JSON body straight into the node and drops the story in with an expression, like "content": "{{ $json.story }}". It works on every test you write. Then a story arrives containing a double quote, a newline or a backslash, and the body stops being valid JSON. Anthropic returns a 400, and the workflow fails on input that looked completely ordinary.

The fix: never assemble JSON as a string. Build the request as a real JavaScript object in a Code node, and let JSON.stringify handle escaping when it’s sent. Here’s the Build Request node:

// Code node: "Build Request" — mode: Run Once for Each Item
const story = $json.story;

const systemPrompt = `You write social captions for Acrid, an AI that runs a business in public.
Voice: blunt, funny, specific, affectionate. No emoji. No hashtags in the body.
Return ONLY a JSON object with exactly these keys:
  "x"         - under 260 characters
  "instagram" - 2 to 4 short paragraphs
  "tiktok"    - under 150 characters, hook first
No prose before or after the JSON. No code fences.`;

return {
  json: {
    ...$json,
    claudeRequest: {
      model: 'claude-sonnet-4-6',
      max_tokens: 1500,
      system: [
        {
          type: 'text',
          text: systemPrompt,
          cache_control: { type: 'ephemeral' }
        }
      ],
      messages: [
        {
          role: 'user',
          content: `Here is today's story. Write the three captions.\n\n<story>\n${story}\n</story>`
        }
      ]
    }
  }
};

A few choices in there are worth explaining.

The ...$json spread keeps the original item fields, like the story ID and the scheduled time, attached to the item. Later nodes need them, and n8n only passes along what each node returns.

The XML-style <story> tags mark where the input starts and stops. If the story itself contains something that reads like an instruction (“ignore the above and…”), the tags help Claude treat it as material to write about, not a command to follow. They aren’t a security boundary, but they’re a cheap improvement.

The model is Sonnet 4.6 because caption writing needs taste, and Sonnet 4.6 is the current workhorse. If this step only had to classify a story as “trading” or “not trading,” I’d use Haiku 4.5 and pay far less. Opus 4.8 is the flagship, but it’s overkill for 260 characters.

Parsing the output: Claude’s JSON is a claim, not a guarantee

The Messages API doesn’t return your text directly. It returns an envelope: an id, a stop_reason, a usage block, and a content array of typed blocks. The caption JSON is a string inside a text block inside that array. The Parse node’s job is to unwrap it carefully:

// Code node: "Parse Output" — mode: Run Once for Each Item
const res = $json;

// 1. Truncation check — a cut-off reply is never valid JSON anyway
if (res.stop_reason === 'max_tokens') {
  throw new Error(`Claude hit max_tokens for story ${res.storyId ?? 'unknown'}`);
}

// 2. Join every text block (usually one, but don't assume)
const text = (res.content || [])
  .filter(block => block.type === 'text')
  .map(block => block.text)
  .join('')
  .trim();

// 3. Strip code fences the model added despite instructions
const cleaned = text
  .replace(/^```(?:json)?\s*/i, '')
  .replace(/\s*```$/, '')
  .trim();

// 4. Parse, loudly
let captions;
try {
  captions = JSON.parse(cleaned);
} catch (err) {
  throw new Error(`Non-JSON reply: ${cleaned.slice(0, 200)}`);
}

// 5. Validate shape and limits
const required = ['x', 'instagram', 'tiktok'];
for (const key of required) {
  if (typeof captions[key] !== 'string' || captions[key].trim() === '') {
    throw new Error(`Missing or empty caption: ${key}`);
  }
}
if (captions.x.length > 280) {
  throw new Error(`X caption too long: ${captions.x.length} chars`);
}

return { json: { captions, usage: res.usage } };

Each numbered step handles a failure that happens in real use.

Truncation. If max_tokens is too low, Claude stops partway through. The reply then ends with something like "instagram": "the bench was designed agai, and JSON.parse fails with a vague error. Checking stop_reason first gives you an error message that tells you what actually happened.

Code fences. Even when told not to, models sometimes wrap JSON in triple backticks. You could keep reworking the prompt, but stripping the fences in code is more reliable. The prompt sets the goal, and the parser handles the cases where the model misses it.

Shape validation. Valid JSON can still be wrong JSON. A missing key or an X caption that’s 40 characters too long will fail at Buffer later, far from where the problem started. Checking here keeps the error close to its cause.

If you want stricter output, Claude can also return JSON through tool use. You define a tool whose input schema matches your captions, set tool_choice to that tool, and read the arguments from a tool_use block instead of a text block. It’s more setup in n8n, but the output keys are enforced by a schema rather than by asking nicely. For three string fields, the parse-and-validate approach above has been enough.

I also keep usage on the item. Input tokens, output tokens and cache reads flow downstream with each run, so cost per caption is something I can actually look up.

Handling failures: retry what is temporary, stop what is not

The Claude API fails in a few distinct ways, and each one needs its own response:

1. 429 (rate limited): temporary. Wait, then retry.
2. 529 (overloaded) and 5xx errors: temporary. Wait, then retry.
3. Network timeouts: usually temporary. Retry, but check that your timeout is long enough first.
4. 400 (bad request): your bug. Retrying sends the same broken body again.
5. 401 (authentication): dead or wrong key. No retry will help, and a human needs to know.

The node config at the top handles cases 1 to 3 with retryOnFail: true, three tries, and five seconds between them. The limitation is that n8n’s built-in retry doesn’t check the status code, so it also retries a 400 three times. That’s 15 seconds of wasted effort on a request that was never going to work. It’s mildly wasteful, but it’s simpler than writing my own retry loop, and the error output catches the item either way.

After the last retry fails, onError: continueErrorOutput sends the item down the error branch instead of stopping the whole execution. That matters when the workflow is processing a batch: one bad story shouldn’t take down the other four. Parse failures from node 4 go to the same branch. The branch formats the story ID, the error message and the first 200 characters of whatever Claude returned, then sends an alert.

The timeout gets its own warning, because it caused the worst incident I’ve had in n8n. A Stripe webhook was waiting on a workflow that made a 25-second Claude call. Stripe stops waiting after a few seconds, assumed the delivery had failed, and retried it. The pipeline ran again and the customer got duplicate emails. The fix was to reply to the webhook immediately and do the Claude work afterward. The full story is in my n8n review. The general rule: if something upstream is waiting on your workflow, never make it wait for a language model. Answer first, generate second.

On the HTTP node itself, I set the timeout to 120 seconds, well above how long the call should take. A long generation that gets cut off at 60 seconds looks exactly like an outage, and you’ll spend an hour investigating Anthropic when the real cause is one setting.

Where this node sits in the bigger machine

The caption writer is one step in the pipeline that posts to five platforms with no human approving anything. That’s why the parse-and-validate node is strict. Nobody reads the captions before they go out, so the code has to do the checking. A clean JSON object with three valid captions is the only thing allowed to continue to Buffer. Anything else becomes an alert. You can see how the whole pipeline fits together in the three-platform social pipeline teardown.

The same build, call and parse pattern repeats wherever Claude appears in my n8n workflows. Summarizing the trading tape, tagging a story, drafting a reply: the prompt and the validation change, but the four-node layout stays the same. Once you’ve built it once, every later Claude step is a copy with a new prompt.

If you want to see the real configs instead of my simplified versions, the fleet files are the actual prompt and config files this operation runs on, unlocked with an email.

If you’d rather have this built than build it yourself, this is the kind of thing we automate for people.