How to Use the n8n API

The n8n API gives you a way to manage workflows, credentials, and executions without using the visual editor. With a few API requests, you can automate repetitive tasks, integrate n8n with other tools, and control your instance from your own applications.

If you're creating your first API key or building more advanced automations, this guide walks you through the core concepts and the API endpoints you'll use most often. You'll also learn how AI agents work with the n8n API and when they're worth using.

What is the n8n API?

The n8n API is a REST API that lets you manage your n8n instance without using the visual editor. You can create, update, activate, and delete workflows, monitor executions, manage credentials, and automate other administrative tasks with API requests.

n8n refers to this as its public API. In this case, "public" doesn't mean anyone can access it. It simply means the API is officially documented and supported for developers, unlike the private endpoints that n8n uses internally. Every request still requires authentication before it can access your instance.

It's also helpful to understand the difference between the public API and webhooks. The public API is used when your application sends requests to n8n to manage workflows and other resources. Webhooks work the other way around. They let external services send data to an n8n workflow to trigger an automation.

3 Ways You Can Use APIs in n8n

When people search for the "n8n API," they often mean different things. In practice, there are three common ways to work with APIs in n8n. Knowing the difference will help you find the right approach for your project.

This guide focuses mainly on the n8n public API, which lets you manage your n8n instance programmatically. Because many users also need to connect third-party APIs or expose their own endpoints, we've included dedicated sections on the HTTP Request node and webhooks as well.

What You Need Before You Start

You need a paid n8n Cloud plan or a self-hosted instance. The API is not available on the free trial. If you self-host the Community edition, you get full API access without a Cloud subscription, though you take on the hosting work in exchange. On an enterprise license, you also get scoped API keys, which limit what each key can do.

You also need basic comfort with HTTP requests. You should know what GET and POST mean and how to read a JSON response. If that sounds new, MDN's overview of HTTP and IBM's guide to REST APIs cover the basics in an afternoon.

How to Get Your n8n API Key

You create an API key inside your n8n settings. The key acts as your password for every request, so treat it with the same care.

Follow these steps:

1. Log in to your n8n instance.
2. Open Settings, then select n8n API.
3. Select Create an API key.
4. Choose the key label so you remember what it is for and set an expiration time.
5. If you're on an Enterprise plan, select the API key scopes.
6. Copy and securely store the API key. You'll use it to authenticate API requests.

n8n shows the full key once. If you lose it, delete the old key and create a new one. On an enterprise license, you can also set scopes when you create the key. Scopes restrict a key to specific resources, like read-only access to workflows. Pick the smallest set of scopes that the key needs to do its job. The n8n authentication docs list every available scope.

API Key Security Basics

Your key can read and change everything it has scope for, so a leaked key is a serious problem. A few habits keep you safe:

• Never paste a key into a public GitHub repository. Bots scan new commits for tokens within minutes.
• Never share a key in a community forum thread, even when asking for help. Share the error message and redact the token.
• Rotate keys on a schedule. Expiration dates make this automatic.
• Use one key per tool or project. When one key leaks, you revoke one key instead of all of them.
• Store keys in environment variables or a secrets manager, not in your workflow code.

How to Make Your First API Request

Every request to the n8n API needs your key in a header named X-N8N-API-KEY. Once you have the key and the right base URL, your first call takes under a minute.

Set Your Base URL

The base URL depends on where your instance runs.

n8n Cloud: https://yourname.app.n8n.cloud/api/v1

Self-hosted: https://your-domain.com/api/v1

Replace yourname with your Cloud subdomain, or your-domain.com with the address of your self-hosted instance. The subdomain is the name you picked at signup, and it shows in your browser address bar when you use the editor. The version number in the path is 1. You will reuse this base URL in every request that follows.

Example: Fetch Your Active Workflows

This request fetches every active workflow in your account.

The -H flag adds your authentication header. The URL points to the workflows resource. The query parameter active=true filters the list to workflows currently running in production.

The response comes back as JSON. The data field holds an array of workflow objects, starting at index 0. Each object includes fields like id, name, and active. When active reads true, the workflow is live. You will use the ID value constantly, because almost every other operation asks for it.

Test Safely Before You Touch Production

API calls hit your real account. A delete request removes a real workflow, and there is no undo. Build the habit of testing before you run anything against production data.

Two options work well. Create a throwaway test workflow and practice your calls against it, or run a separate test instance if you self-host. Self-hosted users also get a built-in API playground with interactive Swagger docs, where you can try requests and see live responses. The playground is not available on n8n Cloud. One warning applies either way: the playground connects to your live data, so a delete is still a delete.

Core Operations You Can Run with the Public API

The API groups its endpoints by resource: workflows, executions, credentials, users, tags, variables, projects, and audit. Each page in the API reference shows the operation, the parameters it accepts, and the shape of the response. This section walks through the operations you will use most.

