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

## Veille

**Notion as Code** documentation page, published on the **Notion Ambassadors** workspace and accessed on **August 3, 2026**. Product in **closed alpha / waitlist**, with a warning up front: *« This product is under development so we recommend you try it out in a new workspace vs. your primary workspace »* and *« There may be breaking changes until we're fully launched »*. **The principle is infrastructure as code applied to a documentary workspace**: *« Instead of having to make individual public API requests, you can describe the final state and we handle updating your workspace to match. »* Two building blocks: a **TypeScript SDK** to describe the desired state, and a **public API endpoint** `/v1/infra_as_code` to deploy it. **The mechanism that holds everything together is the resource identifier**: the script contains **no Notion identifier**, only *resource IDs* chosen by the author; the first deployment returns a **mapping table** `resourceId → RecordPointer`, which is passed back on subsequent calls so the same records are **updated rather than recreated**. Three properties follow, and they are the only ones that matter: the script is **idempotent** (re-deployment = update), it is **decoupled from the workspace** (multiple mapping tables allow **the same script to be deployed across several workspaces**), and it is **code** — hence variables and loops, the given example being *« build 10 teams that all have a very similar structure and just need some nouns renamed »*. **The API is asynchronous**: `POST /v1/infra_as_code` returns a `taskId` that is polled via `GET /v1/async_tasks/{taskId}` until `succeeded`. **Two notable operational differences**: the product requires **personal access tokens** rather than the usual bot tokens of the public API, and the **rate limit is lowered to 5 requests per minute** because a call no longer creates a single entity but a batch. ⚠️ **Point worth recording for this corpus**: the page is explicitly written for assisted use — *« A typescript SDK for you **or your coding agent** to describe what you want »* —, and the recommended entry path is to clone the SDK on an experimental branch and let *« either you or your favorite coding agent »* open the README. **Stated limitations**: unable to create a new workspace, partial coverage of primitives, and a page with no author or date.

## 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, desired state, reconciliation, idempotence, TypeScript SDK, notion-sdk-js, experimental branch, public API, infra_as_code, asynchronous endpoint, taskId, async_tasks, polling, resource ID, resource identifier, RecordPointer, mapping table, mapping, existingResources, existingProperties, intents, multi-workspace deployment, pattern reuse, variables and loops, personal access tokens, personal access token, rate limit, 5 requests per minute, alpha, waitlist, breaking changes, coding agents, coding agent, supported primitives, 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

**Profile**: brief, operational alpha product documentation. Neither a marketing announcement nor an in-depth article — an onboarding page doubling as an **API specification** (field / type / description tables for the request and response of both endpoints).

**Style**: **warnings first, mechanism second**. The page opens with three caveats (product under development, possible breaking changes, access gated behind acceptance) before any explanation of value. The register is that of a team shipping early and saying so: alert emojis 🚧 and ⚠️ at the top of sections, a pointer to a bug tracker, limitations listed explicitly at the close.

**The page's single rhetorical move** is contained in one sentence, and it is the one that justifies the product's existence: *« Instead of having to make individual public API requests, you can describe the final state and we handle updating your workspace to match. »* Everything else follows from it — the mapping table, idempotence, multi-workspace deployment.

**Notable trait**: the coding agent is mentioned **as a first-class user**, twice, without emphasis — *« for you or your coding agent »*, *« either you or your favorite coding agent can open the readme »*. This is not a bolted-on "AI" section: it is woven into the product description as a given.

**Marker phrases**: *« 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

