How to use Notion as Code

Punti chiave

1. 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.
2. 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.
3. 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.
4. Due differenze operative da conoscere prima di provarlo.
5. 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.
6. 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.
7. 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.
8. 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.
9. Ciò che la pagina non dice, e che va tenuto presente.
10. 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.
11. Nessuna modalità "plan". e nessuna anteprima prima dell'applicazione. Si distribuisce e si osserva.
12. Nessuna gestione della concorrenza. due deployment simultanei sullo stesso workspace non vengono discussi.
13. 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.
14. 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]].
15. 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.