How to use Notion as Code

Punti chiave

1. ⭐ 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.
2. ⭐⭐ 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.
3. 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.
4. Due differenze operative da conoscere prima di provarlo.
5. 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.
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. ⭐ 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.
8. 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.
9. ⚠️ Cosa la pagina non dice, e va tenuto presente.
10. 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.
11. Nessuna modalità "plan". né anteprima prima dell'applicazione. Si distribuisce e si osserva.
12. Nessuna gestione della concorrenza. due deployment simultanei sullo stesso workspace non sono 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 necessità di datare questa nota tramite osservazione.
14. 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]].
15. 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]].