Notion API : le guide complet pour automatiser Notion

L’API de Notion permet de connecter vos bases de données, pages et vues à des milliers d’applications externes, avec ou sans code. Depuis la version 2026-03-11 et l’arrivée du protocole MCP, elle transforme Notion en plateforme de données programmable, accessible aussi bien aux développeurs qu’aux utilisateurs no-code.

Avec plus de 100 millions d’utilisateurs dans le monde, 4 millions de clients payants et un chiffre d’affaires estimé à 600 millions de dollars fin 2025 (500 millions annualisés dès septembre 2025 selon CNBC), Notion est la plateforme de productivité de référence. L’API est le moteur de cet écosystème : elle alimente les intégrations tierces, le serveur MCP hébergé, et les agents IA natifs lancés avec Notion 3.0.

J’utilise l’API de Notion depuis sa sortie en bêta en mai 2021. Après cinq ans d’utilisation intensive sur des projets personnels et professionnels, et après avoir testé chaque mise à jour majeure, voici le guide complet que j’aurais aimé avoir au départ.

Retrouvez ce sujet en vidéo :

Qu’est-ce que l’API de Notion et à quoi sert-elle ?

Une API (Application Programming Interface) est une interface qui permet à deux logiciels de communiquer entre eux. L’API de Notion expose les opérations de lecture, création, modification et suppression sur vos pages, bases de données, blocs et désormais vues.

Concrètement, cela signifie que vous pouvez automatiser des tâches répétitives. Chaque fois qu’un formulaire Typeform est rempli, les réponses arrivent dans votre base Notion. Votre Google Agenda se synchronise en temps réel avec une base de données via Notion Calendar. Un agent IA externe peut consulter vos pages et générer du contenu directement dans votre workspace.

L’API transforme Notion d’un outil de notes en un hub central de données connecté à l’ensemble de votre stack. Toutes les requêtes passent par https://api.notion.com en HTTPS, avec un format JSON standardisé et des propriétés en snake_case.

Les trois versions majeures de l’API : de 2021 à 2026

Version initiale (mai 2021) : les fondations

L’API a été lancée en bêta publique le 13 mai 2021. Elle permettait les opérations de base : lire et écrire dans les bases de données, créer des pages, et gérer les blocs de contenu. J’ai fait un live lors de cette sortie, suivi par des centaines de personnes.

À l’époque, les possibilités étaient limitées : pas de support pour tous les types de blocs, pas de gestion des fichiers, et une authentification parfois complexe. Mais le potentiel était déjà évident pour quiconque travaillait avec des outils no-code.

Version 2025-09-03 : les Data Sources

C’est la mise à jour la plus structurante depuis le lancement. Notion a introduit le concept de « Data Sources », qui sépare la base de données (le conteneur) de la source de données (la table). Cette architecture permet à une seule base de contenir plusieurs sources de données liées.

Pour les développeurs et les outils d’automatisation, cela implique un changement majeur : il faut désormais récupérer un data_source_id avant de créer des pages ou de définir des relations. Les intégrations qui n’ont pas migré risquent des erreurs sur les bases multi-sources.

Version 2026-03-11 : la simplification (version actuelle)

La dernière version en date, sortie le 11 mars 2026, apporte trois changements notables.

Le SDK officiel JavaScript @notionhq/client en version 5.12.0 prend en charge cette version. La version 5.15.0, sortie le 25 mars 2026, ajoute le support des blocs tab, des emojis personnalisés et des icônes natives. Je recommande de migrer progressivement vos intégrations existantes.

L’API Views : 8 nouveaux endpoints pour vos vues

Notion a lancé l’API /v1/views le 19 mars 2026, avec huit nouveaux endpoints. Vous pouvez désormais créer, modifier et interroger des vues de bases de données par programmation.

L’intérêt principal est de pouvoir interroger une vue en utilisant ses filtres et tris déjà configurés dans Notion. Plutôt que de reconfigurer les filtres dans votre code, vous interrogez directement la vue. C’est particulièrement utile pour construire des tableaux de bord externes basés sur vos données Notion, ou pour alimenter un dashboard Notion depuis un outil tiers.

Le Markdown Content API : lire et écrire en markdown

Avec la sortie de Notion 3.4 le 26 mars 2026, Notion a introduit le Markdown Content API. Cette interface permet aux outils compatibles de lire et écrire du contenu Notion directement en markdown, sans passer par la structure hiérarchique JSON des blocs.

