n8n API Workflow Tutorial: Build Your First Integration From Scratch (2026)

The fastest way to build your first n8n API workflow in 2026 is: deploy n8n 2.x via Docker Compose, wire an HTTP Request node to a Schedule Trigger, parse the JSON response with a Set node, route results through an IF node, and activate. The entire build takes under 30 minutes. Self-hosted n8n costs zero per execution, supports 400+ integrations, and includes an AI Agent node for chaining LLM calls with tool accesspart of n8n 2.x since December 2026.

“A workflow that takes 30 minutes to build in n8n might take 4-6 hours to build properly as a custom script (including error handling, logging, monitoring, and deployment).“

n8n vs. the Alternatives: Why This Matters in 2026

Zapier charges per task. Make throttles operations. Custom scripts accumulate technical debt. n8n 2.x changes the equation with unlimited self-hosted executions, visual debugging, built-in retry logic, and an AI Agent node. Here is how the platforms compare using verified 2026 data:

Feature	n8n 2.x (Self-Hosted)	Zapier	Make
Pricing model	Free, unlimited executions	$29.99/mo (750 tasks)	$10.59/mo (10,000 ops)
Total integrations	400+	7,000+	1,800+
Custom code	JavaScript + Python (Code node)	JavaScript (Code step)	Limited scripting
Self-hosting	Yes (Docker, npm)	No	No
AI Agent node	Native, with tool-calling	Basic AI actions	Basic AI modules
Database support	PostgreSQL, MySQL, MongoDB, Redis	None native	None native
Source code access	Fair-code (public GitHub)	Closed source	Closed source
SSO / Enterprise	OIDC, SAML, RBAC	Enterprise plan only	Enterprise plan only

The trade-off is clear: Zapier has more pre-built integrations but charges per execution. n8n compensates with its HTTP Request node (calls any REST API) and Code nodes (arbitrary JavaScript or Python). For technical teams in 2026, n8n’s unlimited execution model justifies the switch.

What You Will Build

This tutorial walks through a weather-monitoring workflow that fetches live data from OpenWeatherMap, parses the JSON response, applies conditional logic, and sends a Slack alert when thresholds are breached. The patternfetch, parse, decide, notifypowers most real-world API workflows.

Step 1: Deploy n8n 2.x

n8n 2.x ships with security-by-default and PostgreSQL support. The recommended deployment is Docker Compose with PostgreSQL.

services:
  postgres:
    image: postgres:16-alpine
    environment:
      POSTGRES_USER: n8n
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
      POSTGRES_DB: n8n
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U n8n"]
  n8n:
    image: n8nio/n8n:latest
    ports: ["5678:5678"]
    environment:
      DB_TYPE: postgresdb
      DB_POSTGRESDB_HOST: postgres
      DB_POSTGRESDB_DATABASE: n8n
      DB_POSTGRESDB_USER: n8n
      DB_POSTGRESDB_PASSWORD: ${POSTGRES_PASSWORD}
      N8N_ENCRYPTION_KEY: ${N8N_ENCRYPTION_KEY}
    volumes:
      - n8n_data:/home/node/.n8n
    depends_on:
      postgres:
        condition: service_healthy

Generate the encryption key with openssl rand -hex 32 and store it in a .env file. The N8N_ENCRYPTION_KEY encrypts all stored credentials. Losing this key means losing access to every saved API token, OAuth2 refresh token, and password. Back it up.

Start the stack: docker compose up -d. Navigate to http://localhost:5678 and create your owner account.

For quick local testing, install via npm: npm install n8n -g && n8n start. This uses SQLite and is fine for learning but not for production.

Step 2: Add a Schedule Trigger

Every n8n workflow begins with exactly one trigger node. Triggers define when the workflow executeson a cron schedule, in response to a webhook, or manually.

1. Click “Add Workflow” in the n8n dashboard.
2. Search “Schedule Trigger” and drag it onto the canvas.
3. Set the trigger to run every hour (0 * * * *).
4. Name the node “Hourly Weather Check.”

The Schedule Trigger fires at a fixed interval or cron expression.

Step 3: Wire the HTTP Request Node

The HTTP Request node handles all outbound API communication. It supports GET, POST, PUT, PATCH, DELETE, custom headers, query parameters, JSON/form-data/binary bodies, and five auth methods: API key, Bearer token, Basic Auth, OAuth2, and client certificates.

