Introducción

Usa la API REST de Mintlify para lanzar despliegues, integrar un asistente de IA, exportar Analytics y gestionar la documentación de forma programática.

La API REST requiere un plan Pro o Enterprise.

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.

​

Endpoints

• 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.

​

Casos de uso comunes

• 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 personalizadas: Inserta el Asistente de IA en tu producto, portal de soporte o herramientas internas con Create assistant message, 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.

​

URL base

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

https://api.mintlify.com

​

Autenticación

Puedes generar API keys en la página de API keys de tu dashboard. Cada API key pertenece a una organización; puedes usar API keys en múltiples implementaciones dentro de la misma organización.

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

​

Clave de la API de administrador

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.

​

key del Assistant API

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_.

Las llamadas que usan el token del Assistant API pueden generar costos: ya sea usando tus créditos del assistant o incurriendo en excedentes.

​

Restringir claves por dirección IP

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. Tanto las claves de la API de administrador como las del Assistant API 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.

​

Restringir claves de administrador por scope

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:

Método HTTP	Scope requerido
GET, HEAD	read
Los demás	write

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.

​

Establecer una fecha de expiración

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. Tanto las claves de la API de administrador como las del Assistant API 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.