# notion-as-code-2026-08-03

## Veille

Dokumentationsseite zu **Notion as Code**, veröffentlicht im **Notion Ambassadors**-Workspace und abgerufen am **3. August 2026**. Produkt im **Closed-Alpha-/Warteliste**-Status, mit einem Warnhinweis vorab: *« This product is under development so we recommend you try it out in a new workspace vs. your primary workspace »* und *« There may be breaking changes until we're fully launched »*. **Das Prinzip ist Infrastructure as Code, angewandt auf einen dokumentarischen Workspace**: *« Instead of having to make individual public API requests, you can describe the final state and we handle updating your workspace to match. »* Zwei Bausteine: ein **TypeScript SDK** zur Beschreibung des gewünschten Zustands und ein öffentlicher API-Endpunkt `/v1/infra_as_code` zu dessen Bereitstellung. **Der Mechanismus, der alles zusammenhält, ist der Ressourcenbezeichner**: Das Skript enthält **überhaupt keine Notion-ID**, sondern nur vom Autor gewählte *resource IDs*; das erste Deployment liefert eine **Zuordnungstabelle** `resourceId → RecordPointer` zurück, die bei nachfolgenden Aufrufen wieder übergeben wird, sodass dieselben Datensätze **aktualisiert statt neu erstellt** werden. Daraus folgen drei Eigenschaften, und sie sind die einzigen, die zählen: Das Skript ist **idempotent** (erneutes Deployment = Aktualisierung), es ist **vom Workspace entkoppelt** (mehrere Zuordnungstabellen erlauben das Deployment **desselben Skripts auf mehrere Workspaces**), und es ist Code — daher Variablen und Schleifen, wobei als Beispiel genannt wird, *« build 10 teams that all have a very similar structure and just need some nouns renamed »*. **Die API ist asynchron**: `POST /v1/infra_as_code` liefert eine `taskId` zurück, die über `GET /v1/async_tasks/{taskId}` abgefragt wird, bis der Status `succeeded` erreicht ist. **Zwei bemerkenswerte betriebliche Unterschiede**: Das Produkt erfordert **persönliche Zugriffstoken** anstelle der üblichen Bot-Token der öffentlichen API, und das **Rate Limit ist auf 5 Anfragen pro Minute gesenkt**, da ein einzelner Aufruf nicht mehr eine einzelne Entität, sondern einen Batch erzeugt. **Für dieses Korpus festzuhalten**: Die Seite ist explizit für den assistierten Einsatz geschrieben — *« A typescript SDK for you **or your coding agent** to describe what you want »* —, und der empfohlene Einstiegsweg besteht darin, das SDK auf einem experimentellen Branch zu klonen und *« either you or your favorite coding agent »* die README öffnen zu lassen. **Genannte Einschränkungen**: kein Erstellen eines neuen Workspace möglich, nur teilweise Abdeckung der Primitiven, sowie eine Seite ohne Autor- oder Datumsangabe.

## Titre Article

How to use Notion as Code

## Date

2026-08-03

## URL

https://app.notion.com/p/notionambassadors/How-to-use-Notion-as-Code-3973139dbfef802eb77cfbe7cf08c12a

## Keywords

Notion as Code, Infrastructure as Code, IaC, gewünschter Zustand, Reconciliation, Idempotenz, TypeScript SDK, notion-sdk-js, experimenteller Branch, öffentliche API, infra_as_code, asynchroner Endpunkt, taskId, async_tasks, Polling, Ressourcen-ID, Ressourcenbezeichner, RecordPointer, Zuordnungstabelle, Mapping, existingResources, existingProperties, intents, Multi-Workspace-Deployment, Musterwiederverwendung, Variablen und Schleifen, persönliche Zugriffstoken, persönliches Zugriffstoken, Rate Limit, 5 Anfragen pro Minute, Alpha, Warteliste, Breaking Changes, Coding Agents, Coding Agent, unterstützte Primitiven, Feedback-Tracker, Notion Ambassadors

## Authors

