How to use Notion as Code

À retenir

1. ⭐ Ce que c'est, en une phrase. de l'infrastructure as code pour un espace de travail documentaire. On décrit l'état final voulu en TypeScript, Notion réconcilie l'espace pour qu'il y corresponde. C'est le modèle Terraform, appliqué à des pages, bases et équipes plutôt qu'à des ressources cloud.
2. ⭐⭐ Le mécanisme central — l'identifiant de ressource, et pourquoi il fait tout. le script ne contient aucun identifiant Notion. Il utilise des resourceId choisis par l'auteur. Le premier déploiement retourne une table de correspondance resourceId → RecordPointer, que l'on renvoie ensuite via existingResources / existingProperties. Trois propriétés en découlent, et elles sont inséparables : 1. Idempotence — re-déployer met à jour au lieu de recréer. 2. Découplage de l'espace de travail — « since the script is not coupled to one workspace, you can easily have multiple mappings… allowing you to use the same script to deploy many workspaces » : une table de correspondance par espace, un seul script. 3. Programmabilité — c'est du code, donc variables et boucles : « build 10 teams that all have a very similar structure and just need some nouns renamed ». → L'indirection par identifiant logique est ce qui transforme un script d'API en descripteur d'état réutilisable. C'est exactement le rôle des adresses de ressources dans un état Terraform.
3. Le contrat d'API, en deux temps (asynchrone). POST /v1/infra_as_code (champs intents — représentation JSON sérialisée du script —, existingResources, existingProperties) rend un taskId ; on interroge GET /v1/async_tasks/{taskId} jusqu'à status: succeeded, la réponse portant createdRecordCounts, resourceIdToPointerMappings et resourceIdToPropertyIdMappings. Les deux tables de correspondance en sortie sont ce qu'il faut persister — ce sont l'équivalent d'un fichier d'état.
4. Deux différences opérationnelles à connaître avant d'essayer.
5. Jetons d'accès personnels obligatoires. , et non les jetons de bot de l'API publique. ⚠️ Conséquence non discutée par la page : les actions sont attribuées à une personne, pas à une intégration — ce qui pose la même question de responsabilité que « qui consomme, et pour le compte de qui » dans [[girard-acp-deux-protocoles-un-sigle-2026-08-02]]. Un agent qui déploie avec le jeton personnel d'un administrateur agit en son nom.
6. 5 requêtes par minute. , « since this API is not a 1 request → 1 entity created or updated ». Le débit est abaissé parce qu'un appel est un lot.
7. ⭐ La mention des agents, intégrée sans emphase. « A typescript SDK for you or your coding agent to describe what you want in your Notion workspace », et le chemin recommandé consiste à cloner le SDK puis laisser « either you or your favorite coding agent » lire le README. → Le produit est conçu en supposant qu'un agent l'utilisera, et le SDK typé est précisément ce qui rend cela sûr : les types contraignent ce que l'agent peut décrire, et la réconciliation rend l'erreur corrigible par re-déploiement plutôt que par nettoyage manuel. Un descripteur d'état typé est un bien meilleur outil pour un agent qu'une série d'appels d'API impératifs — l'erreur y est rejouable, pas cumulative.
8. Limites déclarées. ne peut que créer ou mettre à jour dans un espace existant (impossible de créer un espace) ; toutes les entités ne sont pas couvertes — se référer au fichier de définition de types du SDK, les primitives de haut niveau étant censées passer ; débit abaissé.
9. ⚠️ Ce que la page ne dit pas, et qu'il faut avoir en tête.
10. Aucune mention de destruction. L'API « crée ou met à jour ». Que devient un élément retiré du script ? Un vrai outil d'état sait supprimer ce qui n'est plus déclaré — ici, rien ne l'indique, ce qui suggère une réconciliation additive et donc une dérive possible entre le script et l'espace réel.
11. Aucun mode « plan ». ni prévisualisation avant application. On déploie et on observe.
12. Aucune gestion de la concurrence. deux déploiements simultanés sur le même espace ne sont pas discutés.
13. Aucun auteur, aucune date. Pour une documentation d'alpha en évolution, c'est un manque qui rendra toute citation rapidement périmée — d'où la datation par observation dans cette fiche.
14. Angle « veille » — pourquoi c'est intéressant au-delà de Notion. c'est un signal de plus de la migration du modèle déclaratif hors de l'infrastructure. Après le cloud, les espaces documentaires ; et le déclencheur assumé est l'agent de codage, qui a besoin d'un format descriptible, typé et rejouable plutôt que d'une séquence d'actions. À rapprocher de la logique « un fichier plutôt qu'une équipe » de [[isenberg-meng-to-google-design-md-design-team-in-a-file-2026-05-06]], et de la discipline de spécification versionnée de [[lassiege-usine-logicielle-heure-ia-2026-07-28]].
15. Méta / à relier. question du jeton personnel et de l'action pour le compte d'autrui dans [[girard-acp-deux-protocoles-un-sigle-2026-08-02]] ; identité et périmètre d'action d'un agent dans [[uber-engineering-agent-identity-crisis-zero-trust-spire-2026-05-21]] et [[valente-zalewski-beyond-zero-enterprise-security-ai-era-2026-07-20]] ; artefacts déclaratifs pilotés par agent dans [[isenberg-meng-to-google-design-md-design-team-in-a-file-2026-05-06]].