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

## Veille

Pagina di documentazione **Notion as Code**, pubblicata sul workspace **Notion Ambassadors** e consultata il **3 agosto 2026**. Prodotto in **alpha chiusa / lista d'attesa**, con un avviso iniziale: *« This product is under development so we recommend you try it out in a new workspace vs. your primary workspace »* e *« There may be breaking changes until we're fully launched »*. **Il principio è l'infrastructure as code applicata a un workspace documentale**: *« Instead of having to make individual public API requests, you can describe the final state and we handle updating your workspace to match. »* Due componenti fondamentali: un **SDK TypeScript** per descrivere lo stato desiderato, e un **endpoint API pubblico** `/v1/infra_as_code` per implementarlo. **Il meccanismo che tiene tutto insieme è l'identificatore di risorsa**: lo script non contiene **alcun identificatore Notion**, solo *resource ID* scelti dall'autore; il primo deployment restituisce una **tabella di mappatura** `resourceId → RecordPointer`, che viene ripassata nelle chiamate successive in modo che gli stessi record vengano **aggiornati anziché ricreati**. Ne derivano tre proprietà, e sono le uniche che contano: lo script è **idempotente** (ridistribuzione = aggiornamento), è **disaccoppiato dal workspace** (più tabelle di mappatura permettono di distribuire **lo stesso script su più workspace**), ed è **codice** — da cui variabili e cicli, con l'esempio fornito *« build 10 teams that all have a very similar structure and just need some nouns renamed »*. **L'API è asincrona**: `POST /v1/infra_as_code` restituisce un `taskId` interrogato via `GET /v1/async_tasks/{taskId}` fino a `succeeded`. **Due differenze operative degne di nota**: il prodotto richiede **personal access token** anziché i consueti token bot dell'API pubblica, e il **rate limit è abbassato a 5 richieste al minuto** perché una singola chiamata non crea più una sola entità ma un batch. **Punto da annotare per questo corpus**: la pagina è esplicitamente scritta per un uso assistito — *« A typescript SDK for you **or your coding agent** to describe what you want »* —, e il percorso di ingresso consigliato è clonare l'SDK su un branch sperimentale e lasciare che *« either you or your favorite coding agent »* apra il README. **Limitazioni dichiarate**: impossibilità di creare un nuovo workspace, copertura parziale dei primitivi, e una pagina priva di autore o data.

## 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, stato desiderato, riconciliazione, idempotenza, SDK TypeScript, notion-sdk-js, branch sperimentale, API pubblica, infra_as_code, endpoint asincrono, taskId, async_tasks, polling, resource ID, identificatore di risorsa, RecordPointer, tabella di mappatura, mapping, existingResources, existingProperties, intents, deployment multi-workspace, riutilizzo di pattern, variabili e cicli, personal access token, personal access token, rate limit, 5 richieste al minuto, alpha, lista d'attesa, breaking changes, coding agent, coding agent, primitivi supportati, 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

**Profilo**: documentazione breve e operativa di un prodotto in alpha. Né annuncio di marketing né articolo approfondito — una pagina di onboarding che funge anche da **specifica API** (tabelle campo / tipo / descrizione per la richiesta e la risposta di entrambi gli endpoint).