1. Drag an “HTTP Request” node onto the canvas and connect it to the Schedule Trigger.
2. Set Method to GET.
3. Set URL to: https://api.openweathermap.org/data/2.5/weather?q=London&units=metric&appid=YOUR_API_KEY
4. Under Authentication, select “Generic Credential Type” ? “Header Auth,” then create a credential with your OpenWeatherMap API key.
5. Set Options ? Timeout to 30000 (30 seconds).

Never hard-code credentials in node fields. Use n8n’s built-in credential manager, which encrypts all secrets at rest using AES-256 under the N8N_ENCRYPTION_KEY.

Step 4: Parse the JSON Response

n8n automatically parses JSON responses. The parsed data is available as $json in expressions. Use a Set node to extract only the fields you need:

1. Add a “Set” node connected to the HTTP Request output.
2. Configure these fields using n8n expressions:
   • temperature ? {{ $json.main.temp }}
   • condition ? {{ $json.weather[0].description }}
   • city ? {{ $json.name }}
   • humidity ? {{ $json.main.humidity }}
   • timestamp ? {{ $now.toISO() }}
3. Set the mode to “Keep Only Set Fields” to discard unused data.
4. Name the node “Extract Weather Data.”

n8n expressions use JavaScript template syntax in double curly braces. $json refers to the current item’s JSON data; $now returns the current DateTime. Chain methods like $now.format('yyyy-MM-dd HH:mm').

Click “Test step” on the Set node to verify the output.

Step 5: Route with Conditional Logic

The IF node splits execution into two branches based on a comparison.

1. Add an “IF” node connected to the Set node.
2. Set Value 1 to {{ $json.temperature }}, Operation to “Larger,” and Value 2 to 35.

One branch sends alerts (temperature > 35?�C); the other terminates the workflow.

Step 6: Send the Alert

On the IF node’s true branch, add a Slack node:

1. Add a “Slack” node connected to the IF node’s true output.
2. Create a Slack credential using an OAuth2 bot token.
3. Set Resource to “Message,” Operation to “Send,” and select the target channel.
4. Compose the message text:

Weather Alert: {{ $json.city }} is {{ $json.temperature }}�C ({{ $json.condition }})
Humidity: {{ $json.humidity }}%
Recorded: {{ $json.timestamp }}

Test the Slack node by clicking “Test step.” Verify the message appears in your Slack channel before proceeding.

Step 7: Add Error Handling

Silent failures are the most dangerous kind. n8n 2.x provides three layers of error handling:

• Retry on Fail: Each node can be configured to retry automatically (3 retries, 5-second delay recommended for API calls).
• Error Output: Every node exposes an error output connector. Wire it to a Slack or email node that alerts your team.
• Error Workflow: A dedicated error-handling workflow invoked when any node fails unhandled. Configure it in Workflow Settings ? Error Workflow.

Configure all three layers for production. At minimum, wire the HTTP Request node’s error output to a Slack notification so you detect API outages before users do.

Common error codes and their meanings:

• 400 Bad request: check URL and parameters
• 401 Unauthorized: API key is missing or expired
• 403 Forbidden: API key lacks required scope
• 404 Not found: endpoint URL or resource ID is wrong
• 429 Rate limited: enable Batching and Retry on Fail in HTTP Request options
• 500 Server error: retry with backoff; alert if persistent

Step 8: Activate and Monitor

1. Click “Test Workflow” to run the full pipeline end-to-end.
2. Inspect execution data at each node in the bottom panel.
3. Fix any expression errors or credential issues.
4. Toggle the “Active” switch (top-right corner) to enable the workflow.

Activating a workflow makes it respond to triggers. Inactive workflows ignore schedules, webhooks, and all triggers. Test mode (/webhook-test/) and production (/webhook/) use different URLsshare only the production URL externally.

Production Readiness Checklist

Before marking a workflow as done, verify these items:

• Credentials stored in n8n credential manager (not hard-coded in nodes)
• API rate limits understood and batching/retry configured
• Error output of the HTTP Request node wired to a notification
• Error Workflow configured at the workflow level
• All nodes descriptively named (not “HTTP Request 4”)
• Workflow description includes: purpose, owner, APIs used, alert destination, last reviewed date
• Tested with both success and failure scenarios
• N8N_ENCRYPTION_KEY backed up securely
• Sensitive data excluded from execution logs

