mirror of
https://github.com/mintlify/docs.git
synced 2026-09-14 13:35:46 +08:00
mintlify[bot]
4b73a9127d
Co-authored-by: mintlify[bot] <109931778+mintlify[bot]@users.noreply.github.com>
699 lines
23 KiB
JSON
699 lines
23 KiB
JSON
{
|
||
"openapi": "3.1.0",
|
||
"info": {
|
||
"title": "Mintlify Analytics Export API",
|
||
"version": "1.0.0",
|
||
"description": "API d’exportation des données Analytics de la documentation"
|
||
},
|
||
"servers": [
|
||
{
|
||
"url": "https://api.mintlify.com",
|
||
"description": "Production"
|
||
}
|
||
],
|
||
"components": {
|
||
"securitySchemes": {
|
||
"bearerAuth": {
|
||
"type": "http",
|
||
"scheme": "bearer",
|
||
"description": "L'en-tête Authorization requiert un jeton Bearer. Utilisez une clé d'API administrateur. Il s'agit d'une clé secrète côté serveur. Générez-en une depuis la [page des clés d'API](https://dashboard.mintlify.com/settings/organization/api-keys) de votre Dashboard."
|
||
}
|
||
},
|
||
"schemas": {
|
||
"projectId": {
|
||
"type": "string",
|
||
"description": "ID de votre projet. Vous pouvez le copier depuis la page [API keys](https://dashboard.mintlify.com/settings/organization/api-keys) de votre Dashboard."
|
||
},
|
||
"FeedbackResponse": {
|
||
"type": "object",
|
||
"properties": {
|
||
"feedback": {
|
||
"type": "array",
|
||
"description": "Liste des retours.",
|
||
"items": {
|
||
"anyOf": [
|
||
{
|
||
"type": "object",
|
||
"properties": {
|
||
"id": {
|
||
"type": "string",
|
||
"description": "Identifiant unique du retour."
|
||
},
|
||
"path": {
|
||
"type": "string",
|
||
"description": "Le chemin ou l’URL du document source."
|
||
},
|
||
"comment": {
|
||
"type": [
|
||
"string",
|
||
"null"
|
||
],
|
||
"description": "Texte du commentaire de l’utilisateur."
|
||
},
|
||
"createdAt": {
|
||
"type": [
|
||
"string",
|
||
"null"
|
||
],
|
||
"description": "Horodatage de l’envoi du retour."
|
||
},
|
||
"source": {
|
||
"type": "string",
|
||
"enum": [
|
||
"code_snippet",
|
||
"contextual",
|
||
"agent",
|
||
"thumbs_only"
|
||
],
|
||
"description": "Source du retour. `code_snippet` correspond à un retour sur un bloc de code, `contextual` à un retour au niveau de la page, `agent` est un retour soumis par un agent IA tiers, `thumbs_only` est un vote pouce vers le haut/bas."
|
||
},
|
||
"status": {
|
||
"type": "string",
|
||
"enum": [
|
||
"pending",
|
||
"in_progress",
|
||
"resolved",
|
||
"dismissed"
|
||
],
|
||
"description": "Statut actuel de révision du retour."
|
||
},
|
||
"helpful": {
|
||
"type": "boolean",
|
||
"description": "Indique si l'utilisateur a jugé le contenu utile."
|
||
},
|
||
"contact": {
|
||
"type": [
|
||
"string",
|
||
"null"
|
||
],
|
||
"description": "Adresse e-mail fournie par l'utilisateur pour le suivi."
|
||
}
|
||
},
|
||
"required": [
|
||
"id",
|
||
"path",
|
||
"comment",
|
||
"createdAt",
|
||
"source",
|
||
"status",
|
||
"helpful",
|
||
"contact"
|
||
],
|
||
"description": "Renvoyé lorsque la source est `contextual`. Indique si l'utilisateur a trouvé la page utile et un e-mail de contact optionnel."
|
||
},
|
||
{
|
||
"type": "object",
|
||
"properties": {
|
||
"id": {
|
||
"type": "string",
|
||
"description": "Identifiant unique du retour."
|
||
},
|
||
"path": {
|
||
"type": "string",
|
||
"description": "Chemin ou URL du document source."
|
||
},
|
||
"comment": {
|
||
"type": [
|
||
"string",
|
||
"null"
|
||
],
|
||
"description": "Texte du commentaire de l’utilisateur."
|
||
},
|
||
"createdAt": {
|
||
"type": [
|
||
"string",
|
||
"null"
|
||
],
|
||
"description": "Horodatage de l’envoi du retour."
|
||
},
|
||
"source": {
|
||
"type": "string",
|
||
"enum": [
|
||
"code_snippet",
|
||
"contextual",
|
||
"agent",
|
||
"thumbs_only"
|
||
],
|
||
"description": "Source du retour. `code_snippet` correspond à un retour sur un bloc de code, `contextual` à un retour au niveau de la page, `agent` est un retour soumis par un agent IA tiers, `thumbs_only` est un vote pouce vers le haut/bas."
|
||
},
|
||
"status": {
|
||
"type": "string",
|
||
"enum": [
|
||
"pending",
|
||
"in_progress",
|
||
"resolved",
|
||
"dismissed"
|
||
],
|
||
"description": "Statut actuel d’examen du retour."
|
||
},
|
||
"code": {
|
||
"type": "string",
|
||
"description": "Extrait de code auquel le retour se rapporte."
|
||
},
|
||
"filename": {
|
||
"type": [
|
||
"string",
|
||
"null"
|
||
],
|
||
"description": "Nom de fichier associé à l'extrait de code."
|
||
},
|
||
"lang": {
|
||
"type": [
|
||
"string",
|
||
"null"
|
||
],
|
||
"description": "Langage de programmation de l'extrait de code."
|
||
}
|
||
},
|
||
"required": [
|
||
"id",
|
||
"path",
|
||
"comment",
|
||
"createdAt",
|
||
"source",
|
||
"status",
|
||
"code",
|
||
"filename",
|
||
"lang"
|
||
],
|
||
"description": "Renvoyé lorsque la source est `code_snippet`. Inclut le code, le nom de fichier et le langage de l'extrait auquel le retour se rapporte."
|
||
},
|
||
{
|
||
"type": "object",
|
||
"properties": {
|
||
"id": {
|
||
"type": "string",
|
||
"description": "Identifiant unique du retour."
|
||
},
|
||
"path": {
|
||
"type": "string",
|
||
"description": "Chemin ou URL du document source."
|
||
},
|
||
"comment": {
|
||
"type": [
|
||
"string",
|
||
"null"
|
||
],
|
||
"description": "Texte du commentaire de l’utilisateur."
|
||
},
|
||
"createdAt": {
|
||
"type": [
|
||
"string",
|
||
"null"
|
||
],
|
||
"description": "Horodatage de l’envoi du retour."
|
||
},
|
||
"source": {
|
||
"type": "string",
|
||
"enum": [
|
||
"code_snippet",
|
||
"contextual",
|
||
"agent",
|
||
"thumbs_only"
|
||
],
|
||
"description": "Source du retour. `code_snippet` correspond à un retour sur un bloc de code, `contextual` à un retour au niveau de la page, `agent` est un retour soumis par un agent IA tiers, `thumbs_only` est un vote pouce vers le haut/bas."
|
||
},
|
||
"status": {
|
||
"type": "string",
|
||
"enum": [
|
||
"pending",
|
||
"in_progress",
|
||
"resolved",
|
||
"dismissed"
|
||
],
|
||
"description": "Statut actuel d’examen du retour."
|
||
}
|
||
},
|
||
"required": [
|
||
"id",
|
||
"path",
|
||
"comment",
|
||
"createdAt",
|
||
"source",
|
||
"status"
|
||
],
|
||
"description": "Renvoyé lorsque la source est `agent` ou `thumbs_only`. Contient uniquement les champs de base du retour."
|
||
}
|
||
]
|
||
}
|
||
},
|
||
"nextCursor": {
|
||
"type": [
|
||
"string",
|
||
"null"
|
||
],
|
||
"description": "Curseur permettant de récupérer la page de résultats suivante. null s’il n’y a plus de résultats."
|
||
},
|
||
"hasMore": {
|
||
"type": "boolean",
|
||
"description": "Indique si des résultats supplémentaires sont disponibles au-delà de cette page."
|
||
}
|
||
},
|
||
"required": [
|
||
"feedback",
|
||
"nextCursor",
|
||
"hasMore"
|
||
]
|
||
},
|
||
"AnalyticsErrorResponse": {
|
||
"type": "object",
|
||
"properties": {
|
||
"error": {
|
||
"type": "string",
|
||
"description": "Message d’erreur décrivant ce qui s’est mal passé."
|
||
},
|
||
"details": {
|
||
"type": "array",
|
||
"description": "Détails supplémentaires sur l’erreur.",
|
||
"items": {
|
||
"type": "object",
|
||
"properties": {
|
||
"message": {
|
||
"type": "string",
|
||
"description": "Description d’une erreur spécifique de validation ou de traitement."
|
||
}
|
||
},
|
||
"required": [
|
||
"message"
|
||
]
|
||
}
|
||
}
|
||
},
|
||
"required": [
|
||
"error"
|
||
]
|
||
},
|
||
"AssistantCallerStatsResponse": {
|
||
"type": "object",
|
||
"properties": {
|
||
"web": {
|
||
"type": "number",
|
||
"description": "Nombre de requêtes de l'Assistant provenant du web (site de documentation)."
|
||
},
|
||
"api": {
|
||
"type": "number",
|
||
"description": "Nombre de requêtes de l'Assistant provenant d'appels API."
|
||
},
|
||
"other": {
|
||
"type": "number",
|
||
"description": "Nombre de requêtes de l'Assistant provenant d'autres sources (par exemple, intégrations, SDKs)."
|
||
},
|
||
"total": {
|
||
"type": "number",
|
||
"description": "Total des requêtes de l'Assistant tous types d'appelants confondus."
|
||
}
|
||
},
|
||
"required": [
|
||
"web",
|
||
"api",
|
||
"other",
|
||
"total"
|
||
]
|
||
},
|
||
"AssistantConversationsResponse": {
|
||
"type": "object",
|
||
"properties": {
|
||
"conversations": {
|
||
"type": "array",
|
||
"description": "Liste des conversations de l’Assistant.",
|
||
"items": {
|
||
"type": "object",
|
||
"properties": {
|
||
"id": {
|
||
"type": "string",
|
||
"description": "Identifiant unique de la conversation."
|
||
},
|
||
"timestamp": {
|
||
"type": "string",
|
||
"description": "Horodatage de la conversation."
|
||
},
|
||
"query": {
|
||
"type": "string",
|
||
"description": "La question de l’utilisateur adressée à l’Assistant."
|
||
},
|
||
"response": {
|
||
"type": "string",
|
||
"description": "La réponse générée par l’Assistant."
|
||
},
|
||
"sources": {
|
||
"type": "array",
|
||
"description": "Pages de documentation référencées dans la réponse.",
|
||
"items": {
|
||
"type": "object",
|
||
"properties": {
|
||
"title": {
|
||
"type": "string",
|
||
"description": "Titre de la page de documentation référencée."
|
||
},
|
||
"url": {
|
||
"type": "string",
|
||
"description": "URL de la page de documentation référencée."
|
||
}
|
||
},
|
||
"required": [
|
||
"title",
|
||
"url"
|
||
]
|
||
}
|
||
},
|
||
"queryCategory": {
|
||
"type": [
|
||
"string",
|
||
"null"
|
||
],
|
||
"description": "Catégorie de regroupement automatiquement attribuée à la conversation, le cas échéant."
|
||
},
|
||
"pageUrl": {
|
||
"type": [
|
||
"string",
|
||
"null"
|
||
],
|
||
"description": "URL complète de la page de documentation où la conversation a démarré. Null si aucun chemin de page n'a été capturé."
|
||
}
|
||
},
|
||
"required": [
|
||
"id",
|
||
"timestamp",
|
||
"query",
|
||
"response",
|
||
"sources",
|
||
"queryCategory",
|
||
"pageUrl"
|
||
]
|
||
}
|
||
},
|
||
"nextCursor": {
|
||
"type": [
|
||
"string",
|
||
"null"
|
||
],
|
||
"description": "Curseur de pagination permettant de récupérer la page de résultats suivante. Null s’il n’y a plus de résultats."
|
||
},
|
||
"hasMore": {
|
||
"type": "boolean",
|
||
"description": "Indique si des résultats supplémentaires sont disponibles au‑delà de cette page."
|
||
}
|
||
},
|
||
"required": [
|
||
"conversations",
|
||
"nextCursor",
|
||
"hasMore"
|
||
]
|
||
}
|
||
},
|
||
"parameters": {
|
||
"projectId": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/projectId"
|
||
},
|
||
"required": true,
|
||
"name": "projectId",
|
||
"in": "path"
|
||
}
|
||
}
|
||
},
|
||
"paths": {
|
||
"/v1/analytics/{projectId}/feedback": {
|
||
"get": {
|
||
"summary": "Récupérer les retours des utilisateurs",
|
||
"description": "Renvoie des retours d’utilisateurs paginés avec des filtres facultatifs\n\nAuthentifiez-vous avec une clé d'API administrateur.",
|
||
"tags": [
|
||
"Analytics"
|
||
],
|
||
"security": [
|
||
{
|
||
"bearerAuth": []
|
||
}
|
||
],
|
||
"parameters": [
|
||
{
|
||
"$ref": "#/components/parameters/projectId"
|
||
},
|
||
{
|
||
"schema": {
|
||
"type": "string",
|
||
"description": "Date au format ISO 8601 ou AAAA-MM-JJ",
|
||
"example": "2024-01-01"
|
||
},
|
||
"required": false,
|
||
"name": "dateFrom",
|
||
"in": "query"
|
||
},
|
||
{
|
||
"schema": {
|
||
"type": "string",
|
||
"description": "Date au format ISO 8601 ou AAAA-MM-JJ. `dateTo` est une borne supérieure exclusive. Les résultats incluent les dates antérieures, mais pas la date spécifiée elle-même.",
|
||
"example": "2024-01-01"
|
||
},
|
||
"required": false,
|
||
"name": "dateTo",
|
||
"in": "query"
|
||
},
|
||
{
|
||
"schema": {
|
||
"type": "string",
|
||
"enum": [
|
||
"code_snippet",
|
||
"contextual",
|
||
"agent",
|
||
"thumbs_only"
|
||
],
|
||
"description": "Filtrer par source des retours utilisateurs"
|
||
},
|
||
"required": false,
|
||
"name": "source",
|
||
"in": "query"
|
||
},
|
||
{
|
||
"schema": {
|
||
"type": "string",
|
||
"description": "Liste de statuts séparés par des virgules pour le filtrage"
|
||
},
|
||
"required": false,
|
||
"name": "status",
|
||
"in": "query"
|
||
},
|
||
{
|
||
"schema": {
|
||
"type": "number",
|
||
"minimum": 1,
|
||
"maximum": 100,
|
||
"default": 50,
|
||
"description": "Nombre maximal de résultats par page"
|
||
},
|
||
"required": false,
|
||
"name": "limit",
|
||
"in": "query"
|
||
},
|
||
{
|
||
"schema": {
|
||
"type": "string",
|
||
"description": "Curseur de pagination"
|
||
},
|
||
"required": false,
|
||
"name": "cursor",
|
||
"in": "query"
|
||
}
|
||
],
|
||
"responses": {
|
||
"200": {
|
||
"description": "Données de retours utilisateurs paginées",
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/FeedbackResponse"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"400": {
|
||
"description": "Paramètres de requête invalides",
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/AnalyticsErrorResponse"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"500": {
|
||
"description": "Erreur serveur",
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/AnalyticsErrorResponse"
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"/v1/analytics/{projectId}/assistant/caller-stats": {
|
||
"get": {
|
||
"summary": "Récupérer les statistiques d'appels de l'Assistant",
|
||
"description": "Renvoie une répartition du nombre de requêtes de l'Assistant par type d'appelant (web, API et autres) pour la plage de dates spécifiée.\n\nAuthentifiez-vous avec une clé d'API administrateur.",
|
||
"tags": [
|
||
"Analytics"
|
||
],
|
||
"security": [
|
||
{
|
||
"bearerAuth": []
|
||
}
|
||
],
|
||
"parameters": [
|
||
{
|
||
"$ref": "#/components/parameters/projectId"
|
||
},
|
||
{
|
||
"schema": {
|
||
"type": "string",
|
||
"description": "Date au format ISO 8601 ou AAAA-MM-JJ",
|
||
"example": "2024-01-01"
|
||
},
|
||
"required": false,
|
||
"name": "dateFrom",
|
||
"in": "query"
|
||
},
|
||
{
|
||
"schema": {
|
||
"type": "string",
|
||
"description": "Date au format ISO 8601 ou AAAA-MM-JJ. `dateTo` est une borne supérieure exclusive. Les résultats incluent les dates antérieures, mais pas la date spécifiée.",
|
||
"example": "2024-01-01"
|
||
},
|
||
"required": false,
|
||
"name": "dateTo",
|
||
"in": "query"
|
||
}
|
||
],
|
||
"responses": {
|
||
"200": {
|
||
"description": "Nombre de requêtes de l'Assistant ventilé par type d'appelant",
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/AssistantCallerStatsResponse"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"400": {
|
||
"description": "Paramètres de requête invalides",
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/AnalyticsErrorResponse"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"500": {
|
||
"description": "Erreur serveur",
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/AnalyticsErrorResponse"
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"/v1/analytics/{projectId}/assistant": {
|
||
"get": {
|
||
"summary": "Récupérer les conversations de l’Assistant",
|
||
"description": "Renvoie l’historique de conversation paginé de l’Assistant IA\n\nAuthentifiez-vous avec une clé d'API administrateur.",
|
||
"tags": [
|
||
"Analytics"
|
||
],
|
||
"security": [
|
||
{
|
||
"bearerAuth": []
|
||
}
|
||
],
|
||
"parameters": [
|
||
{
|
||
"$ref": "#/components/parameters/projectId"
|
||
},
|
||
{
|
||
"schema": {
|
||
"type": "string",
|
||
"description": "Date au format ISO 8601 ou AAAA-MM-JJ",
|
||
"example": "2024-01-01"
|
||
},
|
||
"required": false,
|
||
"name": "dateFrom",
|
||
"in": "query"
|
||
},
|
||
{
|
||
"schema": {
|
||
"type": "string",
|
||
"description": "Date au format ISO 8601 ou AAAA-MM-JJ. `dateTo` est une borne supérieure exclusive. Les résultats incluent les dates antérieures, mais pas la date spécifiée.",
|
||
"example": "2024-01-01"
|
||
},
|
||
"required": false,
|
||
"name": "dateTo",
|
||
"in": "query"
|
||
},
|
||
{
|
||
"schema": {
|
||
"type": "number",
|
||
"minimum": 1,
|
||
"maximum": 1000,
|
||
"default": 100,
|
||
"description": "Nombre maximal de résultats par page"
|
||
},
|
||
"required": false,
|
||
"name": "limit",
|
||
"in": "query"
|
||
},
|
||
{
|
||
"schema": {
|
||
"type": "string",
|
||
"format": "ulid",
|
||
"description": "Curseur de pagination (format ULID)"
|
||
},
|
||
"required": false,
|
||
"name": "cursor",
|
||
"in": "query"
|
||
}
|
||
],
|
||
"responses": {
|
||
"200": {
|
||
"description": "Données de conversation paginées",
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/AssistantConversationsResponse"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"400": {
|
||
"description": "Paramètres de requête invalides",
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/AnalyticsErrorResponse"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"500": {
|
||
"description": "Erreur serveur",
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/AnalyticsErrorResponse"
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"webhooks": {}
|
||
}
|