Selon le blog technique de Notion, cette approche offre une « densité de contenu efficace par token LLM », ce qui réduit le nombre d’appels API par rapport au format bloc classique. En pratique, cela simplifie les intégrations qui manipulent du texte : éditeurs, CMS, pipelines de publication.

Le Markdown Content API supporte également le « Notion-flavored Markdown », un dialecte enrichi qui prend en charge les blocs spécifiques à Notion : callouts, colonnes, pages imbriquées et bases de données.

Notion et l’intelligence artificielle : MCP, agents et Workers

L’intelligence artificielle dans Notion a considérablement évolué depuis 2023. Avec le serveur MCP, les agents natifs et les Workers, l’API est désormais au centre de cette stratégie IA.

Le serveur MCP hébergé de Notion

Le protocole MCP (Model Context Protocol), lancé par Anthropic en novembre 2024, est un standard ouvert qui permet aux outils IA d’interagir avec des services externes de manière structurée. Notion a adopté ce protocole en 2025 et héberge désormais son propre serveur MCP.

La différence avec les serveurs MCP communautaires est importante. Le serveur hébergé de Notion utilise une authentification OAuth en un clic, stocke les tokens côté serveur, et supporte deux protocoles de transport : streamable HTTP et SSE (Server-Sent Events). Aucune installation locale n’est nécessaire.

Les outils IA compatibles incluent Claude Code, Cursor, VS Code, ChatGPT et d’autres assistants compatibles MCP. Concrètement, depuis votre IDE ou votre assistant IA, vous pouvez :

• Rechercher dans votre workspace Notion et plus de 10 applications connectées
• Créer des pages optimisées pour les workflows conversationnels
• Mettre à jour des pages existantes
• Générer de la documentation (PRD, specs techniques, notes d’architecture)
• Gérer des tâches avec suivi automatique du statut

Pour les entreprises, les workspaces Enterprise peuvent suivre toute l’activité MCP dans les logs d’audit et interroger plusieurs bases de données simultanément.

Les agents IA Notion (Notion 3.0 et 3.4)

Depuis septembre 2025, Notion a lancé sa version 3.0 avec les agents IA natifs. Ces agents exécutent des tâches autonomes : construire un plan de projet, compiler des retours utilisateurs, rédiger des rapports, ou mettre à jour des centaines d’entrées en une seule commande. J’ai rédigé un guide complet sur les agents Notion qui détaille leur fonctionnement.

Avec Notion 3.4 (mars 2026), les agents gagnent la capacité de générer des images, des diagrammes, des graphiques et des slides directement dans vos documents. Le dashboard view, disponible sur les plans Business et Enterprise, permet de décrire un tableau de bord à l’agent qui le crée automatiquement.

Workers : du code personnalisé pour vos agents

Les Workers sont un environnement d’exécution de code TypeScript intégré à Notion, lancé en alpha en mars 2026. Vous écrivez du code personnalisé que les agents IA de Notion exécutent pour des tâches spécifiques : appeler des API externes (Twilio, Discord, GitHub), effectuer des calculs complexes, ou transformer des données. Contrairement aux custom skills qui utilisent des instructions en langage naturel, les Workers offrent une liberté de programmation complète, côté serveur.

Utiliser l’API Notion avec Python

Le SDK Python communautaire notion-client (maintenu par ramnes sur GitHub) est le client de référence pour les développeurs Python. Il s’aligne sur le SDK officiel JavaScript en termes de structure et d’API.

Installation et configuration

pip install notion-client

import os
from notion_client import Client

notion = Client(auth=os.environ["NOTION_TOKEN"])

# Requête synchrone
results = notion.databases.query(database_id="votre-database-id")

# Ou en mode asynchrone
from notion_client import AsyncClient

async_notion = AsyncClient(auth=os.environ["NOTION_TOKEN"])
results = await async_notion.databases.query(database_id="votre-database-id")

Fonctionnalités clés du SDK Python

Le SDK gère automatiquement les erreurs 429 (rate limiting) et les erreurs serveur 500/503 sur les requêtes idempotentes (GET, DELETE). Pour les cas d’erreur, il lève une exception APIResponseError avec un code comparable aux constantes APIErrorCode.

Utiliser l’API sans coder : plateformes no-code

Vous n’avez pas besoin de savoir coder pour exploiter l’API. Plusieurs plateformes no-code servent d’intermédiaires et rendent les connexions accessibles à tous. J’ai rédigé un guide complet sur les automatisations Notion qui couvre ces plateformes en détail.

