Skip to main content

n8n API Integration: The HTTP Request Node Guide

n8n API integration with the HTTP Request node: authentication, pagination, rate limits, errors and n8n's own API, from n8n's documentation, October 2026.

Founder of IImagined.ai

Published
Feb 10, 2026
Updated
Oct 13, 2026
Reading time
10 min read
Quick answer

n8n connects to any service with a REST API through the HTTP Request node. Set the method and URL, pick a predefined credential when n8n already knows the service or a generic one such as Header auth or OAuth2 when it does not, then add pagination, batching and Retry on Fail before you publish. n8n also has its own API, authenticated with the X-N8N-API-KEY header, which is not available during the free trial.

n8n API integration runs through one node: HTTP Request, which calls any REST API from a workflow. You give it a method, a URL and a credential, and it returns the response as items the next node can use. Everything else on this page is what turns a request that works once into one that survives real traffic: authentication, pagination, rate limits and errors.

Based on n8n's documentation as read on 13 October 2026: the HTTP Request node, its common issues page, HTTP Request credentials, custom API operations, the pagination cookbook and n8n API authentication. Option names are quoted as they appear there. This page replaces an earlier version that listed three authentication types and a setup time nobody had measured.

Quick answer: call any API from n8n
  1. 1
    Add an HTTP Request node

    Or paste a curl command from the API docs with Import cURL.

  2. 2
    Set the method and URL

    GET to read, POST to create, PATCH or PUT to update, DELETE to remove.

  3. 3
    Choose the authentication

    Predefined Credential Type if n8n supports the service, Generic Credential Type if not.

  4. 4
    Run it once and read the output

    Fix the request before building anything after it.

  5. 5
    Add pagination and retry settings

    Pagination under Add Option, Retry on Fail under Settings.

  6. 6
    Publish the workflow

    Nothing runs on its own until the workflow is published.

What does the n8n HTTP Request node do?

It sends one HTTP request per input item and hands back whatever the server returns. n8n ships dedicated nodes for many services, and each of those is a wrapper around the same idea. When a service has no node, or its node lacks the operation you need, HTTP Request is the route. If API is a new word, start with the glossary entry.

MethodUse it toNote
GETRead dataNo body. Filters go in query parameters
POSTCreate a record or start an actionBody is usually JSON
PUTReplace a whole recordSend every field, not only the changed ones
PATCHUpdate part of a recordSend only the fields that change
DELETERemove a recordTest against a throwaway record first
HEAD, OPTIONSRead headers or allowed methodsRarely needed in a workflow

The node has three switches that are off by default: Send Query Parameters, Send Headers and Send Body. Each one accepts either name and value pairs (Using Fields Below) or a block of JSON (Using JSON). The body can be JSON, Form URLencoded, Form-Data, an n8n Binary File or Raw with a content type you set.

The fastest start is Import cURL. Most API documentation gives a curl example for every endpoint. Paste it into the modal, select Import, and the node fills in the method, URL, headers and body. Importing overwrites whatever the node held before.

Which authentication should you choose?

Use a predefined credential type whenever one exists, and a generic one otherwise. That is n8n's own recommendation, and it saves work: the predefined type already knows where the token goes and how to refresh it.

Two ways to authenticate an HTTP Request node
Predefined Credential Type
  • For services n8n already integrates with
  • Reuses a credential you set up for that service
  • Covers operations the service node does not offer
  • Some types are limited to certain scopes, and n8n shows a notice
  • Also how credential-only integrations work
Generic Credential Type
  • For any other API
  • You choose the method and fill in the fields
  • Stored encrypted, like every n8n credential
  • Reusable across workflows once saved
  • Read the API docs to see which method it wants

Source: n8n docs, checked 13 October 2026

The generic types, with what each one asks for:

Generic typeWhat you enterTypical use
Header authA header name and its valueAPIs that want a key in a header such as X-API-Key
Bearer authA bearer tokenAPIs that want Authorization: Bearer <token>
Query authOne query parameter name and valueAPIs that take the key in the URL
Basic authUsername and passwordOlder APIs and many self-hosted tools
Digest authUsername and passwordThe few APIs that still require digest
OAuth2Grant type, token URL, client ID and secret, scopeAPIs that act on behalf of an account
OAuth1Consumer key and secret, three URLs, signature methodLegacy APIs that never moved to OAuth2
Custom authJSON holding headers, qs or body valuesAPIs that need two or more secrets at once

Two more are worth knowing. Simplified Custom Auth, available from n8n 2.35.0, lets you write an auth template with placeholders and define a labelled field for each one, which is tidier when you hand a workflow to someone else. And SSL certificates is a separate credential for APIs that require a client certificate: it takes a CA bundle, a certificate and a private key.

Whichever you pick, put the secret in a credential, never in the URL field or a Set node. A key typed into a node travels with every export of the workflow. Getting the key itself is a separate job for each provider: we have walkthroughs for an OpenAI API key and a Claude API key.