**Stile**: **prima gli avvisi, poi il meccanismo**. La pagina si apre con tre avvertenze (prodotto in sviluppo, possibili breaking changes, accesso subordinato all'accettazione) prima di qualsiasi spiegazione del valore. Il registro è quello di un team che rilascia in anticipo e lo dichiara apertamente: emoji di allerta 🚧 in testa e nelle intestazioni delle sezioni, un link a un issue tracker, limitazioni esplicitamente elencate in chiusura.

**L'unica mossa retorica della pagina** sta in una frase, ed è quella che giustifica l'esistenza del prodotto: *« Instead of having to make individual public API requests, you can describe the final state and we handle updating your workspace to match. »* Tutto il resto ne discende — la tabella di mappatura, l'idempotenza, il supporto multi-workspace.

**Tratto notevole**: l'agente di codifica è menzionato **come utente a pieno titolo**, due volte, senza enfasi — *« for you or your coding agent »*, *« either you or your favorite coding agent can open the readme »*. Non è una sezione "AI" aggiunta a posteriori: è integrata nella descrizione del prodotto come un dato di fatto.

**Frasi marcatrici**: *« 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

- **Cos'è, in una frase**: **infrastructure as code per un workspace documentale**. Lo **stato finale desiderato** viene descritto in TypeScript, e Notion **riconcilia** il workspace per farlo corrispondere. È il modello Terraform, applicato a pagine, database e team anziché a risorse cloud.
- **Il meccanismo centrale — l'identificatore di risorsa, e perché fa tutto**: lo script **non contiene alcun identificatore Notion**. Usa valori `resourceId` scelti dall'autore. Il primo deployment restituisce una **tabella di mappatura** `resourceId → RecordPointer`, che viene poi ripassata tramite `existingResources` / `existingProperties`. Ne derivano tre proprietà, inseparabili tra loro: 1. **Idempotenza** — ridistribuire aggiorna anziché ricreare. 2. **Disaccoppiamento dal 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 »*: **una tabella di mappatura per workspace**, un unico script. 3. **Programmabilità** — è codice, da cui variabili e cicli: *« build 10 teams that all have a very similar structure and just need some nouns renamed »*. → **L'indirezione tramite identificatore logico è ciò che trasforma uno script API in un descrittore di stato riutilizzabile.** È esattamente il ruolo che gli indirizzi di risorsa svolgono nello state di Terraform.
- **Il contratto API, in due fasi (asincrono)**: `POST /v1/infra_as_code` (campi `intents` — una rappresentazione JSON serializzata dello script —, `existingResources`, `existingProperties`) restituisce un `taskId`; `GET /v1/async_tasks/{taskId}` viene interrogato fino a `status: succeeded`, con la risposta che porta `createdRecordCounts`, `resourceIdToPointerMappings` e `resourceIdToPropertyIdMappings`. **Le due tabelle di mappatura in uscita sono ciò che deve essere conservato** — sono l'equivalente di un file di stato.
- **Due differenze operative da conoscere prima di provarlo**:
- **Personal access token obbligatori**, anziché i consueti token bot dell'API pubblica. Una conseguenza che la pagina non discute: le azioni sono attribuite a **una persona**, non a un'integrazione — sollevando la stessa questione di responsabilità di *« who consumes, and on whose behalf »* in [[girard-acp-deux-protocoles-un-sigle-2026-08-02]]. Un agente che effettua il deployment con il token personale di un amministratore agisce **per suo conto**.
- **5 richieste al minuto**, *« since this API is not a 1 request → 1 entity created or updated »*. Il tasso è abbassato perché una chiamata è un batch.
- **La menzione degli agenti, inserita senza enfasi**: *« A typescript SDK for **you or your coding agent** to describe what you want in your Notion workspace »*, e il percorso consigliato è clonare l'SDK e poi lasciare che *« either you or your favorite coding agent »* legga il README. → **Il prodotto è progettato assumendo che un agente lo utilizzi**, e l'SDK tipizzato è precisamente ciò che rende questo sicuro: i tipi vincolano ciò che l'agente può descrivere, e la riconciliazione rende un errore correggibile tramite un nuovo deployment anziché una pulizia manuale. **Un descrittore di stato tipizzato è uno strumento di gran lunga migliore per un agente rispetto a una serie di chiamate API imperative** — l'errore vi è replicabile, non cumulativo.
- **Limitazioni dichiarate**: può solo creare o aggiornare **all'interno di un workspace esistente** (impossibilità di creare un workspace); **non tutte le entità sono coperte** — fare riferimento al file di definizione dei tipi dell'SDK, con i primitivi di alto livello che dovrebbero funzionare; rate limit abbassato.
- **Ciò che la pagina non dice, e che va tenuto presente**:
- **Nessuna menzione della distruzione.** L'API "crea o aggiorna". Cosa succede a un elemento rimosso dallo script? Un vero strumento di gestione dello stato sa eliminare ciò che non è più dichiarato — qui nulla lo indica, il che suggerisce una riconciliazione **additiva** e quindi una possibile deriva tra lo script e il workspace effettivo.
- **Nessuna modalità "plan"** e nessuna anteprima prima dell'applicazione. Si distribuisce e si osserva.
- **Nessuna gestione della concorrenza**: due deployment simultanei sullo stesso workspace non vengono discussi.
- **Nessun autore, nessuna data.** Per una documentazione alpha in evoluzione, si tratta di una lacuna che renderà rapidamente obsoleta qualsiasi citazione — da cui la datazione basata sull'osservazione in questa scheda.
- **Angolo di veille — perché questo conta al di là di Notion**: è un ulteriore segnale della **migrazione del modello dichiarativo fuori dall'infrastruttura**. Dopo il cloud, i workspace documentali; e il fattore scatenante riconosciuto è l'agente di codifica, che necessita di un **formato descrivibile, tipizzato, replicabile** anziché di una sequenza di azioni. Da mettere in relazione con la logica "un file anziché un team" in [[isenberg-meng-to-google-design-md-design-team-in-a-file-2026-05-06]], e con la disciplina della specifica versionata in [[lassiege-usine-logicielle-heure-ia-2026-07-28]].
- **Meta / riferimenti incrociati**: la questione del token personale e dell'agire per conto altrui in [[girard-acp-deux-protocoles-un-sigle-2026-08-02]]; l'identità di un agente e il suo ambito d'azione in uber-engineering-agent-identity-crisis-zero-trust-spire-2026-05-21 e valente-zalewski-beyond-zero-enterprise-security-ai-era-2026-07-20; gli artefatti dichiarativi guidati da agente in isenberg-meng-to-google-design-md-design-team-in-a-file-2026-05-06.

## RésuméDe400mots

Documentazione **Notion as Code**, un prodotto in **alpha chiusa**, consultata il 3 agosto 2026 sul workspace Notion Ambassadors — senza autore né data, e con un avviso che raccomanda di provarlo su un workspace nuovo e mette in guardia su possibili breaking changes.

**Il principio** è l'infrastructure as code applicata a un workspace documentale: *« Instead of having to make individual public API requests, you can describe the final state and we handle updating your workspace to match. »* Due componenti fondamentali: un **SDK TypeScript** per descrivere lo stato desiderato, e l'endpoint **`/v1/infra_as_code`** per implementarlo.

**Il meccanismo che regge tutto** è l'indirezione tramite identificatore. Lo script **non contiene alcun identificatore Notion**: dichiara valori `resourceId` scelti dall'autore. Il primo deployment restituisce una **tabella di mappatura** tra questi identificatori logici e i record effettivamente creati; ripassata nelle chiamate successive, garantisce che gli stessi record vengano **aggiornati anziché ricreati**.

**Ne derivano tre proprietà.** Lo script diventa **idempotente**. Diventa **disaccoppiato dal workspace** — più tabelle di mappatura permettono di distribuire **lo stesso script su più workspace**. E trattandosi di codice, supporta variabili e cicli: l'esempio fornito è la costruzione di dieci team di struttura identica cambiando solo alcuni nomi.

**Il contratto API è asincrono**: una `POST` restituisce un `taskId`, interrogato fino al completamento; la risposta porta le tabelle di mappatura da conservare — l'equivalente di un file di stato.

**Due differenze operative**: il prodotto richiede **personal access token** anziché i consueti token bot, il che attribuisce le azioni a una persona anziché a un'integrazione; e il **rate limit scende a 5 richieste al minuto**, una chiamata essendo ormai un batch anziché una singola entità.

**Il prodotto presuppone l'agente.** L'SDK è presentato come costruito *« for you or your coding agent »*, e il percorso di onboarding consiste nel lasciare che un agente legga il README dell'SDK. Un descrittore di stato tipizzato è effettivamente uno strumento migliore per un agente rispetto a una serie di chiamate imperative: l'errore vi è replicabile anziché cumulativo.

**Cosa manca**: nessuna menzione dell'eliminazione degli elementi rimossi dallo script, nessuna modalità di anteprima prima dell'applicazione, nulla sulla concorrenza, e nessuna data su una documentazione destinata a cambiare.

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