N8N.Api

A strongly-typed .NET client for the n8n Public API, generated from the official OpenAPI specification. One typed interface per resource (IWorkflowApi, IExecutionApi, ITagsApi, IUserApi, ...)

Installation

dotnet add package N8N.Api

Setup

The simplest way to register the client is the AddN8NApi(baseUrl, apiKey) extension. It wires up the typed API clients and configures X-N8N-API-KEY authentication for you.

ASP.NET Core (Program.cs)

using N8N.Api.Extensions;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddN8NApi(
    baseUrl: builder.Configuration["N8N:BaseUrl"]!,
    apiKey:  builder.Configuration["N8N:ApiKey"]!);

builder.Services.AddControllers();

var app = builder.Build();
app.MapControllers();
app.Run();

The same extension is available on IHostBuilder for generic hosts / workers:

var host = Host.CreateDefaultBuilder(args)
    .AddN8NApi(baseUrl: "https://n8n.example.com/api/v1/", apiKey: "<your api key>")
    .Build();

Advanced setup

If you need to customize the HttpClient (e.g. add Polly policies, change the token provider, or register custom JSON converters), drop down to the underlying AddApi / ConfigureApi extensions:

builder.Services.AddApi(options =>
{
    options.AddTokens(new ApiKeyToken(
        value: builder.Configuration["N8N:ApiKey"]!,
        header: ClientUtils.ApiKeyHeader.X_N8N_API_KEY,
        prefix: ""));

    options.AddApiHttpClients(
        client => client.BaseAddress = new Uri(builder.Configuration["N8N:BaseUrl"]!),
        builder => builder
            .AddRetryPolicy(2)
            .AddTimeoutPolicy(TimeSpan.FromSeconds(30)));
});

Extension	Lives on	Use when
AddN8NApi(baseUrl, apiKey)	IServiceCollection / IHostBuilder	You just need the basics
AddApi(options => ...)	IServiceCollection	You need to customize the HttpClient, token provider, or JSON options
ConfigureApi((ctx, services, options) => ...)	IHostBuilder	Same as above, but inside a generic host builder

Configuration (appsettings.json)

{
  "N8N": {
    "BaseUrl": "https://n8n.example.com/api/v1/",
    "ApiKey": "<your n8n api key>"
  }
}

Usage

Once registered, inject any of the I*Api interfaces into your services or controllers.

Example: workflow controller

using Microsoft.AspNetCore.Mvc;
using N8N.Api.Api;
using N8N.Api.Client;
using N8N.Api.Model;

[ApiController]
[Route("workflows")]
public class WorkflowsController(IWorkflowApi workflows) : ControllerBase
{
    [HttpGet]
    public async Task<ActionResult<WorkflowList>> List(CancellationToken ct)
    {
        var response = await workflows.WorkflowsGetAsync(
            active: new Option<bool>(true),
            cancellationToken: ct);

        // Ok() returns the deserialized 200 payload or throws if the response wasn't 2xx.
        return Ok(response.Ok());
    }

    [HttpGet("{id}")]
    public async Task<ActionResult<Workflow>> Get(string id, CancellationToken ct)
    {
        var response = await workflows.WorkflowsIdGetOrDefaultAsync(id, cancellationToken: ct);

        // *OrDefault variants return null instead of throwing on non-2xx.
        var workflow = response?.Ok();
        return workflow is null ? NotFound() : Ok(workflow);
    }

    [HttpPost("{id}/activate")]
    public async Task<IActionResult> Activate(string id, CancellationToken ct)
    {
        var response = await workflows.WorkflowsIdActivatePostAsync(id, cancellationToken: ct);
        return Ok(response.Ok());
    }
}

Response patterns

Every operation has two variants:

• XxxAsync(...) — returns IXxxApiResponse. Call .Ok() to get the typed payload; it throws if the HTTP response wasn't successful.
• XxxOrDefaultAsync(...) — returns IXxxApiResponse?. Returns null on failure instead of throwing. Useful for "not found" style flows.

Optional query/body parameters use Option<T> — pass default to omit, or new Option<T>(value) to send.

Regenerating the client

The client is regenerated from api/openapi.yaml via Generate.ps1. The script preprocesses the spec to strip PascalCase $ref-only aliases that collide with their lowercase originals (otherwise the C# generator skips emitting those model classes).

./Generate.ps1

Requires openapi-generator-cli on the PATH.