**Notion** — documentation produit publiée sur l'espace public **Notion Ambassadors**. **Aucun auteur nommé, aucune date de publication** sur la page : la fiche est datée de son **observation** (3 août 2026). Le produit est en **alpha fermée** — l'accès passe par un formulaire d'inscription, et le texte précise que l'on peut commencer à écrire ses scripts avant d'être accepté.

Renvoi vers deux ressources externes : le dépôt **`makenotion/notion-sdk-js`** sur la branche **`EXPERIMENTAL__notion-as-code`**, et un **Feedback Tracker** pour les retours et anomalies.

## Ton

**Profil**: knappe, operative Alpha-Produktdokumentation. Weder Marketing-Ankündigung noch Tiefenartikel — eine Onboarding-Seite, die zugleich als **API-Spezifikation** fungiert (Feld-/Typ-/Beschreibungstabellen für Anfrage und Antwort beider Endpunkte).

**Stil**: **erst Warnhinweise, dann der Mechanismus**. Die Seite eröffnet mit drei Vorbehalten (Produkt in Entwicklung, mögliche Breaking Changes, Zugriff hinter Freigabe) noch bevor der Nutzen erklärt wird. Das Register ist das eines Teams, das früh liefert und dies auch so kommuniziert: Warn-Emojis 🚧 oben und in Abschnittsüberschriften, ein Link zu einem Issue-Tracker, explizit aufgelistete Einschränkungen am Ende.

**Die eine rhetorische Bewegung der Seite** lässt sich in einem Satz zusammenfassen, und es ist genau der, der die Existenz des Produkts rechtfertigt: *« Instead of having to make individual public API requests, you can describe the final state and we handle updating your workspace to match. »* Alles Weitere folgt daraus — die Zuordnungstabelle, die Idempotenz, die Unterstützung mehrerer Workspaces.

**Bemerkenswertes Merkmal**: Der Coding Agent wird zweimal **als vollwertiger Nutzer** erwähnt, ohne besondere Betonung — *« for you or your coding agent »*, *« either you or your favorite coding agent can open the readme »*. Dies ist kein nachträglich angeflanschter „KI“-Abschnitt: Es ist als Selbstverständlichkeit in die Produktbeschreibung eingewoben.

**Charakteristische Formulierungen**: *« describe the final state and we handle updating your workspace to match »*, *« this script doesn't have any IDs, but instead uses resource IDs »*, *« Since the script is not coupled to one workspace »*, *« this API is not a 1 request → 1 entity created or updated »*.

## Pense-betes

- **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.
- **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.
- **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.
- **Zwei betriebliche Unterschiede, die man vor einem Test kennen sollte**:
- **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**.
- **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.
- **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.
- **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.
- **Was die Seite nicht sagt und im Blick behalten werden sollte**:
- **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.
- **Kein „Plan“-Modus** und keine Vorschau vor der Anwendung. Man deployt und beobachtet.
- **Keine Behandlung von Nebenläufigkeit**: Zwei gleichzeitige Deployments in denselben Workspace werden nicht behandelt.
- **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.
- **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]].
- **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.

## RésuméDe400mots

Dokumentation zu **Notion as Code**, ein Produkt in **Closed Alpha**, abgerufen am 3. August 2026 im Notion-Ambassadors-Workspace — ohne Autor- oder Datumsangabe, mit einem Warnhinweis, der empfiehlt, es zunächst in einem neuen Workspace auszuprobieren, und vor möglichen Breaking Changes warnt.

**Das Prinzip** ist Infrastructure as Code, angewandt auf einen dokumentarischen Workspace: *« Instead of having to make individual public API requests, you can describe the final state and we handle updating your workspace to match. »* Zwei Bausteine: ein **TypeScript SDK** zur Beschreibung des gewünschten Zustands und der Endpunkt **`/v1/infra_as_code`** zu dessen Bereitstellung.

