L'API REST de n8n : piloter son instance et ses workflows par programme

L'interface de n8n suffit tant qu'on gère cinq workflows à la main. Mais dès que l'instance grossit — des dizaines de workflows, plusieurs environnements, une équipe qui déploie régulièrement — cliquer dans l'éditeur pour tout administrer devient un goulot d'étranglement. C'est exactement le rôle de l'API REST publique de n8n : tout ce que vous faites dans l'interface d'administration (lister, activer, exporter, surveiller), vous pouvez le faire par programme, depuis un script, un pipeline CI/CD… ou depuis un autre workflow n8n.

Créer une clé API : Settings → n8n API

L'API publique s'authentifie par clé, à générer dans Settings → n8n API avec le bouton Create an API key. Deux choses à savoir dès la création :

• La clé n'est affichée qu'une seule fois. Copiez-la immédiatement dans un gestionnaire de secrets ou une variable d'environnement — si vous la perdez, il faudra en générer une nouvelle.
• Elle hérite des droits du compte qui la crée. Sur la plupart des instances self-hosted, cela revient à des droits d'administration étendus sur les workflows, les exécutions et les credentials.

Chaque requête vers l'API porte ensuite cette clé dans le header dédié X-N8N-API-KEY :

curl -s "https://n8n.exemple.fr/api/v1/workflows" \
  -H "X-N8N-API-KEY: $N8N_API_KEY"

Notez le $N8N_API_KEY : la clé vit dans une variable d'environnement, jamais en dur dans le script. Notre guide des variables d'environnement n8n détaille les bonnes pratiques pour gérer ce type de secret proprement, côté instance comme côté scripts.

Les endpoints principaux

L'API est versionnée sous le préfixe /api/v1 et suit une logique REST classique : des ressources (workflows, exécutions, credentials), des verbes HTTP (GET pour lire, POST pour créer, DELETE pour supprimer), des réponses JSON. Ce n'est pas un hasard : ce style architectural a été formalisé par Roy Fielding et Richard Taylor dans « Principled Design of the Modern Web Architecture » (ACM Transactions on Internet Technology, 2002 — voir sur Google Scholar), l'article fondateur dont s'inspirent la quasi-totalité des API web modernes, celle de n8n comprise. Concrètement, cela signifie qu'un développeur qui a déjà consommé une API REST quelconque s'y retrouve immédiatement.

Les trois familles de ressources qui couvrent l'essentiel des besoins :

• /api/v1/workflows — lister les workflows de l'instance, récupérer la définition JSON complète d'un workflow (ses nodes, ses connexions, ses paramètres), en créer, en modifier, en supprimer, et surtout les activer ou désactiver via des sous-routes dédiées.
• /api/v1/executions — consulter l'historique des exécutions, avec des filtres (notamment par statut et par workflow) qui permettent d'isoler les échecs récents.
• /api/v1/credentials — créer et supprimer des credentials par programme. Point important : par conception, l'API ne renvoie pas les secrets déchiffrés — on peut provisionner un credential, pas relire son contenu.

D'autres ressources existent selon la version et l'édition de n8n (tags, utilisateurs, variables…), mais ces trois-là suffisent pour industrialiser la majorité des opérations courantes.

Cas d'usage no 1 : activer ou désactiver des workflows en masse

Scénario classique : une maintenance de la base de données est prévue, et vous voulez couper proprement les trente workflows planifiés de l'instance plutôt que de les laisser échouer en boucle. À la main, c'est trente allers-retours dans l'interface. Par l'API, c'est une boucle :

# Lister les workflows actifs, puis désactiver chacun d'eux
curl -s "https://n8n.exemple.fr/api/v1/workflows?active=true" \
  -H "X-N8N-API-KEY: $N8N_API_KEY" \
  | jq -r '.data[].id' \
  | while read id; do
      curl -s -X POST "https://n8n.exemple.fr/api/v1/workflows/$id/deactivate" \
        -H "X-N8N-API-KEY: $N8N_API_KEY"
    done

Le même pattern en sens inverse réactive tout après la maintenance. C'est aussi la brique de base d'un « kill switch » : un script qui coupe tous les workflows d'un tag donné en cas d'incident sur une API tierce.

Cas d'usage no 2 : exporter tous les workflows pour sauvegarde

L'endpoint des workflows renvoie la définition JSON complète de chaque workflow — exactement ce que produit l'export manuel depuis l'éditeur. Un script de quelques lignes peut donc récupérer tous les workflows chaque nuit et les écrire dans un dossier, un fichier par workflow. Combiné à un git commit automatique, on obtient un historique versionné de toute l'instance sans aucune action manuelle.

C'est le complément naturel de l'approche décrite dans notre guide sauvegarder et versionner ses workflows avec Git : Git fournit l'historique et la traçabilité, l'API fournit l'automatisation de la collecte. Attention à un point : les credentials ne sont pas inclus dans les exports (et c'est tant mieux) — la sauvegarde des secrets suit un circuit séparé, détaillé dans notre article sur la sécurisation des credentials.

Cas d'usage no 3 : surveiller les échecs depuis un outil externe

