How to use Notion as Code

Kernpunkte

1. ⭐ Was es in einem Satz ist. Infrastructure as Code für einen dokumentarischen Workspace. Der gewünschte Endzustand wird in TypeScript beschrieben, und Notion gleicht den Workspace daran ab. Das ist das Terraform-Modell, angewandt auf Seiten, Datenbanken und Teams statt auf Cloud-Ressourcen.
2. ⭐⭐ Der Kernmechanismus — der Ressourcen-Identifikator, und warum er alles bewirkt. Das Skript enthält keine Notion-ID. Es verwendet vom Autor gewählte resourceIds. Die erste Bereitstellung liefert eine Zuordnungstabelle resourceId → RecordPointer zurück, die anschließend über existingResources / existingProperties erneut übergeben wird. Daraus folgen drei Eigenschaften, die untrennbar sind: 1. Idempotenz — eine erneute Bereitstellung aktualisiert, statt neu zu erstellen. 2. Entkopplung vom Workspace — « 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 »: eine Zuordnungstabelle pro Workspace, ein einziges Skript. 3. Programmierbarkeit — es ist Code, daher Variablen und Schleifen: « build 10 teams that all have a very similar structure and just need some nouns renamed ». → Die Indirektion über einen logischen Identifikator macht aus einem API-Skript einen wiederverwendbaren State-Deskriptor. Genau diese Rolle spielen Ressourcenadressen in einem Terraform-State.
3. Der API-Vertrag in zwei Schritten (asynchron). POST /v1/infra_as_code (Felder intents — die serialisierte JSON-Repräsentation des Skripts —, existingResources, existingProperties) liefert eine taskId zurück; GET /v1/async_tasks/{taskId} wird abgefragt, bis status: succeeded erreicht ist, wobei die Antwort createdRecordCounts, resourceIdToPointerMappings und resourceIdToPropertyIdMappings trägt. Die beiden ausgegebenen Zuordnungstabellen sind es, die persistiert werden müssen — sie sind das Äquivalent einer State-Datei.
4. Zwei operative Unterschiede, die man vor dem Ausprobieren kennen sollte.
5. Persönliche Zugriffstoken sind zwingend erforderlich. , nicht die üblichen Bot-Token der öffentlichen API. ⚠️ Eine Konsequenz, die die Seite nicht erörtert: Aktionen werden einer Person zugeordnet, nicht einer Integration — was dieselbe Verantwortlichkeitsfrage aufwirft wie « who consumes, and on whose behalf » in [[girard-acp-deux-protocoles-un-sigle-2026-08-02]]. Ein Agent, der mit dem persönlichen Token eines Administrators bereitstellt, handelt in dessen Namen.
6. 5 Anfragen pro Minute. , « since this API is not a 1 request → 1 entity created or updated ». Die Rate wird gesenkt, weil ein Aufruf einen Stapel darstellt.
7. ⭐ Die Erwähnung von Agenten, unauffällig eingewoben. « A typescript SDK for you or your coding agent to describe what you want in your Notion workspace », und der empfohlene Pfad besteht darin, das SDK zu klonen und dann « either you or your favorite coding agent » die README lesen zu lassen. → Das Produkt ist so konzipiert, dass ein Agent es nutzt, und genau das typisierte SDK macht dies sicher: Die Typen schränken ein, was der Agent beschreiben kann, und die Abgleichung macht einen Fehler durch erneute Bereitstellung statt manuelle Bereinigung behebbar. Ein typisierter State-Deskriptor ist für einen Agenten ein weit besseres Werkzeug als eine Reihe imperativer API-Aufrufe — der Fehler ist dort wiederholbar, nicht kumulativ.
8. Genannte Einschränkungen. Es kann nur innerhalb eines bestehenden Workspace erstellt oder aktualisiert werden (kein Workspace kann erstellt werden); nicht alle Entitäten sind abgedeckt — es wird auf die Typdefinitionsdatei des SDK verwiesen, wobei High-Level-Primitiven funktionieren sollten; gesenktes Rate Limit.
9. ⚠️ Was die Seite nicht sagt und im Blick behalten werden sollte.
10. Keine Erwähnung von Löschung. Die API „erstellt oder aktualisiert“. Was geschieht mit einem aus dem Skript entfernten Element? Ein echtes State-Management-Werkzeug weiß, wie es löscht, was nicht mehr deklariert ist — hier deutet nichts darauf hin, was auf eine additive Abgleichung und damit mögliche Drift zwischen Skript und tatsächlichem Workspace schließen lässt.
11. Kein „Plan“-Modus. oder Vorschau vor der Anwendung. Man stellt bereit und beobachtet.
12. Keine Behandlung von Nebenläufigkeit. Zwei gleichzeitige Bereitstellungen auf demselben Workspace werden nicht erörtert.
13. Kein Autor, kein Datum. Bei einer sich weiterentwickelnden Alpha-Dokumentation ist dies eine Lücke, die jedes Zitat schnell veraltet erscheinen lässt — daher die Datierung dieser Notiz nach Beobachtungszeitpunkt.
14. Tech-Watch-Perspektive — warum das über Notion hinaus relevant ist. Dies ist ein weiteres Signal dafür, dass das deklarative Modell aus der Infrastruktur herauswandert. Nach der Cloud nun dokumentarische Workspaces; und der anerkannte Treiber ist der Coding Agent, der ein beschreibbares, typisiertes, wiederholbares Format benötigt statt einer Abfolge von Aktionen. Erwähnenswert im Zusammenhang mit der Logik „eine Datei statt ein Team“ aus [[isenberg-meng-to-google-design-md-design-team-in-a-file-2026-05-06]] sowie mit der Disziplin versionierter Spezifikationen aus [[lassiege-usine-logicielle-heure-ia-2026-07-28]].
15. Meta / Querverweise. die Frage des persönlichen Tokens und des Handelns im Namen anderer in [[girard-acp-deux-protocoles-un-sigle-2026-08-02]]; Agenten-Identität und Handlungsumfang in [[uber-engineering-agent-identity-crisis-zero-trust-spire-2026-05-21]] und [[valente-zalewski-beyond-zero-enterprise-security-ai-era-2026-07-20]]; agentengetriebene deklarative Artefakte in [[isenberg-meng-to-google-design-md-design-team-in-a-file-2026-05-06]].