Zapier : le connecteur universel

Zapier propose plus de 8 000 intégrations natives. La connexion avec Notion est directe : vous sélectionnez un déclencheur (une nouvelle ligne dans Google Sheets, par exemple), puis une action (créer une page dans une base Notion). En quelques clics, le workflow est opérationnel.

J’utilise Zapier pour des automatisations simples et ponctuelles. La version gratuite est suffisante pour démarrer.

Make (ex-Integromat) : la puissance visuelle

Make offre plus de 3 000 intégrations et un éditeur visuel de scénarios intuitif. Pour les workflows complexes avec des conditions, des boucles ou des transformations de données, Make est souvent plus adapté que Zapier.

J’ai configuré plusieurs dizaines de scénarios Make connectés à Notion pour des projets clients. La courbe d’apprentissage est raisonnable et le rapport fonctionnalités/prix est excellent.

n8n : l’option open source

n8n propose plus de 400 nodes natifs, auxquels s’ajoutent plus de 5 000 nodes communautaires. L’avantage : vous pouvez l’héberger vous-même, ce qui donne un contrôle total sur vos données. Le node Notion de n8n prend en charge les dernières versions de l’API.

Pour les profils techniques ou les projets qui exigent la maîtrise des données, c’est la solution que je recommande.

Guide pratique : créer votre première intégration

Voici les quatre étapes pour connecter un outil externe à Notion via l’API, sans écrire de code.

Étape 1 : créer une intégration dans Notion

Rendez-vous sur developers.notion.com. Connectez-vous avec votre compte Notion, puis cliquez sur « New integration ». Donnez-lui un nom explicite et sélectionnez le workspace concerné.

Notion vous fournit un token d’intégration (Internal Integration Secret). Conservez-le : c’est la clé qui autorise l’accès à vos données. Le header d’authentification prend la forme Authorization: Bearer <votre-token>.

Étape 2 : partager une base de données avec l’intégration

Dans Notion, ouvrez la base de données que vous souhaitez connecter. Cliquez sur les trois points en haut à droite, puis sur « Connections » et ajoutez votre intégration. Sans cette étape, l’API retourne une erreur 404 sur les endpoints de cette base.

Étape 3 : configurer le workflow dans votre outil no-code

Dans Zapier, Make ou n8n, créez un nouveau workflow. Sélectionnez Notion comme application, puis collez votre token d’intégration. L’outil détecte automatiquement les bases auxquelles vous avez donné accès.

Configurez le déclencheur (trigger) et l’action selon votre besoin. Pour les bases multi-sources (API 2025-09-03+), vérifiez que le data_source_id est correctement récupéré.

Étape 4 : tester et surveiller

Lancez un test pour vérifier que les données circulent correctement. Les problèmes les plus fréquents sont :

• Erreur 404 : base non partagée avec l’intégration
• Erreur 429 : rate limiting (3 requêtes/seconde dépassées)
• Erreur 400 : types de propriétés mal mappés ou chaîne vide au lieu de null
• Erreur de pagination : résultats tronqués au-delà de 100 entrées (utiliser next_cursor)

Les intégrations natives à connaître en 2026

L’écosystème d’intégrations a grandi depuis 2021. Voici les connexions que j’utilise le plus au quotidien.

Formulaires : Typeform, Tally, Jotform

Typeform a été le premier à proposer une intégration native avec Notion dès 2021. Tally a suivi avec une intégration gratuite et efficace. Les réponses arrivent directement dans une base Notion, exploitables avec des formules Notion pour automatiser le tri et le suivi.

Calendriers et communication

La synchronisation bidirectionnelle entre Google Agenda et Notion est native via Notion Calendar. Slack dispose d’une intégration native pour prévisualiser des pages et créer des tâches depuis un message. Pour Gmail, les connexions passent par Zapier ou Make.

Développement : GitHub, GitLab

Les équipes techniques connectent GitHub à Notion pour synchroniser issues, pull requests et releases avec leurs bases de suivi. L’intégration GitHub est native et bien maintenue.

IA : Claude, ChatGPT, Cursor via MCP

Depuis l’arrivée du serveur MCP hébergé, les outils IA compatibles accèdent à Notion en un clic via OAuth. Claude Code, Cursor et ChatGPT peuvent rechercher, créer et modifier des pages directement dans votre workspace. Par rapport aux intégrations classiques, c’est un saut qualitatif important.