How do you read the response?

The node parses JSON automatically and outputs it as items. Response Format defaults to Autodetect; set it to File when you are downloading a PDF or an image, or to Text for raw output. Turn on Include Response Headers and Status when a later node needs the status code or a header such as a rate limit counter.

Later nodes read fields with expressions. {{ $json.data.user.id }} reads a nested value and {{ $json.items[0].email }} reads the first entry of an array. Our n8n expressions cheat sheet has the rest.

One option needs care. Never Error makes the node report success whatever status code comes back. It is useful when a 404 is a normal answer ("this contact does not exist yet"), and dangerous anywhere else, because a failed call then looks like a good one. If you switch it on, add an If node that checks the status code straight after.

How does pagination work in n8n?

Most APIs return results a page at a time, and the HTTP Request node can fetch every page in one run. Select Add Option, then Pagination, and set Pagination Mode. It is off by default, which is why a first test so often returns exactly 20, 50 or 100 records and no more.

ModeUse it whenExpression from the n8n docs
Response Contains Next URLThe API returns the address of the next page{{ $response.body["next-page"] }}
Update a Parameter in Each Request, Type QueryThe API takes a page number in the URL{{ $pageCount + 1 }}
Update a Parameter in Each Request, Type BodyThe API takes the page number in a POST body{{ $pageCount + 1 }}

Three variables are available inside pagination settings: $pageCount (pages fetched so far, starting at zero), $request (the request the node sent) and $response (the body, headers and status code that came back). The + 1 in the page number expression is there because most APIs count pages from one.

Set the page size separately, as an ordinary query parameter such as limit, in the main parameters and not under Options. Then read the API documentation for how it signals the last page, and set the stop condition to match. A pagination loop with no working stop condition will keep calling until something else stops it.

How do you stay inside rate limits?

Slow the node down before the API does it for you. n8n documents two settings for a 429 response, and they solve different problems.