- **⭐ What it is, in one sentence**: **infrastructure as code for a documentary workspace**. The **desired final state** is described in TypeScript, and Notion **reconciles** the workspace to match it. This is the Terraform model, applied to pages, databases, and teams rather than cloud resources.
- **⭐⭐ The core mechanism — the resource identifier, and why it does everything**: the script **contains no Notion identifier**. It uses `resourceId`s chosen by the author. The first deployment returns a **mapping table** `resourceId → RecordPointer`, which is then passed back via `existingResources` / `existingProperties`. Three properties follow from this, and they are inseparable: 1. **Idempotence** — re-deploying updates instead of recreating. 2. **Decoupling from the 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 »*: **one mapping table per workspace**, a single script. 3. **Programmability** — it is code, hence variables and loops: *« build 10 teams that all have a very similar structure and just need some nouns renamed »*. → **Indirection through a logical identifier is what turns an API script into a reusable state descriptor.** This is exactly the role resource addresses play in a Terraform state.
- **The API contract, in two steps (asynchronous)**: `POST /v1/infra_as_code` (fields `intents` — the serialized JSON representation of the script —, `existingResources`, `existingProperties`) returns a `taskId`; `GET /v1/async_tasks/{taskId}` is polled until `status: succeeded`, the response carrying `createdRecordCounts`, `resourceIdToPointerMappings`, and `resourceIdToPropertyIdMappings`. **The two output mapping tables are what must be persisted** — they are the equivalent of a state file.
- **Two operational differences to know before trying it**:
- **Personal access tokens are mandatory**, not the public API's usual bot tokens. ⚠️ A consequence the page does not discuss: actions are attributed to **a person**, not an integration — raising the same accountability question as *« who consumes, and on whose behalf »* in [[girard-acp-deux-protocoles-un-sigle-2026-08-02]]. An agent that deploys with an administrator's personal token acts **on their behalf**.
- **5 requests per minute**, *« since this API is not a 1 request → 1 entity created or updated »*. The rate is lowered because a call is a batch.
- **⭐ The mention of agents, woven in without emphasis**: *« A typescript SDK for **you or your coding agent** to describe what you want in your Notion workspace »*, and the recommended path is to clone the SDK and then let *« either you or your favorite coding agent »* read the README. → **The product is designed assuming an agent will use it**, and the typed SDK is precisely what makes this safe: the types constrain what the agent can describe, and reconciliation makes an error fixable by re-deployment rather than manual cleanup. **A typed state descriptor is a far better tool for an agent than a series of imperative API calls** — the error there is replayable, not cumulative.
- **Stated limitations**: can only create or update **within an existing workspace** (unable to create a workspace); **not all entities are covered** — refer to the SDK's type definition file, with high-level primitives expected to work; lowered rate limit.
- **⚠️ What the page doesn't say, and should be kept in mind**:
- **No mention of destruction.** The API "creates or updates." What happens to an element removed from the script? A true state-management tool knows how to delete what is no longer declared — here, nothing indicates this, which suggests an **additive** reconciliation and thus possible drift between the script and the actual workspace.
- **No "plan" mode** or preview before applying. One deploys and observes.
- **No concurrency handling**: two simultaneous deployments on the same workspace are not discussed.
- **No author, no date.** For evolving alpha documentation, this is a gap that will make any citation quickly outdated — hence dating this note by observation.
- **Tech-watch angle — why this matters beyond Notion**: this is one more signal of the **declarative model migrating out of infrastructure**. After the cloud, documentary workspaces; and the acknowledged driver is the coding agent, which needs a **describable, typed, replayable format** rather than a sequence of actions. Worth relating to the "one file rather than one team" logic of [[isenberg-meng-to-google-design-md-design-team-in-a-file-2026-05-06]], and to the versioned-specification discipline of [[lassiege-usine-logicielle-heure-ia-2026-07-28]].
- **Meta / cross-links**: the personal-token and acting-on-behalf-of-others question in [[girard-acp-deux-protocoles-un-sigle-2026-08-02]]; agent identity and scope of action in [[uber-engineering-agent-identity-crisis-zero-trust-spire-2026-05-21]] and [[valente-zalewski-beyond-zero-enterprise-security-ai-era-2026-07-20]]; agent-driven declarative artifacts in [[isenberg-meng-to-google-design-md-design-team-in-a-file-2026-05-06]].

## RésuméDe400mots

**Notion as Code** documentation, a product in **closed alpha**, accessed on August 3, 2026 on the Notion Ambassadors workspace — with no author or date, and a warning recommending trying it on a fresh workspace and cautioning about possible breaking changes.

**The principle** is infrastructure as code applied to a documentary workspace: *« Instead of having to make individual public API requests, you can describe the final state and we handle updating your workspace to match. »* Two building blocks: a **TypeScript SDK** to describe the desired state, and the **`/v1/infra_as_code`** endpoint to deploy it.

**The mechanism that carries everything** is identifier indirection. The script **contains no Notion identifier**: it declares `resourceId`s chosen by the author. The first deployment returns a **mapping table** between these logical identifiers and the records actually created; passed back on subsequent calls, it makes the same records **updated rather than recreated**.

**Three properties follow.** The script becomes **idempotent**. It becomes **decoupled from the workspace** — multiple mapping tables allow **the same script to be deployed across several workspaces**. And since it is code, it supports variables and loops: the given example is building ten teams of identical structure while changing only a few names.

**The API contract is asynchronous**: a `POST` returns a `taskId`, which is polled until completion; the response carries the mapping tables to persist — the equivalent of a state file.

**Two operational differences**: the product requires **personal access tokens** rather than the usual bot tokens, which attributes actions to a person rather than an integration; and the **rate limit drops to 5 requests per minute**, since a call is now a batch rather than a single entity.

**The product assumes an agent.** The SDK is presented as built *« for you or your coding agent »*, and the onboarding path is to let an agent read the SDK's README. A typed state descriptor is indeed a better tool for an agent than a series of imperative API calls: the error there is replayable rather than cumulative.

⚠️ **What's missing**: no mention of deleting elements removed from the script, no preview mode before applying, nothing on concurrency, and no date on documentation that is bound to change.

## 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/en/fiches/notion-as-code-2026-08-03/