How to use Notion as Code

Puntos clave

1. Qué es, en una frase. infraestructura como código para un espacio de trabajo documental. El estado final deseado se describe en TypeScript, y Notion reconcilia el espacio de trabajo para ajustarlo. Es el modelo Terraform, aplicado a páginas, bases de datos y equipos en lugar de recursos cloud.
2. El mecanismo central — el identificador de recurso, y por qué lo hace todo. el script no contiene ningún identificador de Notion. Utiliza valores resourceId elegidos por el autor. El primer despliegue devuelve una tabla de correspondencia resourceId → RecordPointer, que luego se reenvía mediante existingResources / existingProperties. De ahí se derivan tres propiedades, y son inseparables: 1. Idempotencia — redesplegar actualiza en lugar de recrear. 2. Desacoplamiento del espacio de trabajo — « 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 tabla de correspondencia por espacio de trabajo, un único script. 3. Programabilidad — es código, de ahí variables y bucles: « build 10 teams that all have a very similar structure and just need some nouns renamed ». → La indirección mediante identificador lógico es lo que convierte un script de API en un descriptor de estado reutilizable. Es exactamente el papel que desempeñan las direcciones de recurso en el estado de Terraform.
3. El contrato de la API, en dos pasos (asíncrono). POST /v1/infra_as_code (campos intents — una representación JSON serializada del script —, existingResources, existingProperties) devuelve un taskId; GET /v1/async_tasks/{taskId} se consulta hasta status: succeeded, y la respuesta lleva createdRecordCounts, resourceIdToPointerMappings y resourceIdToPropertyIdMappings. Las dos tablas de correspondencia de salida son lo que hay que conservar — son el equivalente de un archivo de estado.
4. Dos diferencias operativas que conviene conocer antes de probarlo.
5. Tokens de acceso personal obligatorios. , en lugar de los tokens de bot habituales de la API pública. Una consecuencia que la página no aborda: las acciones se atribuyen a una persona, no a una integración — lo que plantea la misma cuestión de responsabilidad que « quién consume, y en nombre de quién » en [[girard-acp-deux-protocoles-un-sigle-2026-08-02]]. Un agente que despliega con el token personal de un administrador actúa en su nombre.
6. 5 solicitudes por minuto. , « since this API is not a 1 request → 1 entity created or updated ». La tasa se reduce porque una llamada es un lote.
7. La mención de los agentes, integrada sin énfasis. « A typescript SDK for you or your coding agent to describe what you want in your Notion workspace », y la vía recomendada es clonar el SDK y luego dejar que « either you or your favorite coding agent » lea el README. → El producto está diseñado partiendo de la base de que un agente lo usará, y el SDK tipado es precisamente lo que lo hace seguro: los tipos limitan lo que el agente puede describir, y la reconciliación hace que un error sea corregible mediante redespliegue en lugar de una limpieza manual. Un descriptor de estado tipado es una herramienta mucho mejor para un agente que una serie de llamadas de API imperativas — el error ahí es reproducible, no acumulativo.
8. Limitaciones señaladas. solo puede crear o actualizar dentro de un espacio de trabajo existente (incapacidad de crear un espacio de trabajo); no todas las entidades están cubiertas — remite al archivo de definición de tipos del SDK, con las primitivas de alto nivel que se espera que funcionen; límite de tasa reducido.
9. Lo que la página no dice, y conviene tener presente.
10. Ninguna mención a la destrucción. La API «crea o actualiza». ¿Qué ocurre con un elemento retirado del script? Una verdadera herramienta de estado sabe eliminar lo que ya no está declarado — aquí nada lo indica, lo que sugiere una reconciliación aditiva y, por tanto, una posible deriva entre el script y el espacio de trabajo real.
11. Sin modo "plan". ni vista previa antes de aplicar. Se despliega y se observa.
12. Sin gestión de la concurrencia. no se aborda el caso de dos despliegues simultáneos en el mismo espacio de trabajo.
13. Sin autor, sin fecha. Para una documentación alfa en evolución, es una carencia que hará que cualquier cita quede rápidamente desactualizada — de ahí la datación basada en la observación en esta ficha.
14. Ángulo de vigilancia tecnológica — por qué esto importa más allá de Notion. es una señal más de la migración del modelo declarativo fuera de la infraestructura. Después de la nube, los espacios de trabajo documentales; y el desencadenante reconocido es el agente de codificación, que necesita un formato describible, tipado, reproducible en lugar de una secuencia de acciones. Vale la pena relacionarlo con la lógica del "un archivo en lugar de un equipo" en [[isenberg-meng-to-google-design-md-design-team-in-a-file-2026-05-06]], y con la disciplina de especificación versionada en [[lassiege-usine-logicielle-heure-ia-2026-07-28]].
15. Meta / referencias cruzadas. la cuestión del token personal y actuar en nombre de otro en [[girard-acp-deux-protocoles-un-sigle-2026-08-02]]; la identidad de un agente y su alcance de acción en uber-engineering-agent-identity-crisis-zero-trust-spire-2026-05-21 y valente-zalewski-beyond-zero-enterprise-security-ai-era-2026-07-20; artefactos declarativos impulsados por agentes en isenberg-meng-to-google-design-md-design-team-in-a-file-2026-05-06.