Create, Update, and Delete Workflows

You create a workflow with a POST request to the workflows endpoint. The body is JSON, and four fields are required: a name, a nodes array, a connections object, and a settings object.

Each entry in the nodes array describes one node: its type, its parameters, and its position on the canvas. The connections object maps how data flows between nodes. Writing this JSON by hand gets tedious fast, so most people build a workflow in the editor first, export it as JSON, and use that as a template for API-created copies. You will reuse this export-as-template trick throughout the guide.

To update a workflow, send the changed JSON to the same endpoint with the workflow ID in the path. To delete one, send a DELETE request to that path. Deletion is permanent, so double-check the ID before you send it.

Activate and Deactivate Workflows

Activation gets its own endpoints. Send a POST to /workflows/{id}/activate to turn a workflow on, and a POST to /workflows/{id}/deactivate to turn it off. A status change through these endpoints leaves the workflow itself untouched, so nothing about its nodes or settings changes.

The deactivated endpoint earns its keep during incidents. When a workflow starts throwing errors at 2 a.m., an API call turns it off faster than logging into the editor, and you can investigate without losing any work.

When you activate a workflow that has a cron trigger, n8n schedules its next run right away. There is no "activate but don't run yet" flag, so activate scheduled workflows only when you want them to fire.

Monitor Executions and Performance

Every time a workflow runs, n8n records an execution. The executions endpoint pulls that history, which turns the API into a monitoring tool.

A GET request to /executions returns recent runs. You can filter by workflow or by status values like success, error, or waiting. Checking the error count across your account each morning takes one request. Watching the execution time trend over weeks tells you when a workflow is slipping before users notice.

Two limits shape how you read this data. First, execution history is pruned automatically, and the API cannot recover pruned runs. On Cloud, retention depends on your plan. Starter plans keep about 7 days of runs, Pro plans keep about 30, and both cap the total number of runs stored. Self-hosted instances prune after 14 days by default. Pull anything you want to keep before it ages out. Second, cursor pagination on the executions endpoint can misbehave. If a loop keeps handing you the same page instead of advancing, filter by date range or workflow to keep result sets small, and confirm the behavior against your n8n version.

Manage Credentials Through the API

Credentials are the stored logins your workflows use to reach outside services. The credentials endpoint lets you create and delete them with code, which helps when you set up many similar workflows across environments.

Every credential has a credential type. The type tells n8n which service the login belongs to and which fields it needs. When you create a credential through the API, pass the exact credential type name. To find it, export a workflow that already uses the credential and read the type from the node. A Google Drive node, for example, shows the type name googleDriveOAuth2Api. You can also request the schema for a type name, and the response lists every field that type requires.

A GET on a workflow returns each credential's ID but never its secret values. That means you cannot fully copy a workflow to another instance through the API alone. Recreate the credential on the target instance with a POST first, then create the workflow that references it.

How to Connect External APIs Inside n8n

Use the HTTP Request node to connect to any outside API from inside a workflow, even when n8n has no pre-built node for that service. n8n ships hundreds of pre-built nodes, but the HTTP Request node is what makes the tool feel unlimited. If a service has an API, you can integrate it.

The HTTP Request node supports the common authentication types. Which one you pick depends on what the outside service expects.

n8n also offers predefined credential types for many services. These let you reuse a credential you already set up, like an Asana login, inside a raw HTTP request. That helps when a service's pre-built node lacks an operation its API supports: you keep the stored credential and call the missing endpoint directly.

Pull Data from a Web Service into a Database

Here is a pattern you will reuse constantly. A workflow fetches records from an outside service, cleans them up, and writes them to a database.

1. A schedule trigger starts the workflow each night.
2. An HTTP Request node calls the service and pulls new records.
3. A code or transform node reshapes the data into the fields your database expects.
4. A database node inserts the rows.
5. An IF node catches empty results, so the workflow skips the insert instead of failing.

You do not have to build this from scratch. The n8n template library hosts thousands of community workflows, and starting from one that almost matches your case beats a blank canvas. Swap in your own credentials, run a test, and adjust from there.

How to Build Your Own API Endpoint with Webhook Nodes

A Webhook node plus a Respond to Webhook node give you a working API endpoint inside a single workflow. This flips the usual direction: instead of n8n calling other services, other services call your n8n.

The pattern takes three nodes. The Webhook node listens at a URL and accepts incoming requests. A middle node holds your logic. The Respond to Webhook node sends the answer back to whoever called you.

Two settings trip up beginners, so learn them early.

• Test versus production URLs. The Webhook node gives you two URLs. The test URL only works while you watch the editor with "Listen for test event" active. The production URL only works after you activate the workflow. Sending requests to the wrong one is the most common reason a new endpoint looks dead.
• The response setting. You control when the caller gets an answer. Respond immediately when the caller does not need to wait, or respond when the last node finishes, if the caller needs the result of your logic.

