Introduction

Utilisez l’API REST de Mintlify pour déclencher des déploiements, intégrer un assistant IA, exporter des analyses et gérer la documentation par code.

L’API REST nécessite une offre Pro ou Enterprise.

L’API REST (Representational State Transfer) de Mintlify vous permet d’interagir programmatiquement avec votre documentation, de déclencher des mises à jour, d’intégrer des expériences de chat propulsées par l’IA et d’exporter les données d’analyse.

​

Endpoints

• Trigger update: Déclenchez une mise à jour de votre site quand vous le souhaitez.
• Get update status: Récupérez le statut d’une mise à jour et d’autres détails sur votre documentation.
• Trigger preview deployment: Créez ou mettez à jour un déploiement de prévisualisation pour une branche spécifique.
• Trigger automation: Exécute une automatisation planifiée à la demande.
• Create agent job: Créez une tâche d’agent pour modifier automatiquement votre documentation.
• Get agent job: Récupérez les détails et le statut d’une tâche d’agent spécifique.
• Send follow-up message: Envoyez un message de suivi à une tâche d’agent existante.
• Create assistant message: Intégrez l’Assistant, entraîné sur votre documentation, dans n’importe quelle application de votre choix.
• Search documentation: Effectuez une recherche dans votre documentation.
• Get page content: Récupérez le contenu textuel complet d’une page de documentation.
• Get user feedback: Exportez les retours utilisateurs issus de votre documentation.
• Get assistant conversations: Exportez l’historique des conversations de l’Assistant IA.
• Get assistant caller stats: Récupérez une ventilation du nombre de requêtes de l’assistant par type d’appelant.

​

Cas d’utilisation courants

• Déploiements automatisés : Déclenchez les mises à jour du site à intervalles réguliers ou lorsqu’un événement se produit avec Trigger update et Get update status.
• Intégration CI/CD : Mettez à jour la documentation dans le cadre de votre pipeline de déploiement lorsque le code change avec Trigger update.
• Déploiements de prévisualisation : Créez ou mettez à jour des déploiements de prévisualisation de manière programmatique dans votre pipeline CI/CD avec Trigger preview deployment.
• Automatisations à la demande : Exécutez des automatisations planifiées depuis vos propres outils, comme un pipeline CI/CD ou un script de version, avec Trigger automation.
• Intégrations personnalisées : Intégrez l’Assistant IA à votre produit, portail d’assistance ou outils internes avec Create assistant message, Search documentation et Get page content.
• Édition automatisée : Utilisez des jobs d’agent pour mettre à jour la documentation de manière programmatique et à grande échelle avec Create agent job, Get agent job, et Send follow-up message.
• Export Analytics : Exportez les retours utilisateurs, les conversations de l’Assistant et les données de visiteurs pour une analyse externe avec Get user feedback, Get assistant conversations et Get assistant caller stats.

​

URL de base

Toutes les requêtes vers l’API REST Mintlify utilisent l’URL de base suivante :

https://api.mintlify.com

​

Authentification

Générez des clés d’API depuis la page API keys de votre Dashboard. Les clés d’API sont associées à toute l’organisation et peuvent être utilisées sur plusieurs déploiements au sein de la même organisation.

Vous pouvez créer jusqu’à 10 clés d’API par heure et par organisation.

​

Clé d’API administrateur

Utilisez la clé d’API administrateur pour authentifier les requêtes vers 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 et Get assistant caller stats.

Les clés d’API administrateur commencent par le préfixe mint_.

La clé d’API administrateur est un secret côté serveur. Ne l’exposez pas dans du code côté client.

​

Clé d’API de l’Assistant

Utilisez la clé d’API de l’Assistant pour authentifier les requêtes vers les points de terminaison Create assistant message, Search documentation et Get page content.

Les clés d’API de l’Assistant commencent par le préfixe mint_dsc_.

Les appels utilisant le token de l’API de l’Assistant peuvent entraîner des coûts : soit en utilisant vos crédits d’Assistant, soit en engendrant des dépassements.

​

Restreindre les clés par adresse IP

Vous pouvez éventuellement restreindre une clé d’API à une liste d’adresses IP ou de plages CIDR autorisées. Lorsqu’une clé possède une liste d’autorisation, les requêtes provenant de toute autre adresse IP sont rejetées avec une réponse 403. Les clés d’API administrateur et les clés d’API de l’Assistant prennent en charge les listes d’autorisation.

Configurez la liste d’autorisation lors de la création de la clé sur la page API keys de votre Dashboard. La liste d’autorisation est fixée pour toute la durée de vie de la clé — pour la modifier, supprimez la clé et créez-en une nouvelle. Si vous ne définissez pas de liste d’autorisation, la clé accepte les requêtes depuis n’importe quelle adresse IP.

Les entrées de la liste prennent en charge :

• Les adresses IPv4 et IPv6, par exemple 203.0.113.5 ou 2001:db8::1.
• Les plages CIDR, par exemple 198.51.100.0/24 ou 2001:db8::/48.

Les entrées attrape-tout comme 0.0.0.0/0 et ::/0 ne sont pas autorisées.

Utilisez les listes d’IP autorisées lorsque votre clé d’API est appelée depuis un ensemble stable d’IP de sortie — par exemple un runner CI/CD, une passerelle NAT statique ou votre serveur backend. Évitez les listes d’autorisation pour les clés utilisées depuis des ordinateurs portables de développeurs ou d’autres environnements dont les IP changent.

​

Restreindre les clés administrateur par scope

Vous pouvez éventuellement restreindre une clé d’API administrateur aux scopes read ou write. Les scopes s’appliquent uniquement aux clés d’API administrateur ; les clés d’API de l’Assistant ne sont pas concernées.

Définissez les scopes lors de la création de la clé sur la page API keys de votre Dashboard. Les scopes sont fixés pour toute la durée de vie de la clé — pour les modifier, supprimez la clé et créez-en une nouvelle. Si vous ne définissez aucun scope, la clé peut appeler tous les points de terminaison administrateur (les clés existantes continuent de fonctionner).

Mintlify déduit le scope requis à partir de la méthode HTTP de la requête :

Méthode HTTP	Scope requis
GET, HEAD	read
Les autres	write

Une clé disposant de write satisfait également read, donc ["read", "write"] et ["write"] autorisent tous les points de terminaison. Les requêtes qui nécessitent un scope que la clé ne possède pas sont rejetées avec une réponse 403.

Seuls read et write sont acceptés. Toute autre valeur renvoie une réponse 400 à la création de la clé.

​

Définir une date d’expiration

Vous pouvez éventuellement définir une date d’expiration sur toute clé d’API lors de sa création. Une fois l’horodatage d’expiration dépassé, les requêtes utilisant la clé sont rejetées. Les clés d’API administrateur et les clés d’API de l’Assistant prennent en charge l’expiration.

Définissez l’expiration sur la page API keys de votre Dashboard. L’expiration est fixée pour toute la durée de vie de la clé — pour la modifier, supprimez la clé et créez-en une nouvelle. Si vous ne définissez pas d’expiration, la clé n’expire jamais.

L’expiration doit être un horodatage ISO 8601 futur. Les horodatages passés ou invalides renvoient une réponse 400 à la création de la clé. L’expiration est renvoyée sous la forme expiresAt lors de la liste des clés, ou null pour les clés sans expiration.

Utilisez les expirations pour des identifiants à courte durée de vie tels que des tokens CI/CD, des prestataires externes ou des scripts ponctuels. Faites tourner les clés de longue durée en créant une clé de remplacement, en mettant à jour vos intégrations, puis en supprimant l’ancienne.