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

## Veille

Página de documentación de **Notion as Code**, publicada en el workspace **Notion Ambassadors** y consultada el **3 de agosto de 2026**. Producto en **alfa cerrada / lista de espera**, con una advertencia previa: *« 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 la 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** (redesplegar = actualizar), está **desacoplado del workspace** (varias tablas de correspondencia permiten **desplegar el mismo script en varios workspaces**), y es **código** — de ahí variables y bucles, siendo el ejemplo dado *« 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 llamada ya no crea una sola 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 declaradas**: incapacidad de crear un nuevo workspace, 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, ID de recurso, identificador de recurso, RecordPointer, tabla de correspondencia, correspondencia, existingResources, existingProperties, intents, despliegue multi-workspace, 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, breaking changes, agentes de codificación, agente de codificación, primitivas admitidas, rastreador de feedback, 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 de producto alfa breve y operativa. Ni un anuncio de marketing ni un 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 la respuesta de ambos endpoints).

**Estilo**: **advertencias primero, mecanismo después**. La página se abre con tres advertencias (producto en desarrollo, posibles breaking changes, acceso condicionado a una aceptación) antes de cualquier explicación del valor. El registro es el de un equipo que lanza pronto y lo dice: emojis de alerta 🚧 y ⚠️ al inicio de las secciones, una referencia a un rastreador de errores, limitaciones enumeradas explícitamente al cierre.

**El único movimiento retórico de la página** está contenido en una frase, y es la 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 despliegue multi-workspace.

**Rasgo notable**: 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 se trata de una sección de "IA" añadida a posteriori: está entretejida 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 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.
- **⭐⭐ El mecanismo central — el identificador de recurso, y por qué lo hace todo**: el script **no contiene ningún identificador de Notion**. Utiliza `resourceId`s 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.
- **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.
- **Dos diferencias operativas a conocer antes de probarlo**:
- **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**.
- **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, 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.
- **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.
- **⚠️ Lo que la página no dice, y debe tenerse en cuenta**:
- **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.
- **Ningún modo "plan"** ni previsualización antes de aplicar. Se despliega y se observa.
- **Ninguna gestión de la concurrencia**: no se discuten dos despliegues simultáneos en el mismo workspace.
- **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.
- **Á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]].
- **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]].

## RésuméDe400mots

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

**El principio** es la 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 `resourceId`s elegidos por el autor. El primer despliegue devuelve una **tabla de correspondencia** entre estos identificadores lógicos y los registros realmente creados; reenviada en las llamadas posteriores, hace que los mismos registros sean **actualizados en lugar de recreados**.

**De ahí se derivan tres propiedades.** El script se vuelve **idempotente**. Se vuelve **desacoplado del workspace** — varias tablas de correspondencia permiten **desplegar el mismo script en varios workspaces**. Y al ser código, admite variables y bucles: el ejemplo dado es construir diez equipos de estructura idéntica cambiando solo algunos nombres.

**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 a persistir — 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 en lugar de una sola entidad.

**El producto presupone un agente.** El SDK se presenta como construido *« for you or your coding agent »*, y la vía de incorporación es 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 API imperativas: el error ahí es repetible en lugar de acumulativo.

⚠️ **Lo que falta**: ninguna mención sobre eliminar elementos retirados del script, ningún modo de previsualización 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/