From 2b6513eebcfffea8ddbdfd630e9d009c4e79fd7a Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Tue, 24 Mar 2026 23:33:59 +0000 Subject: [PATCH] Add feedback by page API endpoint documentation Generated-By: mintlify-agent --- analytics.openapi.json | 154 ++++++++++++++++++++++++++ api/analytics/feedback-by-page.mdx | 28 +++++ api/introduction.mdx | 5 +- docs.json | 4 + es/analytics.openapi.json | 154 ++++++++++++++++++++++++++ es/api/analytics/feedback-by-page.mdx | 37 +++++++ es/api/introduction.mdx | 5 +- fr/analytics.openapi.json | 154 ++++++++++++++++++++++++++ fr/api/analytics/feedback-by-page.mdx | 36 ++++++ fr/api/introduction.mdx | 5 +- zh/analytics.openapi.json | 154 ++++++++++++++++++++++++++ zh/api/analytics/feedback-by-page.mdx | 35 ++++++ zh/api/introduction.mdx | 5 +- 13 files changed, 768 insertions(+), 8 deletions(-) create mode 100644 api/analytics/feedback-by-page.mdx create mode 100644 es/api/analytics/feedback-by-page.mdx create mode 100644 fr/api/analytics/feedback-by-page.mdx create mode 100644 zh/api/analytics/feedback-by-page.mdx diff --git a/analytics.openapi.json b/analytics.openapi.json index e7b80c1b6..e76b9e0c4 100644 --- a/analytics.openapi.json +++ b/analytics.openapi.json @@ -246,6 +246,55 @@ "hasMore" ] }, + "FeedbackGroupedByPageResponse": { + "type": "object", + "properties": { + "feedback": { + "type": "array", + "description": "List of per-page feedback aggregates.", + "items": { + "type": "object", + "properties": { + "path": { + "type": "string", + "description": "The documentation page path." + }, + "thumbsUp": { + "type": "number", + "description": "Number of positive (thumbs up) ratings for the page." + }, + "thumbsDown": { + "type": "number", + "description": "Number of negative (thumbs down) ratings for the page." + }, + "code": { + "type": "number", + "description": "Number of code snippet feedback entries for the page." + }, + "total": { + "type": "number", + "description": "Total number of feedback entries for the page." + } + }, + "required": [ + "path", + "thumbsUp", + "thumbsDown", + "code", + "total" + ] + } + }, + "hasMore": { + "type": "boolean", + "description": "Whether additional results are available beyond this page." + } + }, + "required": [ + "feedback", + "hasMore" + ] + }, "AnalyticsErrorResponse": { "type": "object", "properties": { @@ -483,6 +532,111 @@ } } }, + "/v1/analytics/{projectId}/feedback/by-page": { + "get": { + "summary": "Get feedback grouped by page", + "description": "Returns feedback counts aggregated by documentation page path, including thumbs up/down for contextual feedback, code snippet count, and total per page", + "tags": [ + "Analytics" + ], + "security": [ + { + "bearerAuth": [] + } + ], + "parameters": [ + { + "$ref": "#/components/parameters/projectId" + }, + { + "schema": { + "type": "string", + "description": "Date in ISO 8601 or YYYY-MM-DD format", + "example": "2024-01-01" + }, + "required": false, + "name": "dateFrom", + "in": "query" + }, + { + "schema": { + "type": "string", + "description": "Date in ISO 8601 or YYYY-MM-DD format. `dateTo` is an exclusive upper limit. Results include dates before, but not on, the specified date.", + "example": "2024-01-01" + }, + "required": false, + "name": "dateTo", + "in": "query" + }, + { + "schema": { + "type": "string", + "enum": [ + "code_snippet", + "contextual" + ], + "description": "Filter by feedback source" + }, + "required": false, + "name": "source", + "in": "query" + }, + { + "schema": { + "type": "string", + "description": "Comma-separated list of statuses to filter by" + }, + "required": false, + "name": "status", + "in": "query" + }, + { + "schema": { + "type": "number", + "minimum": 1, + "maximum": 100, + "default": 10, + "description": "Max results per page" + }, + "required": false, + "name": "limit", + "in": "query" + } + ], + "responses": { + "200": { + "description": "Per-page feedback aggregates with pagination flag", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/FeedbackGroupedByPageResponse" + } + } + } + }, + "400": { + "description": "Invalid query parameters", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AnalyticsErrorResponse" + } + } + } + }, + "500": { + "description": "Server error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AnalyticsErrorResponse" + } + } + } + } + } + } + }, "/v1/analytics/{projectId}/assistant": { "get": { "summary": "Get assistant conversations", diff --git a/api/analytics/feedback-by-page.mdx b/api/analytics/feedback-by-page.mdx new file mode 100644 index 000000000..9976ca658 --- /dev/null +++ b/api/analytics/feedback-by-page.mdx @@ -0,0 +1,28 @@ +--- +title: "Get feedback by page" +description: "Retrieve feedback counts aggregated by documentation page, including thumbs up/down ratings and code snippet feedback." +openapi: /analytics.openapi.json GET /v1/analytics/{projectId}/feedback/by-page +keywords: ["analytics", "feedback", "export", "aggregated feedback", "by page"] +--- + +## Usage + +Use this endpoint to get an overview of feedback volume across your documentation pages. Results are aggregated per page path and sorted by total feedback count in descending order. + +Check the `hasMore` field in the response to determine if additional pages of results are available. Increase the `limit` parameter to retrieve more results per request. + +## Filtering + +Filter feedback aggregates by: +- **Date range**: Use `dateFrom` and `dateTo` to limit results to a specific time period +- **Source**: Filter by `code_snippet` or `contextual` feedback types +- **Status**: Filter by status values like `pending`, `in_progress`, `resolved`, or `dismissed` + +## Response fields + +Each item in the response represents a documentation page and includes: + +- **thumbsUp**: Number of positive (helpful) contextual ratings +- **thumbsDown**: Number of negative (not helpful) contextual ratings +- **code**: Number of code snippet feedback entries +- **total**: Combined count of all feedback types for the page diff --git a/api/introduction.mdx b/api/introduction.mdx index d5b28d6d2..17bb8444d 100644 --- a/api/introduction.mdx +++ b/api/introduction.mdx @@ -16,6 +16,7 @@ The Mintlify REST (Representational State Transfer) API enables you to programma - [Create assistant message](/api/assistant/create-assistant-message-v2): Embed the assistant, trained on your docs, into any application of your choosing. - [Search documentation](/api/assistant/search): Search through your documentation. - [Get user feedback](/api/analytics/feedback): Export user feedback from your documentation. +- [Get feedback by page](/api/analytics/feedback-by-page): Export feedback counts aggregated by documentation page. - [Get assistant conversations](/api/analytics/assistant-conversations): Export AI assistant conversation history. ### Common use cases @@ -24,7 +25,7 @@ The Mintlify REST (Representational State Transfer) API enables you to programma - **CI/CD integration**: Update documentation as part of your deployment pipeline when code changes with [Trigger update](/api/update/trigger). - **Custom integrations**: Embed the AI assistant into your product, support portal, or internal tools with [Create assistant message](/api/assistant/create-assistant-message-v2) and [Search documentation](/api/assistant/search). - **Automated editing**: Use agent jobs to programmatically update documentation at scale with [Create agent job](/api/agent/v2/create-agent-job), [Get agent job](/api/agent/v2/get-agent-job), and [Send follow-up message](/api/agent/v2/send-message). -- **Analytics export**: Export feedback and assistant conversations for external analysis with [Get user feedback](/api/analytics/feedback) and [Get assistant conversations](/api/analytics/assistant-conversations). +- **Analytics export**: Export feedback and assistant conversations for external analysis with [Get user feedback](/api/analytics/feedback), [Get feedback by page](/api/analytics/feedback-by-page), and [Get assistant conversations](/api/analytics/assistant-conversations). ## Authentication @@ -34,7 +35,7 @@ You can create up to 10 API keys per hour per organization. ### Admin API key -Use the admin API key to authenticate requests to [Trigger update](/api/update/trigger), [Get update status](/api/update/status), [Create agent job](/api/agent/v2/create-agent-job), [Get agent job](/api/agent/v2/get-agent-job), [Send follow-up message](/api/agent/v2/send-message), [Get user feedback](/api/analytics/feedback), and [Get assistant conversations](/api/analytics/assistant-conversations). +Use the admin API key to authenticate requests to [Trigger update](/api/update/trigger), [Get update status](/api/update/status), [Create agent job](/api/agent/v2/create-agent-job), [Get agent job](/api/agent/v2/get-agent-job), [Send follow-up message](/api/agent/v2/send-message), [Get user feedback](/api/analytics/feedback), [Get feedback by page](/api/analytics/feedback-by-page), and [Get assistant conversations](/api/analytics/assistant-conversations). Admin API keys begin with the `mint_` prefix. diff --git a/docs.json b/docs.json index 53867420a..817bfdc8e 100644 --- a/docs.json +++ b/docs.json @@ -371,6 +371,7 @@ "icon": "chart-line", "pages": [ "api/analytics/feedback", + "api/analytics/feedback-by-page", "api/analytics/assistant-conversations" ] } @@ -741,6 +742,7 @@ "icon": "chart-line", "pages": [ "fr/api/analytics/feedback", + "fr/api/analytics/feedback-by-page", "fr/api/analytics/assistant-conversations" ] } @@ -1111,6 +1113,7 @@ "icon": "chart-line", "pages": [ "es/api/analytics/feedback", + "es/api/analytics/feedback-by-page", "es/api/analytics/assistant-conversations" ] } @@ -1481,6 +1484,7 @@ "icon": "chart-line", "pages": [ "zh/api/analytics/feedback", + "zh/api/analytics/feedback-by-page", "zh/api/analytics/assistant-conversations" ] } diff --git a/es/analytics.openapi.json b/es/analytics.openapi.json index 636f47515..3ce15d68a 100644 --- a/es/analytics.openapi.json +++ b/es/analytics.openapi.json @@ -246,6 +246,55 @@ "hasMore" ] }, + "FeedbackGroupedByPageResponse": { + "type": "object", + "properties": { + "feedback": { + "type": "array", + "description": "Lista de agregados de comentarios por página.", + "items": { + "type": "object", + "properties": { + "path": { + "type": "string", + "description": "La ruta de la página de documentación." + }, + "thumbsUp": { + "type": "number", + "description": "Número de valoraciones positivas (pulgar arriba) para la página." + }, + "thumbsDown": { + "type": "number", + "description": "Número de valoraciones negativas (pulgar abajo) para la página." + }, + "code": { + "type": "number", + "description": "Número de comentarios sobre fragmentos de código para la página." + }, + "total": { + "type": "number", + "description": "Número total de comentarios para la página." + } + }, + "required": [ + "path", + "thumbsUp", + "thumbsDown", + "code", + "total" + ] + } + }, + "hasMore": { + "type": "boolean", + "description": "Indica si hay más resultados disponibles más allá de esta página." + } + }, + "required": [ + "feedback", + "hasMore" + ] + }, "AnalyticsErrorResponse": { "type": "object", "properties": { @@ -483,6 +532,111 @@ } } }, + "/v1/analytics/{projectId}/feedback/by-page": { + "get": { + "summary": "Obtener comentarios agrupados por página", + "description": "Devuelve los recuentos de comentarios agregados por ruta de página de documentación (pulgares arriba/abajo para comentarios contextuales, recuento de fragmentos de código y total por página)", + "tags": [ + "Analytics" + ], + "security": [ + { + "bearerAuth": [] + } + ], + "parameters": [ + { + "$ref": "#/components/parameters/projectId" + }, + { + "schema": { + "type": "string", + "description": "Fecha en formato ISO 8601 o AAAA-MM-DD", + "example": "2024-01-01" + }, + "required": false, + "name": "dateFrom", + "in": "query" + }, + { + "schema": { + "type": "string", + "description": "Fecha en formato ISO 8601 o AAAA-MM-DD. `dateTo` es un límite superior exclusivo. Los resultados incluyen fechas anteriores, pero no la fecha especificada.", + "example": "2024-01-01" + }, + "required": false, + "name": "dateTo", + "in": "query" + }, + { + "schema": { + "type": "string", + "enum": [ + "code_snippet", + "contextual" + ], + "description": "Filtrar por fuente de comentarios" + }, + "required": false, + "name": "source", + "in": "query" + }, + { + "schema": { + "type": "string", + "description": "Lista de estados separados por comas para filtrar" + }, + "required": false, + "name": "status", + "in": "query" + }, + { + "schema": { + "type": "number", + "minimum": 1, + "maximum": 100, + "default": 10, + "description": "Número máximo de resultados por página" + }, + "required": false, + "name": "limit", + "in": "query" + } + ], + "responses": { + "200": { + "description": "Agregados de comentarios por página con indicador de paginación", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/FeedbackGroupedByPageResponse" + } + } + } + }, + "400": { + "description": "Parámetros de consulta inválidos", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AnalyticsErrorResponse" + } + } + } + }, + "500": { + "description": "Error del servidor", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AnalyticsErrorResponse" + } + } + } + } + } + } + }, "/v1/analytics/{projectId}/assistant": { "get": { "summary": "Obtener conversaciones del assistant", diff --git a/es/api/analytics/feedback-by-page.mdx b/es/api/analytics/feedback-by-page.mdx new file mode 100644 index 000000000..54cf219aa --- /dev/null +++ b/es/api/analytics/feedback-by-page.mdx @@ -0,0 +1,37 @@ +--- +title: "Obtener comentarios por página" +description: "Obtén los recuentos de comentarios agregados por página de documentación, + incluidas las valoraciones de pulgares arriba/abajo y los comentarios sobre fragmentos + de código." +openapi: /es/analytics.openapi.json GET /v1/analytics/{projectId}/feedback/by-page +keywords: ["Analytics", "feedback", "exportación", "comentarios agregados", "por página"] +--- + +
+ ## Uso +
+ +Usa este endpoint para obtener una visión general del volumen de comentarios en las páginas de tu documentación. Los resultados se agregan por ruta de página y se ordenan por recuento total de comentarios en orden descendente. + +Verifica el campo `hasMore` en la respuesta para determinar si hay más páginas de resultados disponibles. Aumenta el parámetro `limit` para obtener más resultados por solicitud. + +
+ ## Filtrado +
+ +Filtra los agregados de comentarios por: + +- **Rango de fechas**: Utiliza `dateFrom` y `dateTo` para limitar los resultados a un período de tiempo específico +- **Fuente**: Filtra por tipos de feedback `code_snippet` o `contextual` +- **Estado**: Filtra por valores de estado como `pending`, `in_progress`, `resolved` o `dismissed` + +
+ ## Campos de la respuesta +
+ +Cada elemento de la respuesta representa una página de documentación e incluye: + +- **thumbsUp**: Número de valoraciones contextuales positivas (útil) +- **thumbsDown**: Número de valoraciones contextuales negativas (no útil) +- **code**: Número de comentarios sobre fragmentos de código +- **total**: Recuento combinado de todos los tipos de comentarios para la página diff --git a/es/api/introduction.mdx b/es/api/introduction.mdx index 08c5d5acc..cec66c7ba 100644 --- a/es/api/introduction.mdx +++ b/es/api/introduction.mdx @@ -18,6 +18,7 @@ La REST (Representational State Transfer) API de Mintlify te permite interactuar * [Create assistant message](/es/api/assistant/create-assistant-message-v2): Integra el assistant, entrenado con tu documentación, en cualquier aplicación que elijas. * [Search documentation](/es/api/assistant/search): Busca en tu documentación. * [Get user feedback](/es/api/analytics/feedback): Exporta los comentarios de los usuarios de tu documentación. +* [Get feedback by page](/es/api/analytics/feedback-by-page): Exporta los recuentos de comentarios agregados por página de documentación. * [Get assistant conversations](/es/api/analytics/assistant-conversations): Exporta el historial de conversaciones del Asistente de IA.
@@ -28,7 +29,7 @@ La REST (Representational State Transfer) API de Mintlify te permite interactuar * **Integración CI/CD**: Actualiza la documentación como parte de tu pipeline de implementación cuando el código cambie con [Trigger update](/es/api/update/trigger). * **Integraciones personalizadas**: Inserta el Asistente de IA en tu producto, portal de soporte o herramientas internas con [Create assistant message](/es/api/assistant/create-assistant-message-v2) y [Search documentation](/es/api/assistant/search). * **Edición automatizada**: Usa trabajos de agente para actualizar la documentación programáticamente y a escala con [Create agent job](/es/api/agent/v2/create-agent-job), [Get agent job](/es/api/agent/v2/get-agent-job) y [Send follow-up message](/es/api/agent/v2/send-message). -* **Exportación de Analytics**: Exporta comentarios y conversaciones del Asistente de IA para análisis externo con [Get user feedback](/es/api/analytics/feedback) y [Get assistant conversations](/es/api/analytics/assistant-conversations). +* **Exportación de Analytics**: Exporta comentarios y conversaciones del Asistente de IA para análisis externo con [Get user feedback](/es/api/analytics/feedback), [Get feedback by page](/es/api/analytics/feedback-by-page) y [Get assistant conversations](/es/api/analytics/assistant-conversations).
## Autenticación @@ -42,7 +43,7 @@ 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](/es/api/update/trigger), [Get update status](/es/api/update/status), [Create agent job](/es/api/agent/v2/create-agent-job), [Get agent job](/es/api/agent/v2/get-agent-job), [Send follow-up message](/es/api/agent/v2/send-message), [Get user feedback](/es/api/analytics/feedback) y [Get assistant conversations](/es/api/analytics/assistant-conversations). +Usa la clave de la API de administrador para autenticar solicitudes a [Trigger update](/es/api/update/trigger), [Get update status](/es/api/update/status), [Create agent job](/es/api/agent/v2/create-agent-job), [Get agent job](/es/api/agent/v2/get-agent-job), [Send follow-up message](/es/api/agent/v2/send-message), [Get user feedback](/es/api/analytics/feedback), [Get feedback by page](/es/api/analytics/feedback-by-page) y [Get assistant conversations](/es/api/analytics/assistant-conversations). Las claves de la API de administrador comienzan con el prefijo `mint_`. diff --git a/fr/analytics.openapi.json b/fr/analytics.openapi.json index b41ea2b03..251660efa 100644 --- a/fr/analytics.openapi.json +++ b/fr/analytics.openapi.json @@ -246,6 +246,55 @@ "hasMore" ] }, + "FeedbackGroupedByPageResponse": { + "type": "object", + "properties": { + "feedback": { + "type": "array", + "description": "Liste des agrégats de retours par page.", + "items": { + "type": "object", + "properties": { + "path": { + "type": "string", + "description": "Le chemin de la page de documentation." + }, + "thumbsUp": { + "type": "number", + "description": "Nombre d'évaluations positives (pouce en haut) pour la page." + }, + "thumbsDown": { + "type": "number", + "description": "Nombre d'évaluations négatives (pouce en bas) pour la page." + }, + "code": { + "type": "number", + "description": "Nombre de retours sur les extraits de code pour la page." + }, + "total": { + "type": "number", + "description": "Nombre total de retours pour la page." + } + }, + "required": [ + "path", + "thumbsUp", + "thumbsDown", + "code", + "total" + ] + } + }, + "hasMore": { + "type": "boolean", + "description": "Indique si des résultats supplémentaires sont disponibles au-delà de cette page." + } + }, + "required": [ + "feedback", + "hasMore" + ] + }, "AnalyticsErrorResponse": { "type": "object", "properties": { @@ -483,6 +532,111 @@ } } }, + "/v1/analytics/{projectId}/feedback/by-page": { + "get": { + "summary": "Obtenir les retours groupés par page", + "description": "Renvoie les décomptes de retours agrégés par chemin de page de documentation (pouces en haut/bas pour les retours contextuels, nombre d'extraits de code et total par page)", + "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" + ], + "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": 10, + "description": "Nombre maximal de résultats par page" + }, + "required": false, + "name": "limit", + "in": "query" + } + ], + "responses": { + "200": { + "description": "Agrégats de retours par page avec indicateur de pagination", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/FeedbackGroupedByPageResponse" + } + } + } + }, + "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", diff --git a/fr/api/analytics/feedback-by-page.mdx b/fr/api/analytics/feedback-by-page.mdx new file mode 100644 index 000000000..34dd4bf11 --- /dev/null +++ b/fr/api/analytics/feedback-by-page.mdx @@ -0,0 +1,36 @@ +--- +title: "Obtenir les retours par page" +description: "Récupérez les décomptes de retours agrégés par page de documentation, + y compris les évaluations pouces en haut/bas et les retours sur les extraits de code." +openapi: /fr/analytics.openapi.json GET /v1/analytics/{projectId}/feedback/by-page +keywords: ["analytics", "feedback", "export", "retours agrégés", "par page"] +--- + +
+ ## Utilisation +
+ +Utilisez cet endpoint pour obtenir un aperçu du volume de retours sur les pages de votre documentation. Les résultats sont agrégés par chemin de page et triés par nombre total de retours par ordre décroissant. + +Vérifiez le champ `hasMore` dans la réponse pour déterminer si des pages de résultats supplémentaires sont disponibles. Augmentez le paramètre `limit` pour récupérer davantage de résultats par requête. + +
+ ## Filtrage +
+ +Filtrez les agrégats de retours par : + +- **Plage de dates** : utilisez `dateFrom` et `dateTo` pour limiter les résultats à une période donnée +- **Source** : filtrez par type de feedback, `code_snippet` ou `contextual` +- **Statut** : filtrez par des valeurs de statut comme `pending`, `in_progress`, `resolved` ou `dismissed` + +
+ ## Champs de la réponse +
+ +Chaque élément de la réponse représente une page de documentation et inclut : + +- **thumbsUp** : Nombre d'évaluations contextuelles positives (utile) +- **thumbsDown** : Nombre d'évaluations contextuelles négatives (pas utile) +- **code** : Nombre de retours sur les extraits de code +- **total** : Nombre combiné de tous les types de retours pour la page diff --git a/fr/api/introduction.mdx b/fr/api/introduction.mdx index b872d5cff..f5d4100dc 100644 --- a/fr/api/introduction.mdx +++ b/fr/api/introduction.mdx @@ -18,6 +18,7 @@ L'API REST (Representational State Transfer) de Mintlify vous permet d'interagir * [Create assistant message](/fr/api/assistant/create-assistant-message-v2): Intégrez l'Assistant, entraîné sur votre documentation, dans n'importe quelle application de votre choix. * [Search documentation](/fr/api/assistant/search): Effectuez une recherche dans votre documentation. * [Get user feedback](/fr/api/analytics/feedback): Exportez les retours utilisateurs issus de votre documentation. +* [Get feedback by page](/fr/api/analytics/feedback-by-page): Exportez les décomptes de retours agrégés par page de documentation. * [Get assistant conversations](/fr/api/analytics/assistant-conversations): Exportez l'historique des conversations de l'Assistant IA.
@@ -28,7 +29,7 @@ L'API REST (Representational State Transfer) de Mintlify vous permet d'interagir * **Intégration CI/CD** : Mettez à jour la documentation dans le cadre de votre pipeline de déploiement lorsque le code change avec [Trigger update](/fr/api/update/trigger). * **Intégrations personnalisées** : Intégrez l'Assistant IA à votre produit, portail d'assistance ou outils internes avec [Create assistant message](/fr/api/assistant/create-assistant-message-v2) et [Search documentation](/fr/api/assistant/search). * **Édition automatisée** : Utilisez des jobs d'agent pour mettre à jour la documentation de manière programmatique et à grande échelle avec [Create agent job](/fr/api/agent/v2/create-agent-job), [Get agent job](/fr/api/agent/v2/get-agent-job), et [Send follow-up message](/fr/api/agent/v2/send-message). -* **Export Analytics** : Exportez les retours utilisateurs et les conversations avec l'Assistant pour une analyse externe avec [Get user feedback](/fr/api/analytics/feedback) et [Get assistant conversations](/fr/api/analytics/assistant-conversations). +* **Export Analytics** : Exportez les retours utilisateurs et les conversations avec l'Assistant pour une analyse externe avec [Get user feedback](/fr/api/analytics/feedback), [Get feedback by page](/fr/api/analytics/feedback-by-page) et [Get assistant conversations](/fr/api/analytics/assistant-conversations).
## Authentification @@ -42,7 +43,7 @@ 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](/fr/api/update/trigger), [Get update status](/fr/api/update/status), [Create agent job](/fr/api/agent/v2/create-agent-job), [Get agent job](/fr/api/agent/v2/get-agent-job), [Send follow-up message](/fr/api/agent/v2/send-message), [Get user feedback](/fr/api/analytics/feedback) et [Get assistant conversations](/fr/api/analytics/assistant-conversations). +Utilisez la clé d'API administrateur pour authentifier les requêtes vers [Trigger update](/fr/api/update/trigger), [Get update status](/fr/api/update/status), [Create agent job](/fr/api/agent/v2/create-agent-job), [Get agent job](/fr/api/agent/v2/get-agent-job), [Send follow-up message](/fr/api/agent/v2/send-message), [Get user feedback](/fr/api/analytics/feedback), [Get feedback by page](/fr/api/analytics/feedback-by-page) et [Get assistant conversations](/fr/api/analytics/assistant-conversations). Les clés d'API administrateur commencent par le préfixe `mint_`. diff --git a/zh/analytics.openapi.json b/zh/analytics.openapi.json index 0b7a608af..0b7d55ff9 100644 --- a/zh/analytics.openapi.json +++ b/zh/analytics.openapi.json @@ -246,6 +246,55 @@ "hasMore" ] }, + "FeedbackGroupedByPageResponse": { + "type": "object", + "properties": { + "feedback": { + "type": "array", + "description": "按页面分组的反馈聚合列表。", + "items": { + "type": "object", + "properties": { + "path": { + "type": "string", + "description": "文档页面路径。" + }, + "thumbsUp": { + "type": "number", + "description": "该页面的正面评价（点赞）数量。" + }, + "thumbsDown": { + "type": "number", + "description": "该页面的负面评价（点踩）数量。" + }, + "code": { + "type": "number", + "description": "该页面的代码片段反馈数量。" + }, + "total": { + "type": "number", + "description": "该页面的反馈总数。" + } + }, + "required": [ + "path", + "thumbsUp", + "thumbsDown", + "code", + "total" + ] + } + }, + "hasMore": { + "type": "boolean", + "description": "是否有超出当前页面的更多结果可用。" + } + }, + "required": [ + "feedback", + "hasMore" + ] + }, "AnalyticsErrorResponse": { "type": "object", "properties": { @@ -483,6 +532,111 @@ } } }, + "/v1/analytics/{projectId}/feedback/by-page": { + "get": { + "summary": "获取按页面分组的反馈", + "description": "返回按文档页面路径聚合的反馈计数（上下文反馈的点赞/点踩、代码片段数量和每页总计）", + "tags": [ + "Analytics" + ], + "security": [ + { + "bearerAuth": [] + } + ], + "parameters": [ + { + "$ref": "#/components/parameters/projectId" + }, + { + "schema": { + "type": "string", + "description": "ISO 8601 或 YYYY-MM-DD 格式的日期", + "example": "2024-01-01" + }, + "required": false, + "name": "dateFrom", + "in": "query" + }, + { + "schema": { + "type": "string", + "description": "ISO 8601 或 YYYY-MM-DD 格式的日期。`dateTo` 为排他性上限。结果包含该日期之前的数据，但不包含该日期本身。", + "example": "2024-01-01" + }, + "required": false, + "name": "dateTo", + "in": "query" + }, + { + "schema": { + "type": "string", + "enum": [ + "code_snippet", + "contextual" + ], + "description": "按反馈来源筛选" + }, + "required": false, + "name": "source", + "in": "query" + }, + { + "schema": { + "type": "string", + "description": "以逗号分隔的状态列表进行筛选" + }, + "required": false, + "name": "status", + "in": "query" + }, + { + "schema": { + "type": "number", + "minimum": 1, + "maximum": 100, + "default": 10, + "description": "每页最大结果数" + }, + "required": false, + "name": "limit", + "in": "query" + } + ], + "responses": { + "200": { + "description": "按页面分组的反馈聚合及分页标志", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/FeedbackGroupedByPageResponse" + } + } + } + }, + "400": { + "description": "无效的查询参数", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AnalyticsErrorResponse" + } + } + } + }, + "500": { + "description": "服务器错误", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AnalyticsErrorResponse" + } + } + } + } + } + } + }, "/v1/analytics/{projectId}/assistant": { "get": { "summary": "获取 AI 助手会话记录", diff --git a/zh/api/analytics/feedback-by-page.mdx b/zh/api/analytics/feedback-by-page.mdx new file mode 100644 index 000000000..bca806657 --- /dev/null +++ b/zh/api/analytics/feedback-by-page.mdx @@ -0,0 +1,35 @@ +--- +title: "按页面获取反馈" +description: "获取按文档页面聚合的反馈计数，包括点赞/点踩评分和代码片段反馈。" +openapi: /zh/analytics.openapi.json GET /v1/analytics/{projectId}/feedback/by-page +keywords: ["Analytics", "反馈", "导出", "聚合反馈", "按页面"] +--- + +
+ ## 用法 +
+ +使用此端点获取文档各页面反馈量的概览。结果按页面路径聚合，并按反馈总数降序排列。 + +检查响应中的 `hasMore` 字段以确定是否有更多结果页面可用。增大 `limit` 参数可以在每次请求中获取更多结果。 + +
+ ## 筛选 +
+ +可以按以下维度筛选反馈聚合： + +- **日期范围**：使用 `dateFrom` 和 `dateTo` 将结果限定在特定时间段内 +- **来源**：按 `code_snippet` 或 `contextual` 等反馈来源类型进行筛选 +- **状态**：按状态值进行筛选，例如 `pending`、`in_progress`、`resolved` 或 `dismissed` + +
+ ## 响应字段 +
+ +响应中的每个元素代表一个文档页面，包含： + +- **thumbsUp**：正面（有帮助）上下文评分数量 +- **thumbsDown**：负面（没有帮助）上下文评分数量 +- **code**：代码片段反馈条目数量 +- **total**：该页面所有类型反馈的总计数 diff --git a/zh/api/introduction.mdx b/zh/api/introduction.mdx index b1844beb4..fc092c5a9 100644 --- a/zh/api/introduction.mdx +++ b/zh/api/introduction.mdx @@ -18,6 +18,7 @@ Mintlify 的 REST（Representational State Transfer）API 让你可以以编程 * [Create assistant message](/zh/api/assistant/create-assistant-message-v2)：将基于您的文档训练的 AI 助手嵌入到任意您选择的应用中。 * [搜索文档](/zh/api/assistant/search)：搜索您的文档。 * [获取用户反馈](/zh/api/analytics/feedback)：从您的文档中导出用户反馈。 +* [按页面获取反馈](/zh/api/analytics/feedback-by-page)：导出按文档页面聚合的反馈计数。 * [获取 AI 助手会话](/zh/api/analytics/assistant-conversations)：导出 AI 助手的会话历史。
@@ -28,7 +29,7 @@ Mintlify 的 REST（Representational State Transfer）API 让你可以以编程 * **CI/CD 集成**：在代码变更时，将文档更新作为部署流水线的一部分来执行，使用 [Trigger update](/zh/api/update/trigger)。 * **自定义集成**：使用 [Create assistant message](/zh/api/assistant/create-assistant-message-v2) 和 [Search documentation](/zh/api/assistant/search)，将 AI 助手嵌入到你的产品、支持门户或内部工具中。 * **自动化编辑**：使用 agent 任务，以编程方式大规模更新文档，配合 [Create agent job](/zh/api/agent/v2/create-agent-job)、[Get agent job](/zh/api/agent/v2/get-agent-job) 和 [Send follow-up message](/zh/api/agent/v2/send-message)。 -* **Analytics 导出**：使用 [Get user feedback](/zh/api/analytics/feedback) 和 [Get assistant conversations](/zh/api/analytics/assistant-conversations)，导出反馈和 AI 助手会话以进行外部分析。 +* **Analytics 导出**：使用 [Get user feedback](/zh/api/analytics/feedback)、[按页面获取反馈](/zh/api/analytics/feedback-by-page) 和 [Get assistant conversations](/zh/api/analytics/assistant-conversations)，导出反馈和 AI 助手会话以进行外部分析。
## 认证 @@ -42,7 +43,7 @@ Mintlify 的 REST（Representational State Transfer）API 让你可以以编程 ### 管理员 API key
-使用管理员 API key 对发送到 [Trigger update](/zh/api/update/trigger)、[Get update status](/zh/api/update/status)、[Create agent job](/zh/api/agent/v2/create-agent-job)、[Get agent job](/zh/api/agent/v2/get-agent-job)、[Send follow-up message](/zh/api/agent/v2/send-message)、[Get user feedback](/zh/api/analytics/feedback) 和 [Get assistant conversations](/zh/api/analytics/assistant-conversations) 的请求进行身份验证。 +使用管理员 API key 对发送到 [Trigger update](/zh/api/update/trigger)、[Get update status](/zh/api/update/status)、[Create agent job](/zh/api/agent/v2/create-agent-job)、[Get agent job](/zh/api/agent/v2/get-agent-job)、[Send follow-up message](/zh/api/agent/v2/send-message)、[Get user feedback](/zh/api/analytics/feedback)、[按页面获取反馈](/zh/api/analytics/feedback-by-page) 和 [Get assistant conversations](/zh/api/analytics/assistant-conversations) 的请求进行身份验证。 管理员 API key 以 `mint_` 前缀开头。