API pública

Todo lo que un asistente de IA puede hacer en Lentil, tú puedes hacerlo desde tus propios scripts y aplicaciones mediante HTTP. Cada herramienta es un endpoint, con las mismas entradas, permisos, límites y resultados. Esta página es para desarrolladores.

Cómo funciona

La API es una tercera vía de acceso, junto a la app y el conector de asistentes de IA. Está construida sobre la misma lista de herramientas que usan los asistentes, así que cada herramienta que ves ahí es un endpoint aquí, sin añadir ni quitar nada por herramienta.

• URL base: https://app.uselentil.com/api/v1
• Las solicitudes y respuestas son JSON. Cada herramienta es POST /tools/{name} con la entrada de la herramienta como cuerpo.
• Es para servidores. No se leen cookies ni se envían cabeceras CORS, así que una página en el navegador no puede llamarla. Guarda tu clave en un servidor.
• Solo ves las herramientas que tu cuenta puede usar. Una herramienta que no puedas usar responde exactamente como una que no existe.

Crear una clave de API

1. Abre Perfil desde el menú con tu nombre al final de la barra lateral, luego la pestaña Seguridad. Una vez conectado, también puedes ir directo a la tarjeta de claves de API.
2. En la tarjeta Claves de API, pulsa Crear clave.
3. En Nombre, indica para qué es la clave, por ejemplo Sincronización de inventario, y pulsa Crear clave.
4. El cuadro Tu nueva clave de API muestra la clave una sola vez. Pulsa el botón de copiar y guárdala en un lugar seguro, como un gestor de contraseñas. No volverás a verla.

La tarjeta lista cada clave con su nombre, una pista breve (el inicio de la clave, nunca el secreto), cuándo se creó y cuándo se usó por última vez. Pulsa Revocar y confirma en Revocar clave de API para detener una clave de inmediato: cualquier cosa que la use recibirá un 401 hasta que le des una clave nueva.

• Una clave actúa como tú, con tus roles en cada espacio de trabajo, igual que un asistente conectado, hasta que la revoques.
• Puedes tener 20 claves activas. Revoca una para hacer espacio.
• El nombre de una clave tiene entre 1 y 60 caracteres.
• Crear y revocar una clave aparece en Actividad de seguridad reciente.
• Cerrar sesión en todos los demás lugares no afecta a las claves de API: revócalas en la tarjeta.

Create an API key called Inventory sync, and remind me to store it safely because it is only shown once.

Autenticarse

Envía la clave en la cabecera Authorization en cada solicitud.

Authorization: Bearer $LENTIL_API_KEY

Un token de acceso OAuth del flujo del conector de asistentes funciona en la misma cabecera. Ve las mismas herramientas que ve un asistente, y expira al cabo de una hora como cualquier token de conector. La mayoría de los scripts deberían usar una clave en su lugar.

Las credenciales se verifican en cada solicitud, junto con la cuenta misma: una clave revocada, un token expirado o una cuenta deshabilitada dan un 401 de inmediato.

Listar las herramientas

GET/tools devuelve cada herramienta que puedes usar, con su nombre, título, descripción y esquemas JSON para su entrada y resultado.

curl https://app.uselentil.com/api/v1/tools \
  -H "Authorization: Bearer $LENTIL_API_KEY"

GET/openapi.json describe las mismas herramientas como un documento OpenAPI 3.1, para generar un cliente o cargarlo en una herramienta de API. Lista solo las herramientas que tu cuenta puede usar.

curl https://app.uselentil.com/api/v1/openapi.json \
  -H "Authorization: Bearer $LENTIL_API_KEY" -o lentil-openapi.json

Para echar un vistazo antes de registrarte, el mismo documento con todas las herramientas que cualquier cuenta puede usar es público, sin clave: uselentil.com/docs/api/openapi.json. La referencia de herramientas al final de esta página está construida a partir de él.

Llamar a una herramienta

POST/tools/{name} con la entrada de la herramienta como un objeto JSON. Envía un cuerpo vacío, o {}, para una herramienta sin entrada.

curl https://app.uselentil.com/api/v1/tools/list_sites \
  -H "Authorization: Bearer $LENTIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

El éxito es HTTP 200 con el resultado:

{ "result": { "sites": [ { "id": "...", "name": "Rosa's Bakery" } ] } }

Un resultado con imágenes u otro contenido enriquecido también tiene un array content con los mismos bloques de contenido que recibe un asistente. Los ids como siteId y pageId provienen de llamadas anteriores: list_workspaces, list_sites y list_pages.

Leer, editar y luego publicar

Las ediciones de página siguen el mismo orden seguro que en la app. Lee la página, envía tu cambio con la versión que leíste, y la edición se guarda como borrador. Nada se publica hasta que lo hagas tú.

