Notion
Páginas, bases de datos y bloques de Notion desde su API oficial.
Ver la documentaciónPara qué sirve
Qué problema resuelve
La API de Notion conecta el contenido de tu workspace (páginas, bases de datos, bloques, comentarios) con otras apps.
Sirve para publicar automáticamente, sincronizar un CMS ligero o dejar que un agente lea/escriba páginas que tú hayas compartido con la integración.
En la práctica
Qué puedes hacer con ella
- Leer el contenido de una página compartida con tu integración.
- Consultar o actualizar filas de una base de datos de Notion.
- Crear páginas nuevas bajo un padre autorizado.
- Buscar en el workspace según los permisos de la integración.
- Encadenar un bot o un script que mantenga docs al día.
¿Es gratis?
Usable en workspaces Free (con rate limits)
La API funciona en workspaces Free. Notion limita de media unas 3 peticiones por segundo por conexión (integration), con ráfagas puntuales, y además hay un techo por workspace según el plan. Si te pasas, responde 429 con Retry-After.
Comprobado el 2026-08-02. Fuente: página oficial de precios o límites
Qué cuenta como una «llamada» aquí
Cada request HTTP a api.notion.com (leer página, consultar base, crear bloque…) cuenta 1. No hay «tokens de IA» en este contador: es ritmo por segundo y por workspace.
Además, los objetos grandes tienen límites de tamaño documentados. Comparte explícitamente cada página/base con la integración; si no, la API no la verá.
Límites de la Notion API
| Límite | Cuota | Qué significa en la práctica |
|---|---|---|
| Por conexión (integration) | Media de 3 req/s | Se permiten ráfagas cortas; si te pasas, 429 + Retry-After. |
| Por workspace | Escala con el plan | Compartido entre todas las conexiones del workspace. Motivo en additional_data.rate_limit_reason. |
| Tamaño de payloads | Límites documentados | Hay techos de tamaño en parámetros y valores de propiedades. |
Planes Notion (API en todos los habituales)
| Plan | Precio | Para quién | Qué incluye (resumen) |
|---|---|---|---|
| Free | $0 | Personas y equipos pequeños. | API usable; rate limits de plataforma. |
| Plus / Business / Enterprise | Ver precios oficiales | Equipos con más asientos y controles. | Más capacidad de producto; la API sigue en developers.notion.com. |
Uso permitido, comercial y licencia
| Pregunta | Respuesta clara |
|---|---|
| ¿Open source? | No. Notion es un servicio comercial. |
| ¿Uso comercial? | Sí según el plan contratado y los términos. La API no es un marketplace de datos ajenos: solo tu workspace autorizado. |
| ¿Hace falta cuenta? | Sí: integración interna en https://www.notion.so/my-integrations y compartir páginas/bases con ella. |
Cómo empezar
Leer una página compartida con una integración interna.
Necesitas workspace, una integración y haber compartido la página con ella.
Dirección base de las imágenes: https://api.notion.com/v1
- 01
Paso 1
Crea una integración en https://www.notion.so/my-integrations y copia el secret.
- 02
Paso 2
En Notion, abre la página → Connect to / compartir con esa integración.
- 03
Paso 3
Haz GET https://api.notion.com/v1/pages/{page_id} con Authorization: Bearer SECRET y la cabecera Notion-Version documentada.
- 04
Paso 4
Para el contenido en bloques, usa el endpoint de children de esa página.
- 05
Paso 5
Respeta la media de 3 req/s y el Retry-After si llega 429: https://developers.notion.com/reference/request-limits
Con tu agente
Prompt para integrar la API
Prompt para que tu agente lo deje listo
Pega esto en Cursor, Claude Code, Codex u otro agente de código:
Integra la Notion API. Docs: https://developers.notion.com/reference/intro . Límites: https://developers.notion.com/reference/request-limits . Base: https://api.notion.com/v1 . No inventes integration secret ni page_id: pídemelos. Recuerda compartir la página con la integración y enviar Notion-Version. ¿Leemos una página, una database o creamos contenido?Detalle técnico
Acceso, HTTPS y CORS
- 01
Acceso · OAuth
Requiere flujo OAuth: el usuario autoriza tu aplicación antes de leer sus datos.
- 02
HTTPS · Sí
Sirve sobre TLS, así que vale para producción y para páginas ya en HTTPS.
- 03
CORS · Sin verificar
No consta si permite llamadas desde el navegador; pruébalo antes de montar el cliente.