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.

Créer une base typée via l’API : le champ database_type

Depuis le 2 septembre 2026, l’endpoint Create Database accepte un paramètre optionnel database_type. Au lieu de définir manuellement chaque propriété, vous indiquez un type de base parmi trois valeurs — tasks, projects ou skills — et Notion construit la base à partir de son schéma canonique et de ses métadonnées.

Concrètement, l’appel suivant crée une base de tâches complète sans avoir à déclarer chaque colonne :

notion.databases.create(
    parent={"type": "page_id", "page_id": "votre-page-id"},
    database_type="tasks"
)

Deux règles sont à connaître. Le paramètre database_type ne peut pas être combiné avec initial_data_source : vous choisissez soit un schéma canonique, soit un schéma personnalisé. Et si vous omettez le champ title, la base est nommée d’après son type.

En lecture, les objets Database et data source exposent désormais un champ database_type en lecture seule. Vous pouvez ainsi détecter, depuis vos intégrations, si une base a été générée à partir d’un schéma canonique. Cette nouveauté rapproche l’API de la logique des agents IA de Notion, qui manipulent tâches, projets et Skills comme des objets de premier ordre.

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).

Limites du plan gratuit côté API

Un changement important est entré en vigueur le 1er septembre 2026 : la REST API applique désormais la limite de blocs des workspaces Free aux connexions internes et aux connexions OAuth restreintes à des workspaces sélectionnés. Jusque-là, cette limite ne s’appliquait qu’à l’interface Notion, et l’API permettait de la contourner en créant du contenu par programmation.

Concrètement, si votre workspace est sur le plan gratuit et atteint sa limite de blocs, l’API retourne désormais une erreur HTTP 403 lors des tentatives de création de contenu. Notion prévoit des périodes de grâce et un comportement spécifique pour les modèles en arrière-plan, mais le principe est clair : le plan gratuit n’offre plus de porte dérobée via l’API.

L’accès à l’API reste entièrement gratuit : il n’y a toujours aucun coût pour les appels eux-mêmes. Ce qui change, c’est que le volume de contenu que vous pouvez créer via l’API est désormais soumis aux mêmes plafonds que l’interface. Pour un usage intensif, il faut passer à un forfait payant, dont les plans Plus, Business et Enterprise lèvent la limite de blocs.

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. En septembre 2026, deux ajustements confirment cette trajectoire : la création de bases typées via le champ database_type et l’application de la limite de blocs des workspaces gratuits côté API.

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, dans la limite du plafond de blocs désormais appliqué aux connexions. 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.