curl https://app.uselentil.com/api/v1/tools/get_page \
  -H "Authorization: Bearer $LENTIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"siteId": "SITE_ID", "pageId": "PAGE_ID"}'

El resultado tiene el currentVersionId de la página. Pásalo como baseVersionId a edit_page. Si alguien cambió la página mientras tanto, la llamada falla con 409 version_conflict y la versión actual: vuelve a leer e inténtalo de nuevo. Las versiones creadas así se etiquetan como "(via API)" en el historial de versiones del editor.

Confirmaciones

Las herramientas que publican, eliminan, gastan o cambian un plan requieren confirmed: true, y debes enviarlo solo después de que una persona haya dado su conformidad. publish_page lo exige: sin él, la llamada falla con un 400 y nada se publica. Las herramientas que pueden mostrar una vista previa, como eliminar una página o cambiar un plan, responden con una vista previa cuando lo omites.

curl https://app.uselentil.com/api/v1/tools/publish_page \
  -H "Authorization: Bearer $LENTIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"siteId": "SITE_ID", "pageId": "PAGE_ID", "confirmed": true}'

I want to write a script that updates my opening hours on Lentil every morning from a spreadsheet. Which tools should it call, in what order, and what inputs do they need?

La referencia dentro de la app

La lista completa de herramientas, con cada campo de entrada, su tipo y si es obligatorio, está en la app en /settings/api (app.uselentil.com/settings/api). También puedes acceder con Ver referencia de la API en la tarjeta Claves de API. Se genera a partir del mismo documento OpenAPI y muestra solo las herramientas que tu cuenta puede usar, mientras que la referencia de herramientas de esta página enumera todas las herramientas que cualquier cuenta puede usar. Ambas tienen un cuadro de búsqueda.

Errores

Un fallo es un estado de error HTTP y un cuerpo JSON. El mensaje es el mismo texto que leería un asistente, e indica qué hacer a continuación.

{ "error": { "code": "version_conflict", "message": "...", "details": { "currentVersionId": "..." } } }

El estado indica el tipo de fallo, y code indica exactamente cuál. details está presente cuando el error tiene datos estructurados.

Las herramientas añaden sus propios códigos, por ejemplo site_not_found o payment_failed. Actúa según el código, no según el texto del mensaje.

Límites de uso

Cada clave, y cada conexión OAuth, puede hacer 120 solicitudes por minuto. Pasado eso, la API responde 429 rate_limited con un encabezado retry-after de 60 segundos. Los créditos de IA y los límites del plan se aplican exactamente igual que en la app.

Quién puede usarla

• Cualquiera con una cuenta de Lentil puede crear claves en su perfil. Es una clave personal: puede hacer lo que tú puedes hacer, nada más.
• Tu rol en cada espacio de trabajo decide qué herramientas funcionan y a qué sitios llegan. La clave de un cliente solo ve los sitios compartidos con ese cliente.

Límites y casos particulares

• 20 claves activas por persona, de 1 a 60 caracteres por nombre, se muestra una sola vez.
• La lista de claves muestra Último uso actualizado como máximo cada 10 minutos, así que puede retrasarse.
• La lista de herramientas que ves puede cambiar según cambien tus roles o el acceso a funciones. Vuelve a leer /tools en lugar de guardarlo en caché por mucho tiempo.
• Los nombres de las herramientas y sus entradas aún pueden cambiar mientras la API esté en beta. El documento OpenAPI es el contrato para tu cuenta hoy.
• Las claves no funcionan desde un navegador: no hay CORS ni inicio de sesión con cookies.
• Una clave revocada no puede reactivarse. Crea una nueva.

Desde un asistente de IA

Un asistente puede gestionar tus claves como tú, pero la clave en sí es un secreto.

• list_api_keys: tus claves activas con sus pistas y hora de último uso, nunca el secreto.
• create_api_key con un name: devuelve la clave una sola vez. El asistente debe entregártela de inmediato y decirte que la guardes de forma segura.
• revoke_api_key con keyId: sin confirmed: true solo muestra una vista previa de qué clave dejaría de funcionar. El asistente pasa confirmed: true después de que estés de acuerdo.

Referencia de herramientas

Todas las herramientas que cualquier cuenta de Lentil puede usar, agrupadas por área, con sus campos de entrada. Se genera a partir de la propia API, así que una herramienta nueva aparece aquí en cuanto está disponible para todos. Tu rol en cada espacio de trabajo decide cuáles de ellas puede llamar tu clave.

Descárgala como un archivo OpenAPI 3.1 para Postman, Insomnia o un generador de cliente: openapi.json.

Actualizado el 9 de noviembre de 2026