How to use Notion as Code

Kernpunkte

1. Was es ist, in einem Satz. Infrastructure as Code für einen dokumentarischen Workspace. Der gewünschte Endzustand wird in TypeScript beschrieben, und Notion gleicht den Workspace daran an. Es ist das Terraform-Modell, angewandt auf Seiten, Datenbanken und Teams statt auf Cloud-Ressourcen.
2. Der zentrale Mechanismus — der Ressourcenbezeichner, und warum er alles trägt. Das Skript enthält keine Notion-ID. Es verwendet vom Autor gewählte resourceId-Werte. Das erste Deployment liefert eine Zuordnungstabelle resourceId → RecordPointer zurück, die anschließend über existingResources / existingProperties wieder übergeben wird. Daraus folgen drei Eigenschaften, die untrennbar sind: 1. Idempotenz — erneutes Deployment 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 logische Bezeichner ist es, die aus einem API-Skript einen wiederverwendbaren Zustandsdeskriptor macht. Genau diese Rolle spielen Ressourcenadressen im Terraform-State.
3. Der API-Vertrag, in zwei Schritten (asynchron). POST /v1/infra_as_code (Felder intents — eine 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 enthält. Die beiden ausgegebenen Zuordnungstabellen sind es, die persistiert werden müssen — sie sind das Äquivalent einer State-Datei.
4. Zwei betriebliche Unterschiede, die man vor einem Test kennen sollte.
5. Verpflichtend persönliche Zugriffstoken. , statt der üblichen Bot-Token der öffentlichen API. Eine Konsequenz, die die Seite nicht diskutiert: Aktionen werden einer Person zugeschrieben, nicht einer Integration — was dieselbe Frage der Zurechenbarkeit aufwirft wie « wer konsumiert, und in wessen Namen » in [[girard-acp-deux-protocoles-un-sigle-2026-08-02]]. Ein Agent, der mit dem persönlichen Token eines Administrators deployt, handelt in dessen Namen.
6. 5 Anfragen pro Minute. , « since this API is not a 1 request → 1 entity created or updated ». Die Rate ist gesenkt, weil ein Aufruf ein Batch ist.
7. Die beiläufig eingestreute Erwähnung von Agenten. « A typescript SDK for you or your coding agent to describe what you want in your Notion workspace », und der empfohlene Weg besteht darin, das SDK zu klonen und dann « either you or your favorite coding agent » die README lesen zu lassen. → Das Produkt ist unter der Annahme konzipiert, dass ein Agent es benutzen wird, und das typisierte SDK ist genau das, was dies sicher macht: Die Typen schränken ein, was der Agent beschreiben kann, und die Reconciliation macht einen Fehler durch erneutes Deployment korrigierbar statt manueller Aufräumarbeit erforderlich zu machen. Ein typisierter Zustandsdeskriptor ist ein weitaus besseres Werkzeug für einen Agenten als eine Folge imperativer API-Aufrufe — der Fehler ist dort wiederholbar, nicht kumulativ.
8. Genannte Einschränkungen. kann nur innerhalb eines bestehenden Workspace erstellen oder aktualisieren (kein Erstellen eines Workspace möglich); nicht alle Entitäten sind abgedeckt — verwiesen wird auf die Typdefinitionsdatei des SDK, wobei erwartet wird, dass High-Level-Primitiven funktionieren; gesenktes Rate Limit.
9. Was die Seite nicht sagt und im Blick behalten werden sollte.
10. Keine Erwähnung der Zerstörung. Die API „erstellt oder aktualisiert“. Was geschieht mit einem aus dem Skript entfernten Element? Ein echtes State-Tool weiß, wie es löscht, was nicht mehr deklariert ist — hier deutet nichts darauf hin, was auf eine additive Reconciliation und damit auf mögliche Drift zwischen Skript und tatsächlichem Workspace schließen lässt.
11. Kein „Plan“-Modus. und keine Vorschau vor der Anwendung. Man deployt und beobachtet.
12. Keine Behandlung von Nebenläufigkeit. Zwei gleichzeitige Deployments in denselben Workspace werden nicht behandelt.
13. Kein Autor, kein Datum. Bei einer sich noch entwickelnden Alpha-Dokumentation ist dies eine Lücke, die jedes Zitat schnell veralten lässt — daher die beobachtungsbasierte Datierung in dieser Fiche.
14. Tech-Watch-Perspektive — warum das über Notion hinaus relevant ist. Es ist ein weiteres Signal für die Abwanderung des deklarativen Modells aus der Infrastruktur heraus. Nach der Cloud nun dokumentarische Workspaces; und der genannte Auslöser ist der Coding Agent, der ein beschreibbares, typisiertes, wiederholbares Format benötigt statt einer Abfolge von Aktionen. In Bezug zu setzen mit der „eine Datei statt ein Team“-Logik in [[isenberg-meng-to-google-design-md-design-team-in-a-file-2026-05-06]] und mit der Disziplin der versionierten Spezifikation in [[lassiege-usine-logicielle-heure-ia-2026-07-28]].
15. Meta / Querverweise. die Frage des persönlichen Tokens und des Handelns im Namen eines anderen in [[girard-acp-deux-protocoles-un-sigle-2026-08-02]]; Identität und Handlungsspielraum eines Agenten 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.