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

## Veille

**Notion as Code**-Dokumentationsseite, veröffentlicht im **Notion Ambassadors**-Workspace und abgerufen am **3. August 2026**. Produkt im **geschlossenen Alpha-Stadium / auf Warteliste**, mit einer vorab platzierten Warnung: *« 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 Ressourcen-Identifikator**: Das Skript enthält **keine Notion-ID**, nur vom Autor gewählte *resource IDs*; die erste Bereitstellung liefert eine **Zuordnungstabelle** `resourceId → RecordPointer` zurück, die bei nachfolgenden Aufrufen erneut ü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** (erneute Bereitstellung = Aktualisierung), es ist **vom Workspace entkoppelt** (mehrere Zuordnungstabellen erlauben, **dasselbe Skript über mehrere Workspaces hinweg bereitzustellen**), und es ist **Code** — daher Variablen und Schleifen, wobei das gegebene Beispiel lautet: *« 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 `succeeded` erreicht ist. **Zwei bemerkenswerte operative 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**, weil ein Aufruf nicht mehr eine einzelne Entität, sondern einen Stapel erzeugt. ⚠️ **Für dieses Korpus festzuhaltender Punkt**: Die Seite ist explizit für den unterstützten Einsatz geschrieben — *« A typescript SDK for you **or your coding agent** to describe what you want »* —, und der empfohlene Einstiegspfad 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**: Es kann kein neuer Workspace erstellt werden, die Abdeckung der Primitiven ist unvollständig, und die Seite trägt weder Autor noch Datum.

## 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, Abgleichung, Idempotenz, TypeScript-SDK, notion-sdk-js, experimenteller Branch, öffentliche API, infra_as_code, asynchroner Endpunkt, taskId, async_tasks, Polling, Ressourcen-ID, Ressourcen-Identifikator, RecordPointer, Zuordnungstabelle, Zuordnung, existingResources, existingProperties, intents, Multi-Workspace-Bereitstellung, Wiederverwendung von Mustern, Variablen und Schleifen, persönliche Zugriffstoken, persönliches Zugriffstoken, Rate Limit, 5 Anfragen pro Minute, Alpha, Warteliste, Breaking Changes, Coding-Agenten, 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 eine Marketingankündigung noch ein Tiefenartikel — eine Onboarding-Seite, die zugleich als **API-Spezifikation** dient (Feld-/Typ-/Beschreibungstabellen für Anfrage und Antwort beider Endpunkte).

**Stil**: **Warnungen zuerst, Mechanismus danach**. Die Seite beginnt mit drei Vorbehalten (Produkt in Entwicklung, mögliche Breaking Changes, Zugang hinter Freigabe gesperrt), bevor irgendeine Erklärung des Nutzens erfolgt. Das Register ist das eines Teams, das früh ausliefert und dies auch so kommuniziert: Alarm-Emojis 🚧 und ⚠️ am Anfang der Abschnitte, ein Verweis auf einen Bug-Tracker, Einschränkungen am Ende explizit aufgelistet.

**Der einzige rhetorische Kunstgriff der Seite** steckt in einem Satz, und genau dieser rechtfertigt die Existenz des Produkts: *« 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 Multi-Workspace-Bereitstellung.

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

**Markante 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 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.
- **⭐⭐ Der Kernmechanismus — der Ressourcen-Identifikator, und warum er alles bewirkt**: Das Skript **enthält keine Notion-ID**. Es verwendet vom Autor gewählte `resourceId`s. 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.
- **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.
- **Zwei operative Unterschiede, die man vor dem Ausprobieren kennen sollte**:
- **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**.
- **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.
- **⭐ 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.
- **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.
- **⚠️ Was die Seite nicht sagt und im Blick behalten werden sollte**:
- **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.
- **Kein „Plan“-Modus** oder Vorschau vor der Anwendung. Man stellt bereit und beobachtet.
- **Keine Behandlung von Nebenläufigkeit**: Zwei gleichzeitige Bereitstellungen auf demselben Workspace werden nicht erörtert.
- **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.
- **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]].
- **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]].

## RésuméDe400mots

**Notion as Code**-Dokumentation, ein Produkt im **geschlossenen Alpha-Stadium**, abgerufen am 3. August 2026 im Notion-Ambassadors-Workspace — ohne Autor oder Datum, mit einer Warnung, die empfiehlt, es auf 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 Identifikatoren. Das Skript **enthält keine Notion-ID**: Es deklariert vom Autor gewählte `resourceId`s. Die erste Bereitstellung liefert eine **Zuordnungstabelle** zwischen diesen logischen Identifikatoren und den tatsächlich erstellten Datensätzen zurück; bei nachfolgenden Aufrufen erneut übergeben, sorgt sie dafür, dass dieselben Datensätze **aktualisiert statt neu erstellt** werden.

**Daraus folgen drei Eigenschaften.** Das Skript wird **idempotent**. Es wird **vom Workspace entkoppelt** — mehrere Zuordnungstabellen erlauben, **dasselbe Skript über mehrere Workspaces hinweg bereitzustellen**. Und da es Code ist, unterstützt es Variablen und Schleifen: Das gegebene Beispiel ist der Aufbau von zehn Teams identischer Struktur, wobei nur einige Namen geändert werden.

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

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

**Das Produkt setzt einen Agenten voraus.** Das SDK wird als gebaut *« for you or your coding agent »* präsentiert, und der Onboarding-Pfad besteht darin, einen Agenten die README des SDK lesen zu lassen. Ein typisierter State-Deskriptor ist tatsächlich ein besseres Werkzeug für einen Agenten als eine Reihe imperativer API-Aufrufe: Der Fehler ist dort wiederholbar statt kumulativ.

⚠️ **Was fehlt**: keine Erwähnung des Löschens von aus dem Skript entfernten Elementen, kein Vorschau-Modus vor der Anwendung, nichts zu Nebenläufigkeit, und kein Datum auf einer Dokumentation, die sich zwangsläufig ä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/