# Usar la API con una IA URL: https://docs.fluenta.io/docs/ai Dos formas de darle Fluenta a una IA: un agente con un token de API y esta documentación, o «Conectar con IA» para Claude y ChatGPT. Una IA puede usar Fluenta de dos formas. Las dos actúan como tú, con tu rol. | | Agente con un token de API | «Conectar con IA» | | ----------------------- | --------------------------------------- | ---------------------------------------- | | Para | Cualquier agente que hace llamadas HTTP | Claude y ChatGPT | | Credencial | Un token de API que tú creas | Una conexión que apruebas con «Permitir» | | Plan de la organización | Light y Pro | Pro | | Cobertura | Las 62 operaciones de la API | 38 herramientas | | Cómo se termina | «Revocar» | «Desconectar» | ## Un agente que hace llamadas HTTP [#un-agente-que-hace-llamadas-http] 1. Crea un token de API en «Configuración» → «Tokens de API». Mira [Autenticación](/docs/authentication). 2. Guárdalo en la configuración de secretos del agente, por ejemplo en una variable de entorno. No lo pegues en la conversación. 3. Apunta el agente a la documentación en texto: | Dirección | Qué trae | | ---------------------------------------- | -------------------------------------------------------------- | | `https://docs.fluenta.io/llms.txt` | El índice: una línea por página, para decidir qué leer | | `https://docs.fluenta.io/llms-full.txt` | Todas las páginas, enteras, en un solo documento | | `https://docs.fluenta.io/openapi.json` | El documento OpenAPI: rutas, parámetros, permisos y respuestas | | `https://docs.fluenta.io/docs/errors.md` | Una página en Markdown: agrega `.md` a su dirección | Los dos archivos `llms` están en español. Cada página en inglés está en `https://docs.fluenta.io/en/docs/errors.md`, con el nombre de la página en lugar de `errors`. ### Instrucciones para pegar [#instrucciones-para-pegar] Pega esto en las instrucciones de sistema del agente: ```text Tienes acceso a la API de Fluenta por HTTP. - Base: https://api.fluenta.io/v1/external - En cada solicitud envía el encabezado Authorization: Bearer $FLUENTA_TOKEN El token está en la variable de entorno FLUENTA_TOKEN. Nunca lo escribas en una respuesta ni en un registro. - Documentación: https://docs.fluenta.io/llms.txt es el índice y https://docs.fluenta.io/openapi.json tiene todas las operaciones. - Empieza con GET /me y luego GET /organizations. De ahí salen los permisos del token y el organizationId de cada organización. Todas las demás rutas llevan el organizationId en la ruta: no hay organización por defecto. - Un id sale siempre de una respuesta anterior. Nunca inventes uno. - Los días son YYYY-MM-DD en el reloj de la planta, no en UTC. El campo today de GET /organizations/{organizationId} es el hoy de la planta. - Un error es { statusCode, code, message }. Decide por code y muestra message a la persona tal como llega. No repitas una llamada rechazada sin cambiarla. - Con un 429 RATE_LIMITED espera los segundos del encabezado Retry-After antes de reintentar. - Cita las cifras como llegan. No las recalcules. - No borres nada sin pedir la vista previa y recibir un sí explícito de la persona. Un cambio rechazado no cambió nada: no digas que se hizo. ``` ## «Conectar con IA» [#conectar-con-ia] Claude y ChatGPT se conectan por MCP, sin token. La dirección es: ```text https://app.fluenta.io/mcp ``` 1. Abre «Configuración» → «Conectar con IA». Ahí están la «Dirección del conector» y los pasos para cada aplicación. 2. Pega la dirección en la aplicación: en Claude, como conector personalizado; en ChatGPT, como servidor MCP personalizado con autenticación OAuth. 3. La aplicación te trae a Fluenta. Revisa la solicitud y pulsa «Permitir». Lo que conviene saber: * **Viene con el Plan Pro.** Una prueba de Pro y una organización exenta también lo tienen. La conexión solo alcanza las organizaciones que lo tienen. * **Es OAuth.** Tú apruebas la conexión en Fluenta con tu sesión del panel y eliges sus permisos: «Leer» siempre, «Gestionar el Programa» si lo activas. * **Ofrece 38 herramientas.** 23 solo leen: tu identidad y tus organizaciones, la planta, los tableros, el Programa, el catálogo de referencias, los reportes, la «Actividad de conexiones» y las dos vistas previas de borrado. 15 cambian el Programa y el catálogo, y piden «Gestionar el Programa»; dos de ellas borran, y solo con la confirmación de su vista previa. * **Un token de API no sirve aquí.** La dirección MCP solo acepta la conexión de la propia aplicación: rechaza un token de API como una credencial inválida. * Las 23 rutas de lectura del 2026-11-12 no tienen herramienta MCP. Un agente las alcanza con un token de API y esta documentación. Mira el [registro de cambios](/docs/changelog). «Desconectar», en Configuración, termina la conexión de inmediato. ## Seguridad [#seguridad] * **Un token actúa como tú.** Alcanza todas las organizaciones a las que perteneces, con el rol que tienes en cada una, leído en cada solicitud. * **Prefiere solo «Leer».** Sin «Gestionar el Programa», toda escritura responde 403 `INSUFFICIENT_SCOPE`. Actívalo solo si el agente debe cambiar el Programa. * **Ponle «Vencimiento».** Elige 30 días, 90 días o 1 año. Un token con «Nunca» sirve hasta que lo revoques. * **Un token por agente.** Puedes tener hasta 10 tokens activos. Con uno por uso, revocas ese sin afectar a los demás. * **Revócalo al terminar.** «Revocar» lo termina de inmediato. * **Una IA puede seguir instrucciones del texto que lee.** Lo que el token puede hacer, ese texto se lo puede pedir. Es otra razón para dar solo «Leer». * Cada cambio hecho por la API queda en la «Actividad de conexiones», y `listActivity` la responde.