Adding AI to Your Workflow (n8n 2.x)

n8n 2.x ships with a native AI Agent node that connects to LLM providers (OpenAI, Anthropic Claude, Google Gemini) and gives the model access to toolssub-workflows or nodes it can invoke to complete tasks. This is the same agentic pattern used by LangChain, implemented visually.

To add AI to the weather workflow, insert an AI Agent node between the Set and IF nodes:

1. Add an “AI Agent” node on the canvas.
2. Connect an OpenAI chat model sub-node (or Anthropic Claude).
3. Set the system prompt:

Analyze the weather data and return JSON with:
- risk_level: "low", "moderate", or "high"
- recommendation: a 1-sentence actionable suggestion
- alert_needed: true/false

4. Replace the IF node’s condition with {{ $json.alert_needed }}.
5. The AI Agent now decides whether to alert based on contextual reasoning, not just a numeric threshold.

The AI Agent node supports tool-calling: grant it access to a “Lookup Historical Weather” workflow, a “Check Team Calendar” node, or a “Create Incident Ticket” action, and it chooses which tools to invoke based on the input data.

Debugging Failed API Workflows

When an API workflow fails, inspect the execution log in this order:

• Node input/output: Does the upstream node produce the expected data structure?
• HTTP status code: Is it a 4xx (your fault) or 5xx (their fault)?
• Response body: Does the API return an error message? Is the JSON schema different from what you expected?
• Expression references: Are expressions using correct node names?
• Credentials: Has the API key expired?
• Multiple items: Did a previous node return an array causing N items instead of 1?
• Timeout: Is 60 seconds too short?

The execution panel in n8n’s editor shows the exact data at every node, eliminating guesswork.

FAQ

Can n8n handle API authentication in 2026?

Yes. n8n 2.x supports API key, Bearer token, Basic Auth, OAuth2 (with automatic token refresh), and client certificate authentication. Credentials are encrypted at rest with AES-256 using the N8N_ENCRYPTION_KEY.

How do I handle paginated APIs?

Enable automatic pagination in the HTTP Request node’s options. n8n supports link-header, page-number, and cursor-based pagination.

What happens when an API call times out?

Configure the timeout in HTTP Request options (default: 60 seconds). n8n then routes the failure to the node’s error output. Enable Retry on Fail (3 retries, 5-second delay) for transient errors.

Can I chain multiple API calls in one workflow?

Yes. Connect multiple HTTP Request nodes sequentially, or use parallel branches for independent API calls. The Merge node combines results from parallel branches. For sequential calls where call N+1 depends on call N’s output, use expressions like {{ $('First API').json.id }}.

Is n8n actually free?

Self-hosted n8n is free with unlimited workflow executions under the fair-code license. Enterprise features (SSO, audit logging, dynamic credentials) require a paid license. n8n Cloud offers a free tier with limited executions.

What is n8n 2.x and should I upgrade?

n8n 2.0 released in December 2026, introducing security-by-default, PostgreSQL as recommended database, improved AI Agent node, enhanced OIDC/SAML support, and significant reliability improvements for large datasets. If you are on n8n 1.x, follow the official migration guide.

Key Takeaways

• HTTP Request node handles all API communication with support for five auth methods and automatic pagination
• Set node with n8n expressions extracts specific JSON fields for downstream processing
• IF node enables conditional branching based on parsed data values
• AI Agent node (n8n 2.x) adds LLM-powered decision-making and tool-calling to any workflow
• Error handling is not optionalwire error outputs, configure retry-on-fail, and set up an Error Workflow
• Credentials must use the n8n credential manager; never hard-code API keys in node fields
• Docker Compose with PostgreSQL is the recommended production deployment; n8n start with SQLite is fine for learning

Sources

• n8n Docs: Create and Run Workflows
• n8n Docs: HTTP Request Node Common Issues
• n8n Docs: Error Handling
• Tech Insider: n8n Workflow Automation Tutorial 2026
• DEV Community: Top 10 n8n Workflows 2026
• n8n Docs: Integrations (400+ nodes)
• n8n Docs: Advanced AI / AI Agent Node