**Der Mechanismus, der alles trägt**, ist die Indirektion über Bezeichner. Das Skript **enthält keine Notion-ID**: Es deklariert vom Autor gewählte `resourceId`-Werte. Das erste Deployment liefert eine **Zuordnungstabelle** zwischen diesen logischen Bezeichnern und den tatsächlich erstellten Datensätzen zurück; bei nachfolgenden Aufrufen wieder übergeben, stellt sie sicher, dass dieselben Datensätze **aktualisiert statt neu erstellt** werden.

**Drei Eigenschaften folgen daraus.** Das Skript wird **idempotent**. Es wird **vom Workspace entkoppelt** — mehrere Zuordnungstabellen erlauben das Deployment **desselben Skripts auf mehrere Workspaces**. Und da es sich um Code handelt, unterstützt es Variablen und Schleifen: Als Beispiel wird der Aufbau von zehn Teams identischer Struktur genannt, bei denen nur einige Substantive geändert werden.

**Der API-Vertrag ist asynchron**: Ein `POST` liefert eine `taskId` zurück, die bis zum Abschluss abgefragt wird; die Antwort enthält die zu persistierenden Zuordnungstabellen — das Äquivalent einer State-Datei.

**Zwei betriebliche Unterschiede**: Das Produkt erfordert **persönliche Zugriffstoken** anstelle der üblichen Bot-Token, wodurch Aktionen einer Person statt einer Integration zugeschrieben werden; und das **Rate Limit sinkt auf 5 Anfragen pro Minute**, da ein Aufruf nun ein Batch statt einer einzelnen Entität ist.

**Das Produkt setzt den Agenten voraus.** Das SDK wird als gebaut *« für Sie oder Ihren Coding Agent »* vorgestellt, und der Onboarding-Pfad besteht darin, einen Agenten die README des SDK lesen zu lassen. Ein typisierter Zustandsdeskriptor ist tatsächlich ein besseres Werkzeug für einen Agenten als eine Folge imperativer Aufrufe: Der Fehler ist dort wiederholbar, nicht kumulativ.

**Was fehlt**: keine Erwähnung des Löschens von aus dem Skript entfernten Elementen, kein Vorschaumodus vor der Anwendung, nichts zur Nebenläufigkeit, und kein Datum bei einer Dokumentation, die sich noch ändern wird.

## GrapheDeConnaissance

- Notion —publie→ Notion as Code (TECHNOLOGIE, 0.96)
- Notion as Code —permet→ de décrire l'état final voulu d'un espace de travail et de laisser la plateforme le réconcilier (CITATION, 0.96)
- Notion as Code —est_instance_de→ infrastructure as code (CONCEPT, 0.92)
- identifiant de ressource logique —permet→ de rendre un script idempotent et déployable sur plusieurs espaces de travail (AFFIRMATION, 0.95)
- table de correspondance resourceId vers enregistrement —permet→ de mettre à jour les enregistrements existants au lieu d'en créer de nouveaux (AFFIRMATION, 0.95)
- Notion as Code —utilise→ un SDK TypeScript (TECHNOLOGIE, 0.95)
- Notion as Code —s_applique_à→ les agents de codage, désignés comme utilisateurs du SDK au même titre que les humains (AFFIRMATION, 0.93)
- Notion as Code —utilise→ des jetons d'accès personnels plutôt que des jetons de bot de l'API publique (AFFIRMATION, 0.94)
- endpoint infra_as_code —s_oppose_à→ le modèle une requête pour une entité, d'où une limite de débit abaissée à cinq requêtes par minute (AFFIRMATION, 0.93)
- Notion as Code —réduit→ le nombre d'appels d'API nécessaires pour construire des structures répétitives, grâce aux variables et aux boucles (AFFIRMATION, 0.9)
- description d'état typée —surpasse→ une séquence d'appels impératifs pour un agent, l'erreur devenant rejouable plutôt que cumulative (AFFIRMATION, 0.82)
- Notion as Code —affirme_que→ le produit est en développement, sujet à des changements cassants, et limité à la création ou mise à jour dans un espace existant (AFFIRMATION, 0.95)

---
Canonical: https://www.thekb.eu/de/fiches/notion-as-code-2026-08-03/