What happens to 500 input items with batching and retries on
  1. 01
    500 items arrive

    One request per item by default, as fast as n8n can send them.

  2. 02
    Batching splits them

    Items per Batch sets how many go out together.

  3. 03
    Batch Interval waits

    A pause in milliseconds between batches. 1000 is one second.

  4. 04
    A request fails

    A 429 or a timeout from the service.

  5. 05
    Retry on Fail tries again

    Up to Max Tries, with Wait Between Tries in between.

  6. 06
    Still failing

    The node errors and your error workflow takes over.

  • Batching (Add Option, then Batching) prevents the problem. Set Items per Batch and Batch Interval (ms). The interval defaults to 0, which means no wait at all.
  • Retry on Fail (the node's Settings tab) recovers from it. Set Max Tries and Wait Between Tries (ms).
  • Timeout (Add Option) sets how long the node waits for the server to start answering, in milliseconds.

Retries have a cost: a POST that timed out may still have succeeded on the other side, and retrying it creates a duplicate. For anything that creates records, sends messages or charges money, check whether the API accepts an idempotency key, or look the record up before creating it. Our n8n error handling guide covers what to do when the retries run out.

Should the API call you, or should you call it?

If the service can send a webhook, let it. The HTTP Request node is for calling out; the Webhook node is for being called. They are often used as a pair: a webhook announces that something changed, and an HTTP request fetches the full record.

Polling against webhooks
Polling: Schedule Trigger + HTTP Request
  • Works with every API
  • Asks on a timer, so news arrives late by up to one interval
  • Spends requests even when nothing changed
  • You must track what you have already seen
  • Nothing has to reach your n8n instance from outside
Webhook node
  • Only works if the service can send events
  • Arrives when the event happens
  • No requests spent while idle
  • The sender may deliver twice, so handle duplicates
  • Your instance needs a public HTTPS address

The n8n webhook trigger guide covers test and production URLs, and the cron expression guide covers the timer side of polling.

Which errors will you see, and what fixes them?

The usual ones, with their fixes. This table follows n8n's common issues page.

ErrorCauseFix
400 Bad requestA query parameter name or value is wrong, or an array is in the wrong formatCheck names against the API docs. Set Array Format in Query Parameters
403 ForbiddenThe credential failed or lacks a permissionAdd the scope to the key, or create a new key with it
404 Not foundThe URL has a typo or the endpoint was retiredCopy the endpoint again from the API docs
415 Unsupported media typeA file was sent as a raw body to an API that expects multipartSet Body Content Type to Form-Data with an n8n Binary File parameter
429 Too many requestsYou passed the rate limitAdd Batching, or turn on Retry on Fail
ECONNREFUSEDNothing listens at that address. In Docker, localhost is the n8n containerUse host.docker.internal, the Compose service name or 127.0.0.1
JSON parameter need to be an valid JSONThe JSON you typed does not parseValidate it. With an expression, wrap the whole object in double curly brackets

The connection error deserves a second line for anyone self-hosting. Inside Docker, localhost means the n8n container, not your machine. To reach a service on the host, use http://host.docker.internal:<port>; to reach another container in the same Compose stack, use its service name. On n8n Cloud, a workflow cannot reach your localhost at all, so the service needs a public URL or a tunnel. More cases are in common n8n errors and fixes.

Does n8n have an API of its own?

Yes, and it is a different thing from the HTTP Request node. The n8n public API lets another program manage your instance: list workflows, read executions, create credentials. To use it:

  1. Go to Settings, then n8n API.
  2. Select Create an API key, give it a label and set an expiration.
  3. Copy the key and send it in the X-N8N-API-KEY header.
curl -X 'GET' \
  '<your-cloud-instance>/api/v<version-number>/workflows?active=true' \
  -H 'accept: application/json' \
  -H 'X-N8N-API-KEY: <your-api-key>'

Two limits from the authentication docs: the API is not available during the free trial, and choosing scopes for a key is an Enterprise feature. On other plans, in n8n's words, keys "have full access to all the account's resources and capabilities", so treat one like an admin password.

Can an AI agent use the HTTP Request node?

Yes. Attach the node to an AI agent as a tool and the model decides when to call the API. In that position the node gains Optimize Response, which cuts the response down before the model sees it: pick fields from JSON, apply a CSS selector to HTML, or truncate text to a character limit that defaults to 1,000.

Before you publish a workflow that calls an API
  • The secret lives in a credential, not in a node field
  • The key has only the scopes this workflow needs
  • Pagination is on, and it stops on the last page
  • Batching or Retry on Fail is set to match the documented rate limit
  • Calls that create or charge are safe to repeat, or are not retried
  • Never Error is off, or an If node checks the status code
  • An error workflow is published and alerts someone
  • You ran it against a test account before real data

Give an agent read-only endpoints first, and keep anything that writes, sends or pays behind a human approval step. Claude and n8n shows the agent side in detail.

Where to go next

If you have never built a workflow, the n8n tutorial for beginners comes first. To check whether n8n already has a node for your service before reaching for HTTP Request, see how many integrations n8n has. The AI automation library lists every related guide. And if the API you want to call is one you would rather build and sell yourself, AI SaaS Builder is our program on building a product on Supabase, Next.js and the Claude API.

n8n API integration: FAQ

How do I connect an API to n8n?

Add an HTTP Request node, set the method and URL from the API documentation, and choose an authentication type. Use a predefined credential type when n8n already supports the service, or a generic credential such as Header auth or OAuth2 when it does not. Run the node once, read the output, then add pagination and retry settings before you publish the workflow.

What authentication does the n8n HTTP Request node support?

Two routes. Predefined credential types reuse the credentials of services n8n already integrates with. Generic credential types cover everything else: Basic auth, Digest auth, Header auth, Bearer auth, Query auth, OAuth1, OAuth2, Custom auth and, from n8n 2.35.0, Simplified Custom Auth. A separate SSL certificates credential handles client certificates.

How does pagination work in the n8n HTTP Request node?

Open Add Option, then Pagination, and pick a mode. Response Contains Next URL follows a link the API returns, read with an expression on $response. Update a Parameter in Each Request changes a query or body value on every call, usually a page number built from $pageCount. The node keeps requesting pages and returns the combined results.

How do I fix a 429 error in n8n?

A 429 means the service is rate limiting you. n8n documents two fixes on the HTTP Request node. Add the Batching option and set Items per Batch and Batch Interval in milliseconds, so requests are spaced out. Or open the node Settings, turn on Retry on Fail, and set Max Tries and Wait Between Tries. Check the API documentation for the real limit first.

What is the difference between PUT and PATCH in an HTTP request?

PUT replaces the whole resource, so the body has to carry every field, including the ones you are not changing. PATCH is a partial update, so the body carries only the fields that change. APIs differ on which they accept, so check the endpoint in the documentation before choosing a method in the node.

Does n8n have its own API?

Yes. n8n has a public REST API for managing workflows, executions, credentials and more. Create a key under Settings, then n8n API, and send it in the X-N8N-API-KEY header. The docs say the API is not available during the free trial, and that scoped keys are an Enterprise feature: other keys have full access to the account.

Can an n8n AI agent call an API?

Yes. The HTTP Request node can be attached to an AI agent as a tool. In that position it gains an Optimize Response option, which trims JSON, HTML or text before it is sent to the model, by selecting fields, applying a CSS selector or truncating to a character limit. Smaller responses cost fewer tokens and are easier for the model to read.

Free · no card needed

Start with the free Starter Kit.

A unit economics calculator from AI SaaS Builder, plus four more working files.

Starter Kit5 files · free
See All Access: $99/mo →30-day money-back guarantee