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

## Veille

Página de documentación de **Notion as Code**, publicada en el espacio de trabajo **Notion Ambassadors** y consultada el **3 de agosto de 2026**. Producto en **alfa cerrada / lista de espera**, con una advertencia inicial: *« This product is under development so we recommend you try it out in a new workspace vs. your primary workspace »* y *« There may be breaking changes until we're fully launched »*. **El principio es infraestructura como código aplicada a un espacio de trabajo documental**: *« Instead of having to make individual public API requests, you can describe the final state and we handle updating your workspace to match. »* Dos bloques constitutivos: un **SDK TypeScript** para describir el estado deseado, y un **endpoint de API pública** `/v1/infra_as_code` para desplegarlo. **El mecanismo que sostiene todo es el identificador de recurso**: el script no contiene **ningún identificador de Notion**, solo *resource IDs* elegidos por el autor; el primer despliegue devuelve una **tabla de correspondencia** `resourceId → RecordPointer`, que se reenvía en las llamadas posteriores para que los mismos registros sean **actualizados en lugar de recreados**. De ahí se derivan tres propiedades, y son las únicas que importan: el script es **idempotente** (redespliegue = actualización), está **desacoplado del espacio de trabajo** (varias tablas de correspondencia permiten desplegar **el mismo script en varios espacios de trabajo**), y es **código** — de ahí variables y bucles, con el ejemplo dado de *« build 10 teams that all have a very similar structure and just need some nouns renamed »*. **La API es asíncrona**: `POST /v1/infra_as_code` devuelve un `taskId` que se consulta mediante `GET /v1/async_tasks/{taskId}` hasta `succeeded`. **Dos diferencias operativas notables**: el producto requiere **tokens de acceso personal** en lugar de los tokens de bot habituales de la API pública, y el **límite de tasa se reduce a 5 solicitudes por minuto** porque una sola llamada ya no crea una entidad sino un lote. **Punto a destacar para este corpus**: la página está explícitamente escrita para un uso asistido — *« A typescript SDK for you **or your coding agent** to describe what you want »* —, y la vía de entrada recomendada es clonar el SDK en una rama experimental y dejar que *« either you or your favorite coding agent »* abra el README. **Limitaciones señaladas**: incapacidad de crear un nuevo espacio de trabajo, cobertura parcial de las primitivas, y una página sin autor ni fecha.

## 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, infraestructura como código, IaC, estado deseado, reconciliación, idempotencia, SDK TypeScript, notion-sdk-js, rama experimental, API pública, infra_as_code, endpoint asíncrono, taskId, async_tasks, polling, resource ID, identificador de recurso, RecordPointer, tabla de correspondencia, mapping, existingResources, existingProperties, intents, despliegue multi-espacio de trabajo, reutilización de patrones, variables y bucles, tokens de acceso personal, token de acceso personal, límite de tasa, 5 solicitudes por minuto, alfa, lista de espera, cambios disruptivos, agentes de codificación, agente de codificación, primitivas soportadas, rastreador de comentarios, 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

**Perfil**: documentación breve y operativa de un producto alfa. Ni anuncio de marketing ni artículo en profundidad — una página de incorporación que funciona a la vez como **especificación de API** (tablas campo / tipo / descripción para la solicitud y respuesta de ambos endpoints).

**Estilo**: **advertencias primero, mecanismo después**. La página se abre con tres avisos (producto en desarrollo, posibles cambios disruptivos, acceso condicionado a la aceptación) antes de cualquier explicación de valor. El registro es el de un equipo que lanza en fase temprana y lo dice: emojis de alerta 🚧 al principio y en los encabezados de sección, un enlace a un rastreador de incidencias, limitaciones enumeradas explícitamente al cierre.

**El único movimiento retórico de la página** cabe en una frase, y es el que justifica la existencia del producto: *« Instead of having to make individual public API requests, you can describe the final state and we handle updating your workspace to match. »* Todo lo demás se deriva de ahí — la tabla de correspondencia, la idempotencia, el soporte multi-espacio de trabajo.

**Rasgo destacable**: el agente de codificación se menciona **como un usuario de pleno derecho**, dos veces, sin énfasis — *« for you or your coding agent »*, *« either you or your favorite coding agent can open the readme »*. No es una sección "IA" añadida a posteriori: está integrada en la descripción del producto como un dato de partida.

**Frases marcadoras**: *« 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

- **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.
- **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.
- **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.
- **Dos diferencias operativas que conviene conocer antes de probarlo**:
- **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**.
- **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.
- **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.
- **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.
- **Lo que la página no dice, y conviene tener presente**:
- **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.
- **Sin modo "plan"** ni vista previa antes de aplicar. Se despliega y se observa.
- **Sin gestión de la concurrencia**: no se aborda el caso de dos despliegues simultáneos en el mismo espacio de trabajo.
- **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.
- **Á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]].
- **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.

## RésuméDe400mots

Documentación de **Notion as Code**, un producto en **alfa cerrada**, consultada el 3 de agosto de 2026 en el espacio de trabajo Notion Ambassadors — sin autor ni fecha, y con una advertencia que recomienda probarlo en un espacio de trabajo nuevo y alerta sobre posibles cambios disruptivos.

**El principio** es infraestructura como código aplicada a un espacio de trabajo documental: *« Instead of having to make individual public API requests, you can describe the final state and we handle updating your workspace to match. »* Dos bloques constitutivos: un **SDK TypeScript** para describir el estado deseado, y el endpoint **`/v1/infra_as_code`** para desplegarlo.

**El mecanismo que sostiene todo** es la indirección de identificadores. El script **no contiene ningún identificador de Notion**: declara valores `resourceId` elegidos por el autor. El primer despliegue devuelve una **tabla de correspondencia** entre estos identificadores lógicos y los registros efectivamente creados; reenviada en las llamadas posteriores, garantiza que los mismos registros sean **actualizados en lugar de recreados**.

**Se derivan tres propiedades.** El script se vuelve **idempotente**. Se vuelve **desacoplado del espacio de trabajo** — varias tablas de correspondencia permiten desplegar **el mismo script en varios espacios de trabajo**. Y al ser código, admite variables y bucles: el ejemplo dado consiste en crear diez equipos de estructura idéntica cambiando solo unos pocos sustantivos.

**El contrato de la API es asíncrono**: un `POST` devuelve un `taskId`, que se consulta hasta su finalización; la respuesta lleva las tablas de correspondencia que hay que conservar — el equivalente de un archivo de estado.

**Dos diferencias operativas**: el producto requiere **tokens de acceso personal** en lugar de los tokens de bot habituales, lo que atribuye las acciones a una persona en lugar de a una integración; y el **límite de tasa baja a 5 solicitudes por minuto**, ya que una llamada es ahora un lote y no una entidad única.

**El producto asume al agente.** El SDK se presenta como creado *« for you or your coding agent »*, y la vía de incorporación consiste en dejar que un agente lea el README del SDK. Un descriptor de estado tipado es, en efecto, una herramienta mejor para un agente que una serie de llamadas imperativas: el error ahí es reproducible en lugar de acumulativo.

**Lo que falta**: ninguna mención a la eliminación de elementos retirados del script, ningún modo de vista previa antes de aplicar, nada sobre concurrencia, y ninguna fecha en una documentación destinada a cambiar.

## 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/es/fiches/notion-as-code-2026-08-03/