L'endpoint des exécutions, filtré sur le statut « error », transforme n8n en source de métriques pour votre outillage de supervision existant. Un script appelé toutes les cinq minutes par votre système de monitoring compte les exécutions en échec récentes et déclenche une alerte au-delà d'un seuil :

curl -s "https://n8n.exemple.fr/api/v1/executions?status=error&limit=20" \
  -H "X-N8N-API-KEY: $N8N_API_KEY"

L'intérêt par rapport à un Error Workflow interne : la surveillance vit en dehors de l'instance. Si n8n lui-même est tombé, l'appel API échoue et votre outil de monitoring le voit — là où un Error Workflow hébergé sur l'instance malade ne préviendra jamais personne. Les deux approches se complètent, comme détaillé dans notre guide sur la supervision d'une instance n8n.

Cas d'usage no 4 : déployer un workflow de dev vers prod

Avec deux instances (une de développement, une de production), l'API permet un déploiement scriptable : on récupère la définition JSON du workflow sur l'instance dev, on ajuste ce qui doit l'être (identifiants de credentials, URLs), puis on la pousse sur l'instance prod — création si le workflow n'existe pas encore, mise à jour sinon — avant de l'activer. Intégré à un pipeline CI/CD, ce script transforme le déploiement d'un workflow en un processus reproductible, déclenché par un merge plutôt que par un copier-coller manuel entre deux onglets. La mise en place de cette architecture à deux instances est couverte dans notre guide des environnements dev et prod pour n8n.

Cas d'usage no 5 : piloter n8n… depuis n8n

Rien n'interdit à un workflow n8n d'appeler l'API de sa propre instance avec un node HTTP Request. C'est même un pattern étonnamment utile : un workflow planifié chaque nuit qui exporte tous les autres workflows vers un stockage externe, un workflow de « ménage » qui désactive les workflows non exécutés depuis 90 jours après notification, ou un tableau de bord interne qui agrège le statut des exécutions. Créez un credential de type Header Auth avec le header X-N8N-API-KEY (plutôt que de coller la clé dans le node), pointez le node HTTP Request vers http://localhost:5678/api/v1/... si le workflow tourne sur la même machine, et l'instance devient capable de s'auto-administrer.

API publique et webhooks : deux portes, deux niveaux de privilège

La confusion est fréquente chez les débutants : « j'ai déjà des webhooks, pourquoi une API ? ». Parce que les deux n'ont ni le même rôle ni la même portée :

• Un webhook déclenche un workflow précis. Sa portée se limite à ce que ce workflow fait, son authentification se configure node par node, et il est pensé pour être exposé à des systèmes tiers (voir notre guide complet des webhooks n8n).
• L'API publique administre l'instance entière : n'importe quel workflow peut être lu, modifié, supprimé ou désactivé, les credentials manipulés, l'historique consulté.

En clair : donner une URL de webhook à un partenaire est un acte banal ; donner une clé API revient à confier les clés de la salle des machines. Cela impose une hygiène stricte : clé stockée en variable d'environnement, jamais dans un dépôt Git ni dans le paramètre d'un node ; accès réseau à l'instance restreint autant que possible (reverse proxy avec liste blanche d'IP, VPN, ou au minimum HTTPS obligatoire) ; rotation de la clé en cas de départ d'un membre de l'équipe ; et une clé dédiée par usage (une pour le backup, une pour le monitoring) pour pouvoir révoquer finement.

Pièges fréquents

• Coller la clé API en dur dans un script ou un workflow. Elle finit dans Git, dans les logs ou dans un export partagé. Une variable d'environnement côté script, un credential Header Auth côté n8n : jamais autre chose.
• Oublier la pagination. L'endpoint des workflows comme celui des exécutions renvoient les résultats par pages, avec un curseur pour demander la suite. Un script d'export qui ignore la pagination sauvegarde silencieusement une fraction de l'instance et donne une fausse impression de sécurité.
• Confondre déclencher et administrer. Utiliser la clé API pour déclencher un traitement métier qu'un simple webhook aurait couvert, c'est exposer des privilèges d'administration là où une porte étroite suffisait.
• Pousser un workflow de dev en prod sans ajuster les références. Les identifiants de credentials diffèrent d'une instance à l'autre : un déploiement API qui ne les remappe pas produit un workflow actif… branché sur les mauvais comptes, ou sur rien.
• Traiter la réponse de l'API comme stable entre versions. Le schéma général bouge peu, mais les champs exacts peuvent évoluer avec les versions de n8n : un script robuste vérifie la présence des champs qu'il consomme au lieu de les supposer.

Pour aller plus loin

L'API publique est la brique qui fait passer une instance n8n du statut d'outil individuel à celui d'infrastructure d'équipe : sauvegardes automatisées, déploiements reproductibles, supervision externe. L'étape suivante logique, c'est la traçabilité de ce qui s'exécute réellement : le Pack Conformité & Audit (149 €) fournit des workflows prêts à l'emploi pour journaliser et tracer ce qui se passe dans vos automatisations une fois l'instance industrialisée — l'audit trail qui complète naturellement le pilotage par API. Et si votre instance n'est pas encore self-hosted, commencez par notre guide d'installation de n8n avec Docker : c'est le socle sur lequel tout le reste s'appuie.