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.
- 1Add an HTTP Request node
Or paste a curl command from the API docs with Import cURL.
- 2Set the method and URL
GET to read, POST to create, PATCH or PUT to update, DELETE to remove.
- 3Choose the authentication
Predefined Credential Type if n8n supports the service, Generic Credential Type if not.
- 4Run it once and read the output
Fix the request before building anything after it.
- 5Add pagination and retry settings
Pagination under Add Option, Retry on Fail under Settings.
- 6Publish 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.
| Method | Use it to | Note |
|---|---|---|
| GET | Read data | No body. Filters go in query parameters |
| POST | Create a record or start an action | Body is usually JSON |
| PUT | Replace a whole record | Send every field, not only the changed ones |
| PATCH | Update part of a record | Send only the fields that change |
| DELETE | Remove a record | Test against a throwaway record first |
| HEAD, OPTIONS | Read headers or allowed methods | Rarely 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.
- 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
- 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 type | What you enter | Typical use |
|---|---|---|
| Header auth | A header name and its value | APIs that want a key in a header such as X-API-Key |
| Bearer auth | A bearer token | APIs that want Authorization: Bearer <token> |
| Query auth | One query parameter name and value | APIs that take the key in the URL |
| Basic auth | Username and password | Older APIs and many self-hosted tools |
| Digest auth | Username and password | The few APIs that still require digest |
| OAuth2 | Grant type, token URL, client ID and secret, scope | APIs that act on behalf of an account |
| OAuth1 | Consumer key and secret, three URLs, signature method | Legacy APIs that never moved to OAuth2 |
| Custom auth | JSON holding headers, qs or body values | APIs 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.
| Mode | Use it when | Expression from the n8n docs |
|---|---|---|
| Response Contains Next URL | The API returns the address of the next page | {{ $response.body["next-page"] }} |
| Update a Parameter in Each Request, Type Query | The API takes a page number in the URL | {{ $pageCount + 1 }} |
| Update a Parameter in Each Request, Type Body | The 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.
- 01500 items arrive
One request per item by default, as fast as n8n can send them.
- 02Batching splits them
Items per Batch sets how many go out together.
- 03Batch Interval waits
A pause in milliseconds between batches. 1000 is one second.
- 04A request fails
A 429 or a timeout from the service.
- 05Retry on Fail tries again
Up to Max Tries, with Wait Between Tries in between.
- 06Still 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.
- 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
- 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.
| Error | Cause | Fix |
|---|---|---|
| 400 Bad request | A query parameter name or value is wrong, or an array is in the wrong format | Check names against the API docs. Set Array Format in Query Parameters |
| 403 Forbidden | The credential failed or lacks a permission | Add the scope to the key, or create a new key with it |
| 404 Not found | The URL has a typo or the endpoint was retired | Copy the endpoint again from the API docs |
| 415 Unsupported media type | A file was sent as a raw body to an API that expects multipart | Set Body Content Type to Form-Data with an n8n Binary File parameter |
| 429 Too many requests | You passed the rate limit | Add Batching, or turn on Retry on Fail |
| ECONNREFUSED | Nothing listens at that address. In Docker, localhost is the n8n container | Use host.docker.internal, the Compose service name or 127.0.0.1 |
| JSON parameter need to be an valid JSON | The JSON you typed does not parse | Validate 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:
- Go to Settings, then n8n API.
- Select Create an API key, give it a label and set an expiration.
- Copy the key and send it in the
X-N8N-API-KEYheader.
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.
- 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.