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

## Veille

Pagina di documentazione di **Notion as Code**, pubblicata sul workspace **Notion Ambassadors** e consultata il **3 agosto 2026**. Prodotto in **alpha chiusa / lista d'attesa**, con un avviso in apertura: *« 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 uno spazio di lavoro 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 elementi costitutivi: un **SDK TypeScript** per descrivere lo stato desiderato, e un endpoint API pubblico `/v1/infra_as_code` per distribuirlo. **Il meccanismo che tiene insieme tutto è l'identificatore di risorsa**: lo script non contiene **alcun identificatore Notion**, solo *resource ID* scelti dall'autore; il primo deployment restituisce una **tabella di corrispondenza** `resourceId → RecordPointer`, che viene ripassata nelle chiamate successive in modo che gli stessi record vengano **aggiornati anziché ricreati**. Ne derivano tre proprietà, che sono le uniche che contano: lo script è **idempotente** (nuovo deployment = aggiornamento), è **disaccoppiato dallo workspace** (più tabelle di corrispondenza permettono di **distribuire lo stesso script su più workspace**), ed è **codice** — da cui variabili e cicli, 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 tramite `GET /v1/async_tasks/{taskId}` fino a `succeeded`. **Due differenze operative degne di nota**: il prodotto richiede **personal access token** anziché i consueti bot token dell'API pubblica, e il **rate limit è abbassato a 5 richieste al minuto** perché una chiamata non crea più una singola entità ma un batch. ⚠️ **Punto da registrare 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. **Limiti dichiarati**: impossibilità di creare un nuovo workspace, copertura parziale delle primitive, e una pagina senza autore né 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 corrispondenza, 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 change, agenti di coding, agente di coding, primitive supportate, tracker di feedback, 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 alpha. Né un annuncio marketing né un 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 change, accesso condizionato all'accettazione) prima di qualsiasi spiegazione del valore. Il registro è quello di un team che rilascia in anticipo e lo dichiara: emoji di allerta 🚧 e ⚠️ in testa alle sezioni, un rimando a un bug tracker, limiti elencati esplicitamente in chiusura.

**L'unica mossa retorica della pagina** è contenuta 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 corrispondenza, l'idempotenza, il deployment multi-workspace.

**Tratto degno di nota**: l'agente di coding è menzionato **come utente di prim'ordine**, due volte, senza enfasi — *« for you or your coding agent »*, *« either you or your favorite coding agent can open the readme »*. Non è una sezione "IA" 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 uno spazio di lavoro documentale**. Lo **stato finale desiderato** viene descritto in TypeScript, e Notion **riconcilia** lo 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**. Utilizza `resourceId` scelti dall'autore. Il primo deployment restituisce una **tabella di corrispondenza** `resourceId → RecordPointer`, che viene poi ripassata tramite `existingResources` / `existingProperties`. Ne derivano tre proprietà, inseparabili: 1. **Idempotenza** — un nuovo deployment aggiorna invece di ricreare. 2. **Disaccoppiamento dallo 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 corrispondenza 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 un identificatore logico è ciò che trasforma uno script API in un descrittore di stato riutilizzabile.** È esattamente il ruolo che gli indirizzi di risorsa svolgono in uno state file Terraform.
- **Il contratto dell'API, in due passaggi (asincrono)**: `POST /v1/infra_as_code` (campi `intents` — la 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 contiene `createdRecordCounts`, `resourceIdToPointerMappings` e `resourceIdToPropertyIdMappings`. **Le due tabelle di corrispondenza in uscita sono ciò che va conservato** — sono l'equivalente di un file di stato.
- **Due differenze operative da conoscere prima di provarlo**:
- **I personal access token sono obbligatori**, non i consueti bot token 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à del *« chi consuma, e per conto di chi »* 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.
- **⭐ Il riferimento agli agenti, inserito 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 presupponendo 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 con un nuovo deployment anziché con una pulizia manuale. **Un descrittore di stato tipizzato è uno strumento molto migliore per un agente rispetto a una serie di chiamate API imperative** — l'errore qui è ripetibile, non cumulativo.
- **Limiti dichiarati**: può solo creare o aggiornare **all'interno di uno workspace esistente** (impossibilità di creare uno workspace); **non tutte le entità sono coperte** — fare riferimento al file di definizione dei tipi dell'SDK, con le primitive di alto livello attese funzionare; rate limit abbassato.
- **⚠️ Cosa la pagina non dice, e va tenuto presente**:
- **Nessuna menzione della distruzione.** L'API "crea o aggiorna". Cosa succede a un elemento rimosso dallo script? Uno strumento di gestione dello stato vero 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 lo workspace effettivo.
- **Nessuna modalità "plan"** né anteprima prima dell'applicazione. Si distribuisce e si osserva.
- **Nessuna gestione della concorrenza**: due deployment simultanei sullo stesso workspace non sono 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 necessità di datare questa nota tramite osservazione.
- **Angolo di veille tecnologica — perché questo conta oltre Notion**: è un ulteriore segnale della **migrazione del modello dichiarativo fuori dall'infrastruttura**. Dopo il cloud, gli spazi di lavoro documentali; e il motore riconosciuto è l'agente di coding, che necessita di un formato **descrivibile, tipizzato, ripetibile** anziché una sequenza di azioni. Da mettere in relazione con la logica "un file anziché un team" di [[isenberg-meng-to-google-design-md-design-team-in-a-file-2026-05-06]], e con la disciplina della specifica versionata di [[lassiege-usine-logicielle-heure-ia-2026-07-28]].
- **Meta / rimandi incrociati**: la questione del token personale e dell'agire per conto altrui in [[girard-acp-deux-protocoles-un-sigle-2026-08-02]]; identità dell'agente e 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]]; artefatti dichiarativi guidati da agenti in [[isenberg-meng-to-google-design-md-design-team-in-a-file-2026-05-06]].

## RésuméDe400mots

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

**Il principio** è l'infrastructure as code applicata a uno spazio di lavoro 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 elementi costitutivi: un **SDK TypeScript** per descrivere lo stato desiderato, e l'endpoint **`/v1/infra_as_code`** per distribuirlo.

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

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

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

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

**Il prodotto presuppone un 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 è in effetti uno strumento migliore per un agente rispetto a una serie di chiamate API imperative: l'errore qui è ripetibile 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/