Introducción a la API REST de Mintlify

La REST (Representational State Transfer) API de Mintlify te permite interactuar de forma programática con tu documentación, lanzar actualizaciones, integrar experiencias de chat impulsadas por IA y exportar datos de Analytics.

• Trigger update: Activa una actualización de tu sitio cuando quieras.
• Get update status: Obtén el estado de una actualización y otros detalles de tu documentación.
• Trigger preview deployment: Crea o actualiza una implementación de vista previa para una rama específica.
• Trigger automation: Ejecuta una automatización programada bajo demanda.
• Create agent job: Crea una tarea de agente para editar tu documentación automáticamente.
• Get agent job: Obtén los detalles y el estado de una tarea de agente específica.
• Send follow-up message: Envía un mensaje de seguimiento a una tarea de agente existente.
• Create assistant message: Integra el assistant, entrenado con tu documentación, en cualquier aplicación que elijas.
• Search documentation: Busca en tu documentación.
• Get page content: Recupera el contenido de texto completo de una página de documentación.
• Get user feedback: Exporta los comentarios de los usuarios de tu documentación.
• Get assistant conversations: Exporta el historial de conversaciones del Asistente de IA.
• Get assistant caller stats: Obtén un desglose de los recuentos de consultas del assistant por tipo de origen.

• Implementaciones automatizadas: Activa actualizaciones del sitio a intervalos establecidos o cuando se produzcan eventos con Trigger update y Get update status.
• Integración CI/CD: Actualiza la documentación como parte de tu pipeline de implementación cuando el código cambie con Trigger update.
• Implementaciones de vista previa: Crea o actualiza implementaciones de vista previa de forma programática en tu pipeline CI/CD con Trigger preview deployment.
• Automatizaciones bajo demanda: Activa automatizaciones programadas desde tu pipeline CI/CD, scripts de versión u otras herramientas con Trigger automation.
• Integraciones del asistente: Inserta el asistente de IA en tu producto, portal de soporte o herramientas internas con Create assistant message.
• Recuperación de documentación: Busca y recupera documentación para experiencias de búsqueda personalizadas con Search documentation y Get page content.
• Edición automatizada: Usa trabajos de agente para actualizar la documentación programáticamente y a escala con Create agent job, Get agent job y Send follow-up message.
• Exportación de Analytics: Exporta comentarios, conversaciones del assistant y datos de visitantes para análisis externo con Get user feedback, Get assistant conversations y Get assistant caller stats.

Todas las solicitudes a la API REST de Mintlify usan la siguiente URL base:

https://api.mintlify.com

Puedes generar API keys en la página de API keys de tu dashboard. Las claves de API de administrador e Index pertenecen a una organización. Puedes usar las mismas claves en múltiples implementaciones dentro de la misma organización. Las claves de API del Assistant pertenecen al despliegue donde las creas.

Puedes crear hasta 10 API keys por hora y por organización.

Al crear una API key, puedes configurarla para que caduque en 7, 30, 60 o 90 días, o seleccionar Sin caducidad. Las nuevas API keys caducan en 90 días de forma predeterminada. La página de API keys muestra una insignia Caduca en … para las API keys que caducan en los próximos 7 días y una insignia Caducada para las que ya han caducado. Las API keys caducadas dejan de funcionar, por lo que debes rotarlas o reemplazarlas antes de la fecha de caducidad.

Mintlify utiliza tres tipos de API keys, cada una con un conjunto diferente de endpoints:

Usa la clave de la API de administrador para autenticar solicitudes a Trigger update, Get update status, Trigger preview deployment, Trigger automation, Create agent job, Get agent job, Send follow-up message, Get user feedback, Get assistant conversations y Get assistant caller stats.

Las claves de la API de administrador comienzan con el prefijo mint_.

La clave de la API de administrador es un secreto del lado del servidor. No la expongas en código del lado del cliente.

Usa la key del Assistant API para autenticar solicitudes a los endpoints Create assistant message, Search documentation y Get page content.

Las keys del Assistant API comienzan con el prefijo mint_dsc_.

Usa una clave de la API de Index para autenticar solicitudes a la API REST de Mintlify Index. Las claves de la API de Index comienzan con el prefijo mint_us_.

La clave de la API de Index es un secreto del lado del servidor. No la expongas en código del lado del cliente.

Puedes restringir opcionalmente una API key a una lista de direcciones IP o rangos CIDR permitidos. Cuando una key tiene una lista de permitidos, las solicitudes desde cualquier otra dirección IP se rechazan con una respuesta 403. Las claves de las API de administrador, Assistant e Index admiten listas de permitidos.

Configura la lista de permitidos al crear la key en la página de API keys de tu dashboard. La lista de permitidos es fija durante la vida de la key; para cambiarla, elimina la key y crea una nueva. Si no configuras una lista de permitidos, la key acepta solicitudes desde cualquier dirección IP.

Las entradas admiten:

• Direcciones IPv4 e IPv6, por ejemplo 203.0.113.5 o 2001:db8::1.
• Rangos CIDR, por ejemplo 198.51.100.0/24 o 2001:db8::/48.

No se permiten entradas comodín como 0.0.0.0/0 o ::/0.

Usa listas de IP permitidas cuando tu API key se llame desde un conjunto estable de IPs de salida, por ejemplo, un runner de CI/CD, una NAT estática o el servidor de tu backend. Evita las listas de permitidos para keys usadas desde portátiles de personas desarrolladoras u otros entornos con IPs cambiantes.

Puedes restringir opcionalmente una clave de la API de administrador a los scopes read o write. Los scopes se aplican solo a las claves de la API de administrador; las keys del Assistant API no se ven afectadas.

Configura los scopes al crear la key en la página de API keys de tu dashboard. Los scopes son fijos durante la vida de la key; para cambiarlos, elimina la key y crea una nueva. Si no configuras scopes, la key puede llamar a todos los endpoints de administrador (las keys existentes siguen funcionando).

Mintlify deriva el scope requerido a partir del método HTTP de la solicitud:

Una key con write también satisface read, por lo que ["read", "write"] y ["write"] permiten todos los endpoints. Las solicitudes que requieren un scope que la key no tiene se rechazan con una respuesta 403.

Solo se aceptan read y write. Cualquier otro valor devuelve una respuesta 400 al crear la key.

Puedes establecer opcionalmente una fecha de expiración en cualquier API key al crearla. Cuando pasa la marca de tiempo de expiración, las solicitudes que usan la key se rechazan con una respuesta 401. Todas las API keys admiten expiración.

Configura la expiración en la página de API keys de tu dashboard. La expiración es fija durante la vida de la key; para cambiarla, elimina la key y crea una nueva. Si no configuras una expiración, la key nunca expira.

La expiración debe ser una marca de tiempo ISO 8601 en el futuro. Las marcas de tiempo pasadas o inválidas devuelven una respuesta 400 al crear la key. La expiración se devuelve como expiresAt al listar las keys, o null para las keys sin expiración.

Usa expiraciones para credenciales de corta duración, como tokens de CI/CD, colaboradores externos o scripts puntuales. Rota las keys de larga duración creando una de reemplazo, actualizando tus integraciones y eliminando la anterior.