Les limites de l’API Notion à connaître

L’API a des contraintes techniques qu’il faut anticiper avant de construire une intégration.

Les outils no-code gèrent la pagination et le rate limiting automatiquement. Pour les développeurs, le SDK Python retente automatiquement les requêtes avec un backoff exponentiel (configurable via max_retries et max_retry_delay_ms).

Autre point à surveiller : les UUIDs peuvent être envoyés avec ou sans tirets dans les requêtes, et les chaînes vides ne sont pas acceptées (utiliser null à la place).

Spécifications techniques de référence

Pour les développeurs qui construisent des intégrations directes, voici les spécifications essentielles de l’API.

Le header Notion-Version est obligatoire pour toutes les requêtes REST. L’API utilise un versionnage par date : seuls les changements incompatibles déclenchent une nouvelle version. Les anciennes versions restent supportées indéfiniment, mais Notion recommande de migrer vers la dernière.

Mon verdict : pourquoi l’API Notion est devenue indispensable en 2026

Après cinq ans d’utilisation, l’API de Notion est passée d’une fonctionnalité secondaire à une brique essentielle de la plateforme. En mars 2026, trois évolutions changent la donne : le serveur MCP hébergé ouvre Notion aux assistants IA sans configuration, l’API Views permet de piloter les vues par code, et le Markdown Content API simplifie les intégrations textuelles.

Si vous utilisez Notion au quotidien, même sans coder, les automatisations via Zapier ou Make sont à portée de main. L’API est incluse dans tous les forfaits Notion, y compris le plan gratuit. Si vous êtes développeur, le SDK Python notion-client et le SDK JavaScript @notionhq/client v5.15.0 offrent une surface d’API mature.

Pour aller plus loin, je vous recommande mon tutoriel complet sur Notion et mon guide sur les automatisations Notion.

FAQ

Faut-il savoir coder pour utiliser l’API de Notion ?

Non. Des plateformes no-code comme Zapier (8 000+ intégrations), Make (3 000+ intégrations) et n8n (400+ nodes natifs, plus de 5 000 nodes communautaires) permettent d’exploiter l’API via une interface visuelle, sans écrire une seule ligne de code. La majorité des automatisations que j’ai mises en place pour mes clients utilisent Make ou Zapier.

L’API de Notion est-elle gratuite ?

Oui. L’accès à l’API est inclus dans tous les forfaits Notion, y compris le plan gratuit. Il n’y a aucun coût supplémentaire pour les appels API. Seuls les outils d’automatisation tiers ont leurs propres grilles tarifaires.

Quelles sont les limites techniques de l’API Notion ?

Les principales limites sont le rate limiting à 3 requêtes par seconde, la pagination obligatoire au-delà de 100 résultats par requête, et le support partiel de certains types de blocs en écriture. Le SDK Python gère automatiquement le rate limiting avec un backoff exponentiel.

Qu’est-ce que le protocole MCP et comment Notion l’utilise ?

Le Model Context Protocol (MCP) est un standard ouvert lancé par Anthropic en novembre 2024. Notion héberge son propre serveur MCP qui permet aux outils IA (Claude Code, Cursor, VS Code, ChatGPT) de lire et écrire dans votre workspace via une authentification OAuth en un clic. Selon le blog technique de Notion, le format markdown utilisé par le serveur MCP offre une densité de contenu plus efficace par token LLM que le format bloc classique.

Quelle version de l’API Notion utiliser en 2026 ?

Utilisez la version 2026-03-11, sortie le 11 mars 2026. Elle introduit l’objet position pour le placement des blocs, remplace archived par in_trash, et renomme le bloc transcription en meeting_notes. Le SDK officiel @notionhq/client v5.15.0 et le SDK Python notion-client la prennent en charge.

Comment utiliser l’API Notion avec Python ?

Installez le SDK avec pip install notion-client. Initialisez le client avec votre token d’intégration, puis utilisez les méthodes correspondant aux endpoints de l’API (databases.query(), pages.create(), blocks.children.list()). Le SDK supporte les modes synchrone et asynchrone, avec gestion automatique du rate limiting.

Qu’est-ce que l’API Views de Notion ?

Lancée le 19 mars 2026, l’API Views (/v1/views) ajoute 8 endpoints pour gérer les vues de bases de données par programmation. Elle supporte 10 types de vues et 3 événements webhook (view.created, view.updated, view.deleted). Le SDK minimum requis est @notionhq/client v5.14.0.