This replaces a surprising amount of backend work. You can prototype an internal service in minutes and extend it later without touching a server. See the Webhook node docs for authentication options and response settings.

Using the n8n API with AI Agents

The n8n API and MCP server let AI agents create and manage workflows for you. n8n's docs walk you through connecting coding agents like Claude Code and Codex to n8n's built-in MCP server, which gives the agent structured access to your instance. It helps to keep three interfaces straight. The public API is the HTTP calls you make, the CLI runs in your terminal to control the instance, and the MCP server is the piece built for AI agents to connect to. Give an agent a scoped key, and it gains controlled access to your automation, while your credentials stay in n8n's credential store.

Read: n8n Agents & Workflows: Build Guide With Tips & Examples

Why AI Users Are Learning the n8n API

An AI assistant on its own can draft text and answer questions, but it cannot touch your other tools. n8n is the bridge. When you understand the API, you can hand an agent real capabilities while keeping the boundaries tight through a scoped key. Professionals who add this skill find that it stretches what a single AI subscription can do, because one agent can drive dozens of connected services.

Read: The Different Types of AI Agents & What You Need to Know About Each

Example: An AI Agent That Manages Your Workflows

Here is what this looks like in practice, without any code. Imagine a morning routine you delegate to an agent:

1. The agent requests your workflow list and checks each status.
2. It pulls recent executions and spots a workflow with a rising error rate.
3. It calls the deactivate endpoint to stop the bleeding.
4. It posts a short update to your team channel with the workflow name and error details.

Every step is one API request that you learned in this guide. The agent just chains them. That is the honest picture of AI agents today. They are not magic. They are fast hands on the same endpoints you can call yourself, which is why learning those endpoints first makes you better at directing them.

Read: 20 Examples of AI Agents and Workflows: Real Use Cases by Business Function

Common n8n API Errors and How to Fix Them

Most failed requests come down to four causes. Match your status code to this table before you start digging.

Two habits shorten your debugging. Read the response body because n8n usually explains what went wrong in plain text. And check that your Content-Type header reads application/json on every POST, since a missing header makes valid JSON look malformed to the server.

A Note on Pagination and Rate Limits

List endpoints paginate. The default page size is 100 results, and the maximum you can request is 250. A response with more than one page includes a nextCursor value that fetches the next page, so you loop until the cursor comes back empty. (The executions endpoint is the exception noted above.)

Rate limits depend on hosting. Self-hosted Community has no enforced request-rate limit. Cloud plans can throttle large bursts and enforce per-plan execution limits. Limits change over time, so confirm current numbers on the n8n rate-limit docs before you build a high-volume integration.

Why Learning the n8n API Pays Off

Learning the n8n API is a small project with outsized returns. The same core concepts carry over to every tool you will automate for the rest of your career, so the hours you put in now keep paying off long after this guide. Employers increasingly list automation and AI workflow skills in roles far outside engineering, and the people who can connect an AI agent to real business systems stand out in any applicant pool.

Turn API Skills into Career Skills

Leland can help you get there faster. Our AI expert coaches will work with you one-on-one to build a plan and apply these skills to portfolio-ready projects. If you want to go further, the Leland AI Builder program is a live, cohort-based program that takes you from knowledge worker to shipping real agents and workflows in 6 to 10 weeks, taught by operators who do this work. You can also drop into our livestreams for a lower-commitment way to learn as the tooling changes, or join a bootcamp to build alongside others. Pick the path that fits where you are.

See: The 5 Best AI Agents Courses & Bootcamps to Learn Automation (2026)

Read these next:

• n8n vs. Zapier for AI Agents & Workflows: Pros/Cons & Which is Better for You
• The 5 Best n8n Alternatives for AI Agents & Workflows
• How to Build an AI Agent With OpenAI/ChatGPT
• The Top 10 AI Agent Builders to Try in 2026
• The 3 Most Important Principles of Building AI Agents
• Agentic AI vs. AI Agents: Differences & What You Need to Know

FAQ

Is the n8n API free to use?

• The API comes with paid Cloud plans and self-hosted instances. It is not available on the free trial. Self-hosting the Community edition on your own server gives you API access without a Cloud subscription, in exchange for taking on the hosting work.

Do I need to know how to code?

• Less than you might think. Copying and adjusting cURL examples covers most tasks in this guide. Real code helps when you chain many requests together, but plenty of users manage their instances with nothing beyond the examples above.

Can I create workflows with the API?

• Yes. A POST request to the workflows endpoint creates a workflow from JSON. Most users export an existing workflow first and use it as a template, since writing node JSON from scratch is slow and error-prone.

Where can I watch a video walkthrough?

• n8n maintains a video channel on YouTube with tutorials on the editor, webhook nodes, and API basics. Community creators also publish walkthroughs. Watching one build alongside this guide helps if you learn better by seeing each click.