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 workspace para que coincida con él. Es el modelo Terraform, aplicado a páginas, bases de datos y equipos en lugar de recursos en la nube.
2. ⭐⭐ El mecanismo central — el identificador de recurso, y por qué lo hace todo. el script no contiene ningún identificador de Notion. Utiliza resourceIds 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 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 tabla de correspondencia por workspace, 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 un identificador lógico es lo que convierte un script de API en un descriptor de estado reutilizable. Es exactamente el papel que juegan las direcciones de recursos en un state de Terraform.
3. El contrato de la API, en dos pasos (asíncrono). POST /v1/infra_as_code (campos intents — la representación JSON serializada del script —, existingResources, existingProperties) devuelve un taskId; GET /v1/async_tasks/{taskId} se consulta hasta status: succeeded, llevando la respuesta createdRecordCounts, resourceIdToPointerMappings y resourceIdToPropertyIdMappings. Las dos tablas de correspondencia de salida son lo que debe persistirse — son el equivalente de un archivo de estado.
4. Dos diferencias operativas a conocer antes de probarlo.
5. Los tokens de acceso personal son obligatorios. , no los tokens de bot habituales de la API pública. ⚠️ Una consecuencia que la página no discute: las acciones se atribuyen a una persona, no a una integración — planteando la misma cuestión de responsabilidad que « who consumes, and on whose behalf » 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, entretejida 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 suponiendo que un agente lo usará, y el SDK tipado es precisamente lo que hace esto seguro: los tipos restringen lo que el agente puede describir, y la reconciliación hace que un error sea corregible mediante un 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 API imperativas — el error ahí es repetible, no acumulativo.
8. Limitaciones declaradas. solo puede crear o actualizar dentro de un workspace existente (incapacidad de crear un workspace); no todas las entidades están cubiertas — remitirse al archivo de definición de tipos del SDK, esperándose que funcionen las primitivas de alto nivel; límite de tasa reducido.
9. ⚠️ Lo que la página no dice, y debe tenerse en cuenta.
10. Ninguna mención de la destrucción. La API «crea o actualiza». ¿Qué ocurre con un elemento eliminado del script? Una verdadera herramienta de gestión 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 workspace real.
11. Ningún modo "plan". ni previsualización antes de aplicar. Se despliega y se observa.
12. Ninguna gestión de la concurrencia. no se discuten dos despliegues simultáneos en el mismo workspace.
13. Sin autor, sin fecha. Para una documentación de alfa en evolución, se trata de una carencia que hará que cualquier cita quede rápidamente desactualizada — de ahí fechar esta nota por observación.
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 motor reconocido es el agente de codificación, que necesita un formato descriptible, tipado y repetible en lugar de una secuencia de acciones. Vale la pena relacionarlo con la lógica de "un archivo en lugar de un equipo" de [[isenberg-meng-to-google-design-md-design-team-in-a-file-2026-05-06]], y con la disciplina de especificación versionada de [[lassiege-usine-logicielle-heure-ia-2026-07-28]].
15. Meta / enlaces cruzados. la cuestión del token personal y de actuar en nombre de otros en [[girard-acp-deux-protocoles-un-sigle-2026-08-02]]; la identidad del agente y el alcance de su 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]]; los artefactos declarativos impulsados por agentes en [[isenberg-meng-to-google-design-md-design-team-in-a-file-2026-05-06]].