From e3f310e4cff7bdff6e869515860403b69a9901e8 Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Wed, 25 Mar 2026 23:12:05 +0000 Subject: [PATCH 1/7] Add docs for feedback-by-page and search queries analytics endpoints Generated-By: mintlify-agent --- analytics.openapi.json | 307 +++++++++++++++++++++++++ api/analytics/feedback-by-page.mdx | 28 +++ api/analytics/searches.mdx | 27 +++ api/introduction.mdx | 6 +- docs.json | 16 +- es/analytics.openapi.json | 309 +++++++++++++++++++++++++- es/api/analytics/feedback-by-page.mdx | 36 +++ es/api/analytics/searches.mdx | 34 +++ fr/analytics.openapi.json | 309 +++++++++++++++++++++++++- fr/api/analytics/feedback-by-page.mdx | 36 +++ fr/api/analytics/searches.mdx | 34 +++ zh/analytics.openapi.json | 309 +++++++++++++++++++++++++- zh/api/analytics/feedback-by-page.mdx | 36 +++ zh/api/analytics/searches.mdx | 34 +++ 14 files changed, 1512 insertions(+), 9 deletions(-) create mode 100644 api/analytics/feedback-by-page.mdx create mode 100644 api/analytics/searches.mdx create mode 100644 es/api/analytics/feedback-by-page.mdx create mode 100644 es/api/analytics/searches.mdx create mode 100644 fr/api/analytics/feedback-by-page.mdx create mode 100644 fr/api/analytics/searches.mdx create mode 100644 zh/api/analytics/feedback-by-page.mdx create mode 100644 zh/api/analytics/searches.mdx diff --git a/analytics.openapi.json b/analytics.openapi.json index e7b80c1b6..6240242e6 100644 --- a/analytics.openapi.json +++ b/analytics.openapi.json @@ -355,6 +355,116 @@ "nextCursor", "hasMore" ] + }, + "FeedbackGroupedByPageResponse": { + "type": "object", + "properties": { + "feedback": { + "type": "array", + "description": "Feedback counts aggregated by documentation page path.", + "items": { + "type": "object", + "properties": { + "path": { + "type": "string", + "description": "The documentation page path." + }, + "thumbsUp": { + "type": "number", + "description": "Number of positive (thumbs up) contextual feedback entries." + }, + "thumbsDown": { + "type": "number", + "description": "Number of negative (thumbs down) contextual feedback entries." + }, + "code": { + "type": "number", + "description": "Number of code snippet feedback entries." + }, + "total": { + "type": "number", + "description": "Total feedback entries for this page." + } + }, + "required": [ + "path", + "thumbsUp", + "thumbsDown", + "code", + "total" + ] + } + }, + "hasMore": { + "type": "boolean", + "description": "Whether additional results are available beyond this page." + } + }, + "required": [ + "feedback", + "hasMore" + ] + }, + "SearchesResponse": { + "type": "object", + "properties": { + "searches": { + "type": "array", + "description": "Search terms ordered by hit count descending.", + "items": { + "type": "object", + "properties": { + "searchQuery": { + "type": "string", + "description": "The search term entered by users." + }, + "hits": { + "type": "number", + "description": "Number of times this term was searched." + }, + "ctr": { + "type": "number", + "description": "Click-through rate for this search term." + }, + "topClickedPage": { + "type": [ + "string", + "null" + ], + "description": "The most-clicked result path for this query, if any." + }, + "lastSearchedAt": { + "type": "string", + "description": "Timestamp of the last time this term was searched." + } + }, + "required": [ + "searchQuery", + "hits", + "ctr", + "topClickedPage", + "lastSearchedAt" + ] + } + }, + "totalSearches": { + "type": "integer", + "minimum": 0, + "description": "Total count of search events in the requested date range (sum of all hits, not distinct queries)." + }, + "nextCursor": { + "type": [ + "string", + "null" + ], + "description": "Opaque pagination cursor for the next page. Null if no more results." + } + }, + "required": [ + "searches", + "totalSearches", + "nextCursor" + ] } }, "parameters": { @@ -483,6 +593,111 @@ } } }, + "/v1/analytics/{projectId}/feedback/by-page": { + "get": { + "summary": "Get feedback by page", + "description": "Returns feedback counts aggregated by documentation page path (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": "number", + "minimum": 1, + "maximum": 100, + "default": 10, + "description": "Max results per page" + }, + "required": false, + "name": "limit", + "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" + } + ], + "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", @@ -575,6 +790,98 @@ } } } + }, + "/v1/analytics/{projectId}/searches": { + "get": { + "summary": "Get search queries", + "description": "Returns paginated documentation search terms for the date range, ordered by hit count descending. Each row includes click-through rate, the most-clicked result path for that query (if any), and the last time the term was searched. `totalSearches` is the total number of search query events in the same date range (sum of all hits, not distinct queries).", + "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": "number", + "minimum": 1, + "maximum": 100, + "default": 50, + "description": "Max search terms per page (ordered by hit count descending)" + }, + "required": false, + "name": "limit", + "in": "query" + }, + { + "schema": { + "type": "string", + "description": "Opaque pagination cursor from the previous response" + }, + "required": false, + "name": "cursor", + "in": "query" + } + ], + "responses": { + "200": { + "description": "Search term aggregates with pagination", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/SearchesResponse" + } + } + } + }, + "400": { + "description": "Invalid query parameters or cursor", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AnalyticsErrorResponse" + } + } + } + }, + "500": { + "description": "Server error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AnalyticsErrorResponse" + } + } + } + } + } + } } }, "webhooks": {} diff --git a/api/analytics/feedback-by-page.mdx b/api/analytics/feedback-by-page.mdx new file mode 100644 index 000000000..9e875845c --- /dev/null +++ b/api/analytics/feedback-by-page.mdx @@ -0,0 +1,28 @@ +--- +title: "Get feedback by page" +description: "Retrieve user 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", "by page", "aggregated"] +--- + +## Usage + +Use this endpoint to export user feedback aggregated by documentation page path. Each entry shows the total feedback count for a page, broken down by type. + +Paginate through results using the `hasMore` flag in the response. + +## Filtering + +Filter feedback 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 data + +Each page entry includes: +- **path**: The documentation page path +- **thumbsUp**: Count of positive contextual feedback +- **thumbsDown**: Count of negative contextual feedback +- **code**: Count of code snippet feedback +- **total**: Total feedback entries for the page diff --git a/api/analytics/searches.mdx b/api/analytics/searches.mdx new file mode 100644 index 000000000..ab9a41c02 --- /dev/null +++ b/api/analytics/searches.mdx @@ -0,0 +1,27 @@ +--- +title: "Get search queries" +description: "Retrieve documentation search terms with hit counts, click-through rates, and top clicked pages." +openapi: /analytics.openapi.json GET /v1/analytics/{projectId}/searches +keywords: ["analytics", "search", "export", "queries", "search terms"] +--- + +## Usage + +Use this endpoint to export documentation search analytics. Results are ordered by hit count descending, showing which terms your users search for most. + +Paginate through results using the `nextCursor` parameter returned in the response. Continue fetching while `nextCursor` is not null. + +## Filtering + +Filter search data by date range using `dateFrom` and `dateTo` parameters. + +## Response data + +Each search term entry includes: +- **searchQuery**: The search term entered by users +- **hits**: Number of times this term was searched +- **ctr**: Click-through rate for this search term +- **topClickedPage**: The most-clicked result path for this query, if any +- **lastSearchedAt**: Timestamp of the last time this term was searched + +The response also includes `totalSearches`, which is the total count of all search events in the requested date range (sum of all hits, not distinct queries). diff --git a/api/introduction.mdx b/api/introduction.mdx index d5b28d6d2..02f0de958 100644 --- a/api/introduction.mdx +++ b/api/introduction.mdx @@ -16,7 +16,9 @@ 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 page. - [Get assistant conversations](/api/analytics/assistant-conversations): Export AI assistant conversation history. +- [Get search queries](/api/analytics/searches): Export documentation search terms and analytics. ### Common use cases @@ -24,7 +26,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, assistant conversations, and search analytics for external analysis with [Get user feedback](/api/analytics/feedback), [Get feedback by page](/api/analytics/feedback-by-page), [Get assistant conversations](/api/analytics/assistant-conversations), and [Get search queries](/api/analytics/searches). ## Authentication @@ -34,7 +36,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), [Get assistant conversations](/api/analytics/assistant-conversations), and [Get search queries](/api/analytics/searches). Admin API keys begin with the `mint_` prefix. diff --git a/docs.json b/docs.json index af1132fe7..e64ffaa4d 100644 --- a/docs.json +++ b/docs.json @@ -373,7 +373,9 @@ "icon": "chart-line", "pages": [ "api/analytics/feedback", - "api/analytics/assistant-conversations" + "api/analytics/feedback-by-page", + "api/analytics/assistant-conversations", + "api/analytics/searches" ] } ] @@ -745,7 +747,9 @@ "icon": "chart-line", "pages": [ "fr/api/analytics/feedback", - "fr/api/analytics/assistant-conversations" + "fr/api/analytics/feedback-by-page", + "fr/api/analytics/assistant-conversations", + "fr/api/analytics/searches" ] } ] @@ -1117,7 +1121,9 @@ "icon": "chart-line", "pages": [ "es/api/analytics/feedback", - "es/api/analytics/assistant-conversations" + "es/api/analytics/feedback-by-page", + "es/api/analytics/assistant-conversations", + "es/api/analytics/searches" ] } ] @@ -1489,7 +1495,9 @@ "icon": "chart-line", "pages": [ "zh/api/analytics/feedback", - "zh/api/analytics/assistant-conversations" + "zh/api/analytics/feedback-by-page", + "zh/api/analytics/assistant-conversations", + "zh/api/analytics/searches" ] } ] diff --git a/es/analytics.openapi.json b/es/analytics.openapi.json index 636f47515..528326b95 100644 --- a/es/analytics.openapi.json +++ b/es/analytics.openapi.json @@ -355,6 +355,116 @@ "nextCursor", "hasMore" ] + }, + "FeedbackGroupedByPageResponse": { + "type": "object", + "properties": { + "feedback": { + "type": "array", + "description": "Feedback counts aggregated by documentation page path.", + "items": { + "type": "object", + "properties": { + "path": { + "type": "string", + "description": "The documentation page path." + }, + "thumbsUp": { + "type": "number", + "description": "Number of positive (thumbs up) contextual feedback entries." + }, + "thumbsDown": { + "type": "number", + "description": "Number of negative (thumbs down) contextual feedback entries." + }, + "code": { + "type": "number", + "description": "Number of code snippet feedback entries." + }, + "total": { + "type": "number", + "description": "Total feedback entries for this page." + } + }, + "required": [ + "path", + "thumbsUp", + "thumbsDown", + "code", + "total" + ] + } + }, + "hasMore": { + "type": "boolean", + "description": "Whether additional results are available beyond this page." + } + }, + "required": [ + "feedback", + "hasMore" + ] + }, + "SearchesResponse": { + "type": "object", + "properties": { + "searches": { + "type": "array", + "description": "Search terms ordered by hit count descending.", + "items": { + "type": "object", + "properties": { + "searchQuery": { + "type": "string", + "description": "The search term entered by users." + }, + "hits": { + "type": "number", + "description": "Number of times this term was searched." + }, + "ctr": { + "type": "number", + "description": "Click-through rate for this search term." + }, + "topClickedPage": { + "type": [ + "string", + "null" + ], + "description": "The most-clicked result path for this query, if any." + }, + "lastSearchedAt": { + "type": "string", + "description": "Timestamp of the last time this term was searched." + } + }, + "required": [ + "searchQuery", + "hits", + "ctr", + "topClickedPage", + "lastSearchedAt" + ] + } + }, + "totalSearches": { + "type": "integer", + "minimum": 0, + "description": "Total count of search events in the requested date range." + }, + "nextCursor": { + "type": [ + "string", + "null" + ], + "description": "Opaque pagination cursor for the next page. Null if no more results." + } + }, + "required": [ + "searches", + "totalSearches", + "nextCursor" + ] } }, "parameters": { @@ -483,6 +593,111 @@ } } }, + "/v1/analytics/{projectId}/feedback/by-page": { + "get": { + "summary": "Obtener comentarios por pagina", + "description": "Devuelve comentarios agregados por ruta de pagina", + "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": "Limite superior exclusivo", + "example": "2024-01-01" + }, + "required": false, + "name": "dateTo", + "in": "query" + }, + { + "schema": { + "type": "number", + "minimum": 1, + "maximum": 100, + "default": 10, + "description": "Numero maximo de resultados por pagina" + }, + "required": false, + "name": "limit", + "in": "query" + }, + { + "schema": { + "type": "string", + "enum": [ + "code_snippet", + "contextual" + ], + "description": "Filtrar por origen de los comentarios" + }, + "required": false, + "name": "source", + "in": "query" + }, + { + "schema": { + "type": "string", + "description": "Estados separados por comas" + }, + "required": false, + "name": "status", + "in": "query" + } + ], + "responses": { + "200": { + "description": "Comentarios agregados por pagina", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/FeedbackGroupedByPageResponse" + } + } + } + }, + "400": { + "description": "Parametros no validos", + "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", @@ -575,7 +790,99 @@ } } } + }, + "/v1/analytics/{projectId}/searches": { + "get": { + "summary": "Obtener consultas de busqueda", + "description": "Devuelve terminos de busqueda paginados ordenados por numero de busquedas", + "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": "Limite superior exclusivo", + "example": "2024-01-01" + }, + "required": false, + "name": "dateTo", + "in": "query" + }, + { + "schema": { + "type": "number", + "minimum": 1, + "maximum": 100, + "default": 50, + "description": "Numero maximo de terminos por pagina" + }, + "required": false, + "name": "limit", + "in": "query" + }, + { + "schema": { + "type": "string", + "description": "Cursor de paginacion opaco" + }, + "required": false, + "name": "cursor", + "in": "query" + } + ], + "responses": { + "200": { + "description": "Terminos de busqueda agregados", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/SearchesResponse" + } + } + } + }, + "400": { + "description": "Parametros no validos", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AnalyticsErrorResponse" + } + } + } + }, + "500": { + "description": "Error del servidor", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AnalyticsErrorResponse" + } + } + } + } + } + } } }, "webhooks": {} -} \ No newline at end of file +} diff --git a/es/api/analytics/feedback-by-page.mdx b/es/api/analytics/feedback-by-page.mdx new file mode 100644 index 000000000..de614a96b --- /dev/null +++ b/es/api/analytics/feedback-by-page.mdx @@ -0,0 +1,36 @@ +--- +title: "Obtener comentarios por página" +description: "Obtén los conteos de comentarios de los usuarios agregados por página de documentación, incluyendo valoraciones de pulgar arriba/abajo y comentarios sobre fragmentos de código." +openapi: /es/analytics.openapi.json GET /v1/analytics/{projectId}/feedback/by-page +keywords: ["analytics", "comentarios", "exportación", "por página", "agregado"] +--- + +
+ ## Uso +
+ +Usa este endpoint para exportar los comentarios de los usuarios agregados por ruta de página de documentación. Cada entrada muestra el conteo total de comentarios para una página, desglosado por tipo. + +Pagina los resultados usando el indicador `hasMore` en la respuesta. + +
+ ## Filtrado +
+ +Filtra los 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` + +
+ ## Datos de respuesta +
+ +Cada entrada de página incluye: + +- **path**: La ruta de la página de documentación +- **thumbsUp**: Conteo de comentarios contextuales positivos +- **thumbsDown**: Conteo de comentarios contextuales negativos +- **code**: Conteo de comentarios sobre fragmentos de código +- **total**: Total de entradas de comentarios para la página diff --git a/es/api/analytics/searches.mdx b/es/api/analytics/searches.mdx new file mode 100644 index 000000000..2a6555033 --- /dev/null +++ b/es/api/analytics/searches.mdx @@ -0,0 +1,34 @@ +--- +title: "Obtener consultas de búsqueda" +description: "Obtén los términos de búsqueda de la documentación con conteos de búsquedas, tasas de clics y las páginas más clicadas." +openapi: /es/analytics.openapi.json GET /v1/analytics/{projectId}/searches +keywords: ["analytics", "búsqueda", "exportación", "consultas", "términos de búsqueda"] +--- + +
+ ## Uso +
+ +Usa este endpoint para exportar los datos analíticos de búsqueda de tu documentación. Los resultados se ordenan por número de búsquedas de forma descendente, mostrando los términos que más buscan tus usuarios. + +Pagina los resultados usando el parámetro `nextCursor` devuelto en la respuesta. Continúa obteniendo resultados mientras `nextCursor` no sea null. + +
+ ## Filtrado +
+ +Filtra los datos de búsqueda por rango de fechas usando los parámetros `dateFrom` y `dateTo`. + +
+ ## Datos de respuesta +
+ +Cada entrada de término de búsqueda incluye: + +- **searchQuery**: El término de búsqueda introducido por los usuarios +- **hits**: Número de veces que se buscó este término +- **ctr**: Tasa de clics para este término de búsqueda +- **topClickedPage**: La ruta del resultado más clicado para esta consulta, si existe +- **lastSearchedAt**: Marca de tiempo de la última vez que se buscó este término + +La respuesta también incluye `totalSearches`, que es el conteo total de todos los eventos de búsqueda en el rango de fechas solicitado (suma de todos los hits, no consultas distintas). diff --git a/fr/analytics.openapi.json b/fr/analytics.openapi.json index b41ea2b03..58b955a19 100644 --- a/fr/analytics.openapi.json +++ b/fr/analytics.openapi.json @@ -355,6 +355,116 @@ "nextCursor", "hasMore" ] + }, + "FeedbackGroupedByPageResponse": { + "type": "object", + "properties": { + "feedback": { + "type": "array", + "description": "Feedback counts aggregated by documentation page path.", + "items": { + "type": "object", + "properties": { + "path": { + "type": "string", + "description": "The documentation page path." + }, + "thumbsUp": { + "type": "number", + "description": "Number of positive (thumbs up) contextual feedback entries." + }, + "thumbsDown": { + "type": "number", + "description": "Number of negative (thumbs down) contextual feedback entries." + }, + "code": { + "type": "number", + "description": "Number of code snippet feedback entries." + }, + "total": { + "type": "number", + "description": "Total feedback entries for this page." + } + }, + "required": [ + "path", + "thumbsUp", + "thumbsDown", + "code", + "total" + ] + } + }, + "hasMore": { + "type": "boolean", + "description": "Whether additional results are available beyond this page." + } + }, + "required": [ + "feedback", + "hasMore" + ] + }, + "SearchesResponse": { + "type": "object", + "properties": { + "searches": { + "type": "array", + "description": "Search terms ordered by hit count descending.", + "items": { + "type": "object", + "properties": { + "searchQuery": { + "type": "string", + "description": "The search term entered by users." + }, + "hits": { + "type": "number", + "description": "Number of times this term was searched." + }, + "ctr": { + "type": "number", + "description": "Click-through rate for this search term." + }, + "topClickedPage": { + "type": [ + "string", + "null" + ], + "description": "The most-clicked result path for this query, if any." + }, + "lastSearchedAt": { + "type": "string", + "description": "Timestamp of the last time this term was searched." + } + }, + "required": [ + "searchQuery", + "hits", + "ctr", + "topClickedPage", + "lastSearchedAt" + ] + } + }, + "totalSearches": { + "type": "integer", + "minimum": 0, + "description": "Total count of search events in the requested date range." + }, + "nextCursor": { + "type": [ + "string", + "null" + ], + "description": "Opaque pagination cursor for the next page. Null if no more results." + } + }, + "required": [ + "searches", + "totalSearches", + "nextCursor" + ] } }, "parameters": { @@ -483,6 +593,111 @@ } } }, + "/v1/analytics/{projectId}/feedback/by-page": { + "get": { + "summary": "Obtenir les retours par page", + "description": "Renvoie les comptages de retours par chemin de 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": "Borne superieure exclusive", + "example": "2024-01-01" + }, + "required": false, + "name": "dateTo", + "in": "query" + }, + { + "schema": { + "type": "number", + "minimum": 1, + "maximum": 100, + "default": 10, + "description": "Nombre maximal de resultats par page" + }, + "required": false, + "name": "limit", + "in": "query" + }, + { + "schema": { + "type": "string", + "enum": [ + "code_snippet", + "contextual" + ], + "description": "Filtrer par source des retours" + }, + "required": false, + "name": "source", + "in": "query" + }, + { + "schema": { + "type": "string", + "description": "Statuts separes par des virgules" + }, + "required": false, + "name": "status", + "in": "query" + } + ], + "responses": { + "200": { + "description": "Agregats de retours par page", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/FeedbackGroupedByPageResponse" + } + } + } + }, + "400": { + "description": "Parametres de requete 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", @@ -575,7 +790,99 @@ } } } + }, + "/v1/analytics/{projectId}/searches": { + "get": { + "summary": "Obtenir les requetes de recherche", + "description": "Renvoie les termes de recherche pagines classes par nombre de requetes", + "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": "Borne superieure exclusive", + "example": "2024-01-01" + }, + "required": false, + "name": "dateTo", + "in": "query" + }, + { + "schema": { + "type": "number", + "minimum": 1, + "maximum": 100, + "default": 50, + "description": "Nombre maximal de termes par page" + }, + "required": false, + "name": "limit", + "in": "query" + }, + { + "schema": { + "type": "string", + "description": "Curseur de pagination opaque" + }, + "required": false, + "name": "cursor", + "in": "query" + } + ], + "responses": { + "200": { + "description": "Agregats de termes de recherche", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/SearchesResponse" + } + } + } + }, + "400": { + "description": "Parametres invalides", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AnalyticsErrorResponse" + } + } + } + }, + "500": { + "description": "Erreur serveur", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AnalyticsErrorResponse" + } + } + } + } + } + } } }, "webhooks": {} -} \ No newline at end of file +} diff --git a/fr/api/analytics/feedback-by-page.mdx b/fr/api/analytics/feedback-by-page.mdx new file mode 100644 index 000000000..fdb199219 --- /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 comptages de retours utilisateurs agrégés par page de documentation, incluant les évaluations pouce levé/baissé et les retours sur les extraits de code." +openapi: /fr/analytics.openapi.json GET /v1/analytics/{projectId}/feedback/by-page +keywords: ["analytics", "retours", "export", "par page", "agrégé"] +--- + +
+ ## Utilisation +
+ +Utilisez cet endpoint pour exporter les retours utilisateurs agrégés par chemin de page de documentation. Chaque entrée affiche le nombre total de retours pour une page, ventilé par type. + +Parcourez les résultats à l'aide de l'indicateur `hasMore` dans la réponse. + +
+ ## Filtrage +
+ +Filtrez les retours par : + +- **Plage de dates** : utilisez `dateFrom` et `dateTo` pour limiter les résultats à une période donnée +- **Source** : filtrez par type de retour, `code_snippet` ou `contextual` +- **Statut** : filtrez par des valeurs de statut comme `pending`, `in_progress`, `resolved` ou `dismissed` + +
+ ## Données de la réponse +
+ +Chaque entrée de page inclut : + +- **path** : le chemin de la page de documentation +- **thumbsUp** : nombre de retours contextuels positifs +- **thumbsDown** : nombre de retours contextuels négatifs +- **code** : nombre de retours sur des extraits de code +- **total** : nombre total de retours pour la page diff --git a/fr/api/analytics/searches.mdx b/fr/api/analytics/searches.mdx new file mode 100644 index 000000000..af75badb0 --- /dev/null +++ b/fr/api/analytics/searches.mdx @@ -0,0 +1,34 @@ +--- +title: "Obtenir les requêtes de recherche" +description: "Récupérez les termes de recherche de la documentation avec le nombre de requêtes, les taux de clics et les pages les plus cliquées." +openapi: /fr/analytics.openapi.json GET /v1/analytics/{projectId}/searches +keywords: ["analytics", "recherche", "export", "requêtes", "termes de recherche"] +--- + +
+ ## Utilisation +
+ +Utilisez cet endpoint pour exporter les données analytiques de recherche de votre documentation. Les résultats sont classés par nombre de requêtes décroissant, montrant les termes les plus recherchés par vos utilisateurs. + +Parcourez les résultats à l'aide du paramètre `nextCursor` renvoyé dans la réponse. Continuez à récupérer les données tant que `nextCursor` n'est pas null. + +
+ ## Filtrage +
+ +Filtrez les données de recherche par plage de dates à l'aide des paramètres `dateFrom` et `dateTo`. + +
+ ## Données de la réponse +
+ +Chaque entrée de terme de recherche inclut : + +- **searchQuery** : le terme de recherche saisi par les utilisateurs +- **hits** : nombre de fois que ce terme a été recherché +- **ctr** : taux de clics pour ce terme de recherche +- **topClickedPage** : le chemin du résultat le plus cliqué pour cette requête, le cas échéant +- **lastSearchedAt** : horodatage de la dernière recherche de ce terme + +La réponse inclut également `totalSearches`, qui correspond au nombre total d'événements de recherche dans la période demandée (somme de tous les hits, pas le nombre de requêtes distinctes). diff --git a/zh/analytics.openapi.json b/zh/analytics.openapi.json index 0b7a608af..c4b0c40f9 100644 --- a/zh/analytics.openapi.json +++ b/zh/analytics.openapi.json @@ -355,6 +355,116 @@ "nextCursor", "hasMore" ] + }, + "FeedbackGroupedByPageResponse": { + "type": "object", + "properties": { + "feedback": { + "type": "array", + "description": "Feedback counts aggregated by documentation page path.", + "items": { + "type": "object", + "properties": { + "path": { + "type": "string", + "description": "The documentation page path." + }, + "thumbsUp": { + "type": "number", + "description": "Number of positive (thumbs up) contextual feedback entries." + }, + "thumbsDown": { + "type": "number", + "description": "Number of negative (thumbs down) contextual feedback entries." + }, + "code": { + "type": "number", + "description": "Number of code snippet feedback entries." + }, + "total": { + "type": "number", + "description": "Total feedback entries for this page." + } + }, + "required": [ + "path", + "thumbsUp", + "thumbsDown", + "code", + "total" + ] + } + }, + "hasMore": { + "type": "boolean", + "description": "Whether additional results are available beyond this page." + } + }, + "required": [ + "feedback", + "hasMore" + ] + }, + "SearchesResponse": { + "type": "object", + "properties": { + "searches": { + "type": "array", + "description": "Search terms ordered by hit count descending.", + "items": { + "type": "object", + "properties": { + "searchQuery": { + "type": "string", + "description": "The search term entered by users." + }, + "hits": { + "type": "number", + "description": "Number of times this term was searched." + }, + "ctr": { + "type": "number", + "description": "Click-through rate for this search term." + }, + "topClickedPage": { + "type": [ + "string", + "null" + ], + "description": "The most-clicked result path for this query, if any." + }, + "lastSearchedAt": { + "type": "string", + "description": "Timestamp of the last time this term was searched." + } + }, + "required": [ + "searchQuery", + "hits", + "ctr", + "topClickedPage", + "lastSearchedAt" + ] + } + }, + "totalSearches": { + "type": "integer", + "minimum": 0, + "description": "Total count of search events in the requested date range." + }, + "nextCursor": { + "type": [ + "string", + "null" + ], + "description": "Opaque pagination cursor for the next page. Null if no more results." + } + }, + "required": [ + "searches", + "totalSearches", + "nextCursor" + ] } }, "parameters": { @@ -483,6 +593,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": "不包含在内的上界", + "example": "2024-01-01" + }, + "required": false, + "name": "dateTo", + "in": "query" + }, + { + "schema": { + "type": "number", + "minimum": 1, + "maximum": 100, + "default": 10, + "description": "每页返回的最大结果数" + }, + "required": false, + "name": "limit", + "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" + } + ], + "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 助手会话记录", @@ -575,7 +790,99 @@ } } } + }, + "/v1/analytics/{projectId}/searches": { + "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": "不包含在内的上界", + "example": "2024-01-01" + }, + "required": false, + "name": "dateTo", + "in": "query" + }, + { + "schema": { + "type": "number", + "minimum": 1, + "maximum": 100, + "default": 50, + "description": "每页返回的最大搜索词数" + }, + "required": false, + "name": "limit", + "in": "query" + }, + { + "schema": { + "type": "string", + "description": "上一次响应中的分页游标" + }, + "required": false, + "name": "cursor", + "in": "query" + } + ], + "responses": { + "200": { + "description": "搜索词汇总数据", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/SearchesResponse" + } + } + } + }, + "400": { + "description": "无效的查询参数或游标", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AnalyticsErrorResponse" + } + } + } + }, + "500": { + "description": "服务器错误", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AnalyticsErrorResponse" + } + } + } + } + } + } } }, "webhooks": {} -} \ No newline at end of file +} diff --git a/zh/api/analytics/feedback-by-page.mdx b/zh/api/analytics/feedback-by-page.mdx new file mode 100644 index 000000000..a97277afa --- /dev/null +++ b/zh/api/analytics/feedback-by-page.mdx @@ -0,0 +1,36 @@ +--- +title: "按页面获取反馈" +description: "获取按文档页面汇总的用户反馈计数，包括点赞/踩评分和代码片段反馈。" +openapi: /zh/analytics.openapi.json GET /v1/analytics/{projectId}/feedback/by-page +keywords: ["Analytics", "反馈", "导出", "按页面", "汇总"] +--- + +
+ ## 用法 +
+ +使用此端点导出按文档页面路径汇总的用户反馈。每个条目显示某个页面的反馈总数，并按类型进行细分。 + +使用响应中的 `hasMore` 标志对结果进行分页。 + +
+ ## 筛选 +
+ +可以按以下维度筛选反馈： + +- **日期范围**：使用 `dateFrom` 和 `dateTo` 将结果限定在特定时间段内 +- **来源**：按 `code_snippet` 或 `contextual` 等反馈来源类型进行筛选 +- **状态**：按状态值进行筛选，例如 `pending`、`in_progress`、`resolved` 或 `dismissed` + +
+ ## 响应数据 +
+ +每个页面条目包含： + +- **path**：文档页面路径 +- **thumbsUp**：正面上下文反馈数量 +- **thumbsDown**：负面上下文反馈数量 +- **code**：代码片段反馈数量 +- **total**：该页面的反馈总数 diff --git a/zh/api/analytics/searches.mdx b/zh/api/analytics/searches.mdx new file mode 100644 index 000000000..9481383f9 --- /dev/null +++ b/zh/api/analytics/searches.mdx @@ -0,0 +1,34 @@ +--- +title: "获取搜索查询" +description: "获取文档搜索词及其搜索次数、点击率和最多点击的页面。" +openapi: /zh/analytics.openapi.json GET /v1/analytics/{projectId}/searches +keywords: ["Analytics", "搜索", "导出", "查询", "搜索词"] +--- + +
+ ## 使用方法 +
+ +使用此端点导出文档搜索分析数据。结果按搜索次数降序排列，展示用户最常搜索的词条。 + +使用响应中返回的 `nextCursor` 参数对结果进行分页。当 `nextCursor` 不为 null 时继续获取。 + +
+ ## 筛选 +
+ +使用 `dateFrom` 和 `dateTo` 参数按日期范围过滤搜索数据。 + +
+ ## 响应数据 +
+ +每个搜索词条目包含： + +- **searchQuery**：用户输入的搜索词 +- **hits**：该词被搜索的次数 +- **ctr**：该搜索词的点击率 +- **topClickedPage**：该查询中被点击最多的结果页面路径（如果有） +- **lastSearchedAt**：该词最后一次被搜索的时间戳 + +响应还包含 `totalSearches`，即请求日期范围内所有搜索事件的总数（所有 hits 的总和，而非不同查询的数量）。 From a11096826e74b3044962b80e32e06b70cf24bded Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Thu, 26 Mar 2026 20:27:54 +0000 Subject: [PATCH 2/7] Add page views and unique visitors analytics API docs Generated-By: mintlify-agent --- analytics.openapi.json | 304 ++++++++++++++++++++++ api/analytics/views.mdx | 24 ++ api/analytics/visitors.mdx | 24 ++ api/introduction.mdx | 6 +- docs.json | 16 +- es/analytics.openapi.json | 474 ++++++++++++++++++++++++++++------ es/api/analytics/views.mdx | 31 +++ es/api/analytics/visitors.mdx | 31 +++ fr/analytics.openapi.json | 472 +++++++++++++++++++++++++++------ fr/api/analytics/views.mdx | 31 +++ fr/api/analytics/visitors.mdx | 31 +++ zh/analytics.openapi.json | 474 ++++++++++++++++++++++++++++------ zh/api/analytics/views.mdx | 31 +++ zh/api/analytics/visitors.mdx | 31 +++ 14 files changed, 1720 insertions(+), 260 deletions(-) create mode 100644 api/analytics/views.mdx create mode 100644 api/analytics/visitors.mdx create mode 100644 es/api/analytics/views.mdx create mode 100644 es/api/analytics/visitors.mdx create mode 100644 fr/api/analytics/views.mdx create mode 100644 fr/api/analytics/visitors.mdx create mode 100644 zh/api/analytics/views.mdx create mode 100644 zh/api/analytics/visitors.mdx diff --git a/analytics.openapi.json b/analytics.openapi.json index 6240242e6..232939b1b 100644 --- a/analytics.openapi.json +++ b/analytics.openapi.json @@ -465,6 +465,122 @@ "totalSearches", "nextCursor" ] + }, + "ViewsTrafficTotals": { + "type": "object", + "properties": { + "human": { + "type": "number", + "description": "Site-wide content view events from human traffic." + }, + "ai": { + "type": "number", + "description": "Site-wide content view events from AI bot traffic." + }, + "total": { + "type": "number", + "description": "Site-wide content view events." + } + }, + "required": ["human", "ai", "total"] + }, + "ViewsByPageResponse": { + "type": "object", + "properties": { + "totals": { + "$ref": "#/components/schemas/ViewsTrafficTotals", + "description": "Site-wide view totals for the date range." + }, + "views": { + "type": "array", + "description": "Per-page view counts.", + "items": { + "type": "object", + "properties": { + "path": { + "type": "string", + "description": "The documentation page path." + }, + "human": { + "type": "number", + "description": "Content view events on this path from human traffic." + }, + "ai": { + "type": "number", + "description": "Content view events on this path from AI bot traffic." + }, + "total": { + "type": "number", + "description": "Total content view events on this path." + } + }, + "required": ["path", "human", "ai", "total"] + } + }, + "hasMore": { + "type": "boolean", + "description": "Whether additional results are available beyond this page." + } + }, + "required": ["totals", "views", "hasMore"] + }, + "VisitorsTrafficTotals": { + "type": "object", + "properties": { + "human": { + "type": "number", + "description": "Site-wide unique visitors from human traffic." + }, + "ai": { + "type": "number", + "description": "Site-wide unique visitors from AI bot traffic." + }, + "total": { + "type": "number", + "description": "Site-wide approximate distinct visitors with any qualifying view (deduplicated across human and AI)." + } + }, + "required": ["human", "ai", "total"] + }, + "VisitorsByPageResponse": { + "type": "object", + "properties": { + "totals": { + "$ref": "#/components/schemas/VisitorsTrafficTotals", + "description": "Site-wide unique visitor totals for the date range." + }, + "visitors": { + "type": "array", + "description": "Per-page visitor counts.", + "items": { + "type": "object", + "properties": { + "path": { + "type": "string", + "description": "The documentation page path." + }, + "human": { + "type": "number", + "description": "Unique visitors from human traffic." + }, + "ai": { + "type": "number", + "description": "Unique visitors from AI bot traffic." + }, + "total": { + "type": "number", + "description": "Approximate distinct visitors with any qualifying view on this path (deduplicated across human and AI)." + } + }, + "required": ["path", "human", "ai", "total"] + } + }, + "hasMore": { + "type": "boolean", + "description": "Whether additional results are available beyond this page." + } + }, + "required": ["totals", "visitors", "hasMore"] } }, "parameters": { @@ -882,6 +998,194 @@ } } } + }, + "/v1/analytics/{projectId}/views": { + "get": { + "summary": "Get page views", + "description": "Returns per-path and site-wide content view event counts, split by human and AI traffic.", + "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": "integer", + "minimum": 1, + "maximum": 250, + "default": 50, + "description": "Max results per page (1-250, default 50). Increment offset by limit while hasMore is true to paginate." + }, + "required": false, + "name": "limit", + "in": "query" + }, + { + "schema": { + "type": "integer", + "minimum": 0, + "default": 0, + "description": "Number of rows to skip. Use offset = (page - 1) * limit for page-based access." + }, + "required": false, + "name": "offset", + "in": "query" + } + ], + "responses": { + "200": { + "description": "Site-wide and per-path content view event counts", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ViewsByPageResponse" + } + } + } + }, + "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}/visitors": { + "get": { + "summary": "Get unique visitors", + "description": "Returns per-path and site-wide approximate distinct visitors by traffic type. The `total` field is deduplicated across human and AI (union of distinct visitor IDs with any qualifying content view).", + "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": "integer", + "minimum": 1, + "maximum": 250, + "default": 50, + "description": "Max results per page (1-250, default 50). Increment offset by limit while hasMore is true to paginate." + }, + "required": false, + "name": "limit", + "in": "query" + }, + { + "schema": { + "type": "integer", + "minimum": 0, + "default": 0, + "description": "Number of rows to skip. Use offset = (page - 1) * limit for page-based access." + }, + "required": false, + "name": "offset", + "in": "query" + } + ], + "responses": { + "200": { + "description": "Site-wide totals and per-path visitor counts", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/VisitorsByPageResponse" + } + } + } + }, + "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" + } + } + } + } + } + } } }, "webhooks": {} diff --git a/api/analytics/views.mdx b/api/analytics/views.mdx new file mode 100644 index 000000000..fc505b3f6 --- /dev/null +++ b/api/analytics/views.mdx @@ -0,0 +1,24 @@ +--- +title: "Get page views" +description: "Retrieve per-page and site-wide content view counts, split by human and AI traffic." +openapi: /analytics.openapi.json GET /v1/analytics/{projectId}/views +keywords: ["analytics", "views", "page views", "traffic", "export"] +--- + +## Usage + +Use this endpoint to export page view analytics. Results include both site-wide totals and per-page breakdowns, split by human and AI traffic. + +Paginate through results using offset-based pagination. Increment `offset` by `limit` while `hasMore` is true. + +## Filtering + +Filter view data by date range using `dateFrom` and `dateTo` parameters. + +## Response data + +The response includes a `totals` object with site-wide aggregates and a `views` array with per-page data. Each entry includes: +- **path**: The documentation page path +- **human**: Content view events from human traffic +- **ai**: Content view events from AI bot traffic +- **total**: Total content view events on this path diff --git a/api/analytics/visitors.mdx b/api/analytics/visitors.mdx new file mode 100644 index 000000000..c9a816b9a --- /dev/null +++ b/api/analytics/visitors.mdx @@ -0,0 +1,24 @@ +--- +title: "Get unique visitors" +description: "Retrieve per-page and site-wide approximate unique visitor counts, split by human and AI traffic." +openapi: /analytics.openapi.json GET /v1/analytics/{projectId}/visitors +keywords: ["analytics", "visitors", "unique visitors", "traffic", "export"] +--- + +## Usage + +Use this endpoint to export unique visitor analytics. Results include both site-wide totals and per-page breakdowns, split by human and AI traffic. The `total` field is deduplicated across human and AI traffic. + +Paginate through results using offset-based pagination. Increment `offset` by `limit` while `hasMore` is true. + +## Filtering + +Filter visitor data by date range using `dateFrom` and `dateTo` parameters. + +## Response data + +The response includes a `totals` object with site-wide aggregates and a `visitors` array with per-page data. Each entry includes: +- **path**: The documentation page path +- **human**: Unique visitors from human traffic +- **ai**: Unique visitors from AI bot traffic +- **total**: Approximate distinct visitors (deduplicated across human and AI) diff --git a/api/introduction.mdx b/api/introduction.mdx index 02f0de958..a520012ea 100644 --- a/api/introduction.mdx +++ b/api/introduction.mdx @@ -19,6 +19,8 @@ The Mintlify REST (Representational State Transfer) API enables you to programma - [Get feedback by page](/api/analytics/feedback-by-page): Export feedback counts aggregated by page. - [Get assistant conversations](/api/analytics/assistant-conversations): Export AI assistant conversation history. - [Get search queries](/api/analytics/searches): Export documentation search terms and analytics. +- [Get page views](/api/analytics/views): Export per-page and site-wide content view counts. +- [Get unique visitors](/api/analytics/visitors): Export per-page and site-wide unique visitor counts. ### Common use cases @@ -26,7 +28,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, assistant conversations, and search analytics for external analysis with [Get user feedback](/api/analytics/feedback), [Get feedback by page](/api/analytics/feedback-by-page), [Get assistant conversations](/api/analytics/assistant-conversations), and [Get search queries](/api/analytics/searches). +- **Analytics export**: Export feedback, assistant conversations, search analytics, page views, and visitor data for external analysis with [Get user feedback](/api/analytics/feedback), [Get feedback by page](/api/analytics/feedback-by-page), [Get assistant conversations](/api/analytics/assistant-conversations), [Get search queries](/api/analytics/searches), [Get page views](/api/analytics/views), and [Get unique visitors](/api/analytics/visitors). ## Authentication @@ -36,7 +38,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), [Get feedback by page](/api/analytics/feedback-by-page), [Get assistant conversations](/api/analytics/assistant-conversations), and [Get search queries](/api/analytics/searches). +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), [Get assistant conversations](/api/analytics/assistant-conversations), [Get search queries](/api/analytics/searches), [Get page views](/api/analytics/views), and [Get unique visitors](/api/analytics/visitors). Admin API keys begin with the `mint_` prefix. diff --git a/docs.json b/docs.json index e64ffaa4d..4f6d438f1 100644 --- a/docs.json +++ b/docs.json @@ -375,7 +375,9 @@ "api/analytics/feedback", "api/analytics/feedback-by-page", "api/analytics/assistant-conversations", - "api/analytics/searches" + "api/analytics/searches", + "api/analytics/views", + "api/analytics/visitors" ] } ] @@ -749,7 +751,9 @@ "fr/api/analytics/feedback", "fr/api/analytics/feedback-by-page", "fr/api/analytics/assistant-conversations", - "fr/api/analytics/searches" + "fr/api/analytics/searches", + "fr/api/analytics/views", + "fr/api/analytics/visitors" ] } ] @@ -1123,7 +1127,9 @@ "es/api/analytics/feedback", "es/api/analytics/feedback-by-page", "es/api/analytics/assistant-conversations", - "es/api/analytics/searches" + "es/api/analytics/searches", + "es/api/analytics/views", + "es/api/analytics/visitors" ] } ] @@ -1497,7 +1503,9 @@ "zh/api/analytics/feedback", "zh/api/analytics/feedback-by-page", "zh/api/analytics/assistant-conversations", - "zh/api/analytics/searches" + "zh/api/analytics/searches", + "zh/api/analytics/views", + "zh/api/analytics/visitors" ] } ] diff --git a/es/analytics.openapi.json b/es/analytics.openapi.json index 528326b95..232939b1b 100644 --- a/es/analytics.openapi.json +++ b/es/analytics.openapi.json @@ -3,12 +3,12 @@ "info": { "title": "Mintlify Analytics Export API", "version": "1.0.0", - "description": "API para exportar datos de Analytics de la documentación" + "description": "API for exporting documentation analytics data" }, "servers": [ { "url": "https://api.mintlify.com", - "description": "Producción" + "description": "Production" } ], "components": { @@ -16,20 +16,20 @@ "bearerAuth": { "type": "http", "scheme": "bearer", - "description": "El encabezado Authorization requiere un token Bearer. Usa una clave de API de administrador (con el prefijo `mint_`). Esta es una clave secreta del lado del servidor. Genérala en la [página de claves de API](https://dashboard.mintlify.com/settings/organization/api-keys) de tu dashboard." + "description": "The Authorization header expects a Bearer token. Use an admin API key (prefixed with `mint_`). This is a server-side secret key. Generate one on the [API keys page](https://dashboard.mintlify.com/settings/organization/api-keys) in your dashboard." } }, "schemas": { "projectId": { "type": "string", - "description": "Tu ID de proyecto. Puedes copiarlo desde la página [API keys](https://dashboard.mintlify.com/settings/organization/api-keys) en tu dashboard." + "description": "Your project ID. Can be copied from the [API keys](https://dashboard.mintlify.com/settings/organization/api-keys) page in your dashboard." }, "FeedbackResponse": { "type": "object", "properties": { "feedback": { "type": "array", - "description": "Lista de entradas de comentarios.", + "description": "List of feedback entries.", "items": { "anyOf": [ { @@ -37,25 +37,25 @@ "properties": { "id": { "type": "string", - "description": "Identificador único del comentario." + "description": "Unique feedback identifier." }, "path": { "type": "string", - "description": "La ruta o URL del documento de origen." + "description": "The path or URL to the source document." }, "comment": { "type": [ "string", "null" ], - "description": "Texto del comentario del usuario." + "description": "Text of the user's feedback comment." }, "createdAt": { "type": [ "string", "null" ], - "description": "Fecha y hora en la que se envió el comentario." + "description": "Timestamp when the feedback was submitted." }, "source": { "type": "string", @@ -63,7 +63,7 @@ "code_snippet", "contextual" ], - "description": "Origen del comentario. `code_snippet` indica un comentario sobre un bloque de código, `contextual` indica un comentario a nivel de página." + "description": "Where the feedback originated. `code_snippet` is feedback on a code block, `contextual` is page-level feedback." }, "status": { "type": "string", @@ -73,7 +73,7 @@ "resolved", "dismissed" ], - "description": "Estado de revisión actual del comentario." + "description": "Current review status of the feedback." } }, "required": [ @@ -90,25 +90,25 @@ "properties": { "id": { "type": "string", - "description": "Identificador único del comentario." + "description": "Unique feedback identifier." }, "path": { "type": "string", - "description": "La ruta o URL del documento de origen." + "description": "The path or URL to the source document." }, "comment": { "type": [ "string", "null" ], - "description": "Texto del comentario del usuario." + "description": "Text of the user's feedback comment." }, "createdAt": { "type": [ "string", "null" ], - "description": "Fecha y hora en la que se envió el comentario." + "description": "Timestamp when the feedback was submitted." }, "source": { "type": "string", @@ -116,7 +116,7 @@ "code_snippet", "contextual" ], - "description": "Origen del comentario. `code_snippet` indica un comentario sobre un bloque de código, `contextual` indica un comentario a nivel de página." + "description": "Where the feedback originated. `code_snippet` is feedback on a code block, `contextual` is page-level feedback." }, "status": { "type": "string", @@ -126,18 +126,18 @@ "resolved", "dismissed" ], - "description": "Estado actual de revisión del comentario." + "description": "Current review status of the feedback." }, "helpful": { "type": "boolean", - "description": "Indica si el usuario considera útil el contenido." + "description": "Whether the user found the content helpful." }, "contact": { "type": [ "string", "null" ], - "description": "Dirección de correo electrónico proporcionada por el usuario para el seguimiento." + "description": "Email address the user provided for follow-up." } }, "required": [ @@ -156,25 +156,25 @@ "properties": { "id": { "type": "string", - "description": "Identificador único del comentario." + "description": "Unique feedback identifier." }, "path": { "type": "string", - "description": "La ruta o URL del documento de origen." + "description": "The path or URL to the source document." }, "comment": { "type": [ "string", "null" ], - "description": "Texto del comentario del usuario." + "description": "Text of the user's feedback comment." }, "createdAt": { "type": [ "string", "null" ], - "description": "Marca de tiempo del envío del comentario." + "description": "Timestamp when the feedback was submitted." }, "source": { "type": "string", @@ -182,7 +182,7 @@ "code_snippet", "contextual" ], - "description": "Origen del comentario. `code_snippet` es un comentario sobre un bloque de código, `contextual` es un comentario a nivel de página." + "description": "Where the feedback originated. `code_snippet` is feedback on a code block, `contextual` is page-level feedback." }, "status": { "type": "string", @@ -192,25 +192,25 @@ "resolved", "dismissed" ], - "description": "Estado actual de revisión del comentario." + "description": "Current review status of the feedback." }, "code": { "type": "string", - "description": "Fragmento de código al que hace referencia el comentario." + "description": "The code snippet the feedback relates to." }, "filename": { "type": [ "string", "null" ], - "description": "Nombre de archivo asociado al fragmento de código." + "description": "Filename associated with the code snippet." }, "lang": { "type": [ "string", "null" ], - "description": "Lenguaje de programación del fragmento de código." + "description": "Programming language of the code snippet." } }, "required": [ @@ -233,11 +233,11 @@ "string", "null" ], - "description": "Cursor para recuperar la página siguiente de resultados. Nulo si no hay más resultados." + "description": "Cursor to retrieve the next page of results. Null if no more results." }, "hasMore": { "type": "boolean", - "description": "Indica si hay más resultados después de esta página." + "description": "Whether additional results are available beyond this page." } }, "required": [ @@ -251,17 +251,17 @@ "properties": { "error": { "type": "string", - "description": "Mensaje de error que describe lo que salió mal." + "description": "Error message describing what went wrong." }, "details": { "type": "array", - "description": "Detalles adicionales del error.", + "description": "Additional details about the error.", "items": { "type": "object", "properties": { "message": { "type": "string", - "description": "Descripción de un error específico de validación o procesamiento." + "description": "Description of a specific validation or processing error." } }, "required": [ @@ -279,39 +279,39 @@ "properties": { "conversations": { "type": "array", - "description": "Lista de conversaciones del assistant.", + "description": "List of assistant conversations.", "items": { "type": "object", "properties": { "id": { "type": "string", - "description": "Identificador único de la conversación." + "description": "Unique conversation identifier." }, "timestamp": { "type": "string", - "description": "Marca de tiempo en la que se produjo la conversación." + "description": "Timestamp when the conversation occurred." }, "query": { "type": "string", - "description": "La pregunta del usuario para el assistant." + "description": "The user's question to the assistant." }, "response": { "type": "string", - "description": "La respuesta del assistant." + "description": "The assistant's response." }, "sources": { "type": "array", - "description": "Páginas de la documentación mencionadas en la respuesta.", + "description": "Documentation pages referenced in the response.", "items": { "type": "object", "properties": { "title": { "type": "string", - "description": "Título de la página de documentación mencionada." + "description": "Title of the referenced documentation page." }, "url": { "type": "string", - "description": "URL de la página de documentación mencionada." + "description": "URL of the referenced documentation page." } }, "required": [ @@ -325,7 +325,7 @@ "string", "null" ], - "description": "Categoría de agrupación asignada automáticamente a la conversación, si corresponde." + "description": "Auto-assigned category grouping for the conversation, if applicable." } }, "required": [ @@ -343,11 +343,11 @@ "string", "null" ], - "description": "Cursor para obtener la siguiente página de resultados. Es nulo si no hay más resultados." + "description": "Cursor to retrieve the next page of results. Null if no more results." }, "hasMore": { "type": "boolean", - "description": "Indica si hay resultados adicionales más allá de esta página." + "description": "Whether additional results are available beyond this page." } }, "required": [ @@ -450,7 +450,7 @@ "totalSearches": { "type": "integer", "minimum": 0, - "description": "Total count of search events in the requested date range." + "description": "Total count of search events in the requested date range (sum of all hits, not distinct queries)." }, "nextCursor": { "type": [ @@ -465,6 +465,122 @@ "totalSearches", "nextCursor" ] + }, + "ViewsTrafficTotals": { + "type": "object", + "properties": { + "human": { + "type": "number", + "description": "Site-wide content view events from human traffic." + }, + "ai": { + "type": "number", + "description": "Site-wide content view events from AI bot traffic." + }, + "total": { + "type": "number", + "description": "Site-wide content view events." + } + }, + "required": ["human", "ai", "total"] + }, + "ViewsByPageResponse": { + "type": "object", + "properties": { + "totals": { + "$ref": "#/components/schemas/ViewsTrafficTotals", + "description": "Site-wide view totals for the date range." + }, + "views": { + "type": "array", + "description": "Per-page view counts.", + "items": { + "type": "object", + "properties": { + "path": { + "type": "string", + "description": "The documentation page path." + }, + "human": { + "type": "number", + "description": "Content view events on this path from human traffic." + }, + "ai": { + "type": "number", + "description": "Content view events on this path from AI bot traffic." + }, + "total": { + "type": "number", + "description": "Total content view events on this path." + } + }, + "required": ["path", "human", "ai", "total"] + } + }, + "hasMore": { + "type": "boolean", + "description": "Whether additional results are available beyond this page." + } + }, + "required": ["totals", "views", "hasMore"] + }, + "VisitorsTrafficTotals": { + "type": "object", + "properties": { + "human": { + "type": "number", + "description": "Site-wide unique visitors from human traffic." + }, + "ai": { + "type": "number", + "description": "Site-wide unique visitors from AI bot traffic." + }, + "total": { + "type": "number", + "description": "Site-wide approximate distinct visitors with any qualifying view (deduplicated across human and AI)." + } + }, + "required": ["human", "ai", "total"] + }, + "VisitorsByPageResponse": { + "type": "object", + "properties": { + "totals": { + "$ref": "#/components/schemas/VisitorsTrafficTotals", + "description": "Site-wide unique visitor totals for the date range." + }, + "visitors": { + "type": "array", + "description": "Per-page visitor counts.", + "items": { + "type": "object", + "properties": { + "path": { + "type": "string", + "description": "The documentation page path." + }, + "human": { + "type": "number", + "description": "Unique visitors from human traffic." + }, + "ai": { + "type": "number", + "description": "Unique visitors from AI bot traffic." + }, + "total": { + "type": "number", + "description": "Approximate distinct visitors with any qualifying view on this path (deduplicated across human and AI)." + } + }, + "required": ["path", "human", "ai", "total"] + } + }, + "hasMore": { + "type": "boolean", + "description": "Whether additional results are available beyond this page." + } + }, + "required": ["totals", "visitors", "hasMore"] } }, "parameters": { @@ -481,8 +597,8 @@ "paths": { "/v1/analytics/{projectId}/feedback": { "get": { - "summary": "Obtener comentarios de los usuarios", - "description": "Devuelve comentarios de usuarios con paginación y filtrado opcional", + "summary": "Get user feedback", + "description": "Returns paginated user feedback with optional filtering", "tags": [ "Analytics" ], @@ -498,7 +614,7 @@ { "schema": { "type": "string", - "description": "Fecha en formato ISO 8601 o AAAA-MM-DD", + "description": "Date in ISO 8601 or YYYY-MM-DD format", "example": "2024-01-01" }, "required": false, @@ -508,7 +624,7 @@ { "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.", + "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, @@ -522,7 +638,7 @@ "code_snippet", "contextual" ], - "description": "Filtrar por el origen de los comentarios" + "description": "Filter by feedback source" }, "required": false, "name": "source", @@ -531,7 +647,7 @@ { "schema": { "type": "string", - "description": "Lista de estados separados por comas por los que filtrar" + "description": "Comma-separated list of statuses to filter by" }, "required": false, "name": "status", @@ -543,7 +659,7 @@ "minimum": 1, "maximum": 100, "default": 50, - "description": "Número máximo de resultados por página" + "description": "Max results per page" }, "required": false, "name": "limit", @@ -552,7 +668,7 @@ { "schema": { "type": "string", - "description": "Cursor de paginación" + "description": "Pagination cursor" }, "required": false, "name": "cursor", @@ -561,7 +677,7 @@ ], "responses": { "200": { - "description": "Datos de comentarios paginados", + "description": "Feedback data with pagination", "content": { "application/json": { "schema": { @@ -571,7 +687,7 @@ } }, "400": { - "description": "Parámetros de búsqueda no válidos", + "description": "Invalid query parameters", "content": { "application/json": { "schema": { @@ -581,7 +697,7 @@ } }, "500": { - "description": "Error del servidor", + "description": "Server error", "content": { "application/json": { "schema": { @@ -595,8 +711,8 @@ }, "/v1/analytics/{projectId}/feedback/by-page": { "get": { - "summary": "Obtener comentarios por pagina", - "description": "Devuelve comentarios agregados por ruta de pagina", + "summary": "Get feedback by page", + "description": "Returns feedback counts aggregated by documentation page path (thumbs up/down for contextual feedback, code snippet count, and total per page)", "tags": [ "Analytics" ], @@ -612,7 +728,7 @@ { "schema": { "type": "string", - "description": "Fecha en formato ISO 8601 o AAAA-MM-DD", + "description": "Date in ISO 8601 or YYYY-MM-DD format", "example": "2024-01-01" }, "required": false, @@ -622,7 +738,7 @@ { "schema": { "type": "string", - "description": "Limite superior exclusivo", + "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, @@ -635,7 +751,7 @@ "minimum": 1, "maximum": 100, "default": 10, - "description": "Numero maximo de resultados por pagina" + "description": "Max results per page" }, "required": false, "name": "limit", @@ -648,7 +764,7 @@ "code_snippet", "contextual" ], - "description": "Filtrar por origen de los comentarios" + "description": "Filter by feedback source" }, "required": false, "name": "source", @@ -657,7 +773,7 @@ { "schema": { "type": "string", - "description": "Estados separados por comas" + "description": "Comma-separated list of statuses to filter by" }, "required": false, "name": "status", @@ -666,7 +782,7 @@ ], "responses": { "200": { - "description": "Comentarios agregados por pagina", + "description": "Per-page feedback aggregates with pagination flag", "content": { "application/json": { "schema": { @@ -676,7 +792,7 @@ } }, "400": { - "description": "Parametros no validos", + "description": "Invalid query parameters", "content": { "application/json": { "schema": { @@ -686,7 +802,7 @@ } }, "500": { - "description": "Error del servidor", + "description": "Server error", "content": { "application/json": { "schema": { @@ -700,8 +816,8 @@ }, "/v1/analytics/{projectId}/assistant": { "get": { - "summary": "Obtener conversaciones del assistant", - "description": "Devuelve el historial paginado de conversaciones del Asistente de IA", + "summary": "Get assistant conversations", + "description": "Returns paginated AI assistant conversation history", "tags": [ "Analytics" ], @@ -717,7 +833,7 @@ { "schema": { "type": "string", - "description": "Fecha en formato ISO 8601 o AAAA-MM-DD", + "description": "Date in ISO 8601 or YYYY-MM-DD format", "example": "2024-01-01" }, "required": false, @@ -727,7 +843,7 @@ { "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.", + "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, @@ -740,7 +856,7 @@ "minimum": 1, "maximum": 1000, "default": 100, - "description": "Número máximo de resultados por página" + "description": "Max results per page" }, "required": false, "name": "limit", @@ -750,7 +866,7 @@ "schema": { "type": "string", "format": "ulid", - "description": "Cursor de paginación (formato ULID)" + "description": "Pagination cursor (ULID format)" }, "required": false, "name": "cursor", @@ -759,7 +875,7 @@ ], "responses": { "200": { - "description": "Datos de conversación paginados", + "description": "Conversation data with pagination", "content": { "application/json": { "schema": { @@ -769,7 +885,7 @@ } }, "400": { - "description": "Parámetros de búsqueda no válidos", + "description": "Invalid query parameters", "content": { "application/json": { "schema": { @@ -779,7 +895,7 @@ } }, "500": { - "description": "Error del servidor", + "description": "Server error", "content": { "application/json": { "schema": { @@ -793,8 +909,8 @@ }, "/v1/analytics/{projectId}/searches": { "get": { - "summary": "Obtener consultas de busqueda", - "description": "Devuelve terminos de busqueda paginados ordenados por numero de busquedas", + "summary": "Get search queries", + "description": "Returns paginated documentation search terms for the date range, ordered by hit count descending. Each row includes click-through rate, the most-clicked result path for that query (if any), and the last time the term was searched. `totalSearches` is the total number of search query events in the same date range (sum of all hits, not distinct queries).", "tags": [ "Analytics" ], @@ -810,7 +926,7 @@ { "schema": { "type": "string", - "description": "Fecha en formato ISO 8601 o AAAA-MM-DD", + "description": "Date in ISO 8601 or YYYY-MM-DD format", "example": "2024-01-01" }, "required": false, @@ -820,7 +936,7 @@ { "schema": { "type": "string", - "description": "Limite superior exclusivo", + "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, @@ -833,7 +949,7 @@ "minimum": 1, "maximum": 100, "default": 50, - "description": "Numero maximo de terminos por pagina" + "description": "Max search terms per page (ordered by hit count descending)" }, "required": false, "name": "limit", @@ -842,7 +958,7 @@ { "schema": { "type": "string", - "description": "Cursor de paginacion opaco" + "description": "Opaque pagination cursor from the previous response" }, "required": false, "name": "cursor", @@ -851,7 +967,7 @@ ], "responses": { "200": { - "description": "Terminos de busqueda agregados", + "description": "Search term aggregates with pagination", "content": { "application/json": { "schema": { @@ -861,7 +977,195 @@ } }, "400": { - "description": "Parametros no validos", + "description": "Invalid query parameters or cursor", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AnalyticsErrorResponse" + } + } + } + }, + "500": { + "description": "Server error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AnalyticsErrorResponse" + } + } + } + } + } + } + }, + "/v1/analytics/{projectId}/views": { + "get": { + "summary": "Get page views", + "description": "Returns per-path and site-wide content view event counts, split by human and AI traffic.", + "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": "integer", + "minimum": 1, + "maximum": 250, + "default": 50, + "description": "Max results per page (1-250, default 50). Increment offset by limit while hasMore is true to paginate." + }, + "required": false, + "name": "limit", + "in": "query" + }, + { + "schema": { + "type": "integer", + "minimum": 0, + "default": 0, + "description": "Number of rows to skip. Use offset = (page - 1) * limit for page-based access." + }, + "required": false, + "name": "offset", + "in": "query" + } + ], + "responses": { + "200": { + "description": "Site-wide and per-path content view event counts", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ViewsByPageResponse" + } + } + } + }, + "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}/visitors": { + "get": { + "summary": "Get unique visitors", + "description": "Returns per-path and site-wide approximate distinct visitors by traffic type. The `total` field is deduplicated across human and AI (union of distinct visitor IDs with any qualifying content view).", + "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": "integer", + "minimum": 1, + "maximum": 250, + "default": 50, + "description": "Max results per page (1-250, default 50). Increment offset by limit while hasMore is true to paginate." + }, + "required": false, + "name": "limit", + "in": "query" + }, + { + "schema": { + "type": "integer", + "minimum": 0, + "default": 0, + "description": "Number of rows to skip. Use offset = (page - 1) * limit for page-based access." + }, + "required": false, + "name": "offset", + "in": "query" + } + ], + "responses": { + "200": { + "description": "Site-wide totals and per-path visitor counts", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/VisitorsByPageResponse" + } + } + } + }, + "400": { + "description": "Invalid query parameters", "content": { "application/json": { "schema": { @@ -871,7 +1175,7 @@ } }, "500": { - "description": "Error del servidor", + "description": "Server error", "content": { "application/json": { "schema": { @@ -885,4 +1189,4 @@ } }, "webhooks": {} -} +} \ No newline at end of file diff --git a/es/api/analytics/views.mdx b/es/api/analytics/views.mdx new file mode 100644 index 000000000..764c89d1c --- /dev/null +++ b/es/api/analytics/views.mdx @@ -0,0 +1,31 @@ +--- +title: "Obtener vistas de páginas" +description: "Obtén los conteos de vistas de contenido por página y a nivel del sitio, divididos entre tráfico humano e IA." +openapi: /es/analytics.openapi.json GET /v1/analytics/{projectId}/views +keywords: ["analytics", "vistas", "vistas de página", "tráfico", "exportación"] +--- + +
+ ## Uso +
+ +Usa este endpoint para exportar los datos analíticos de vistas de páginas. Los resultados incluyen totales a nivel del sitio y desgloses por página, divididos entre tráfico humano e IA. + +Pagina los resultados usando paginación basada en offset. Incrementa `offset` por `limit` mientras `hasMore` sea true. + +
+ ## Filtrado +
+ +Filtra los datos de vistas por rango de fechas usando los parámetros `dateFrom` y `dateTo`. + +
+ ## Datos de respuesta +
+ +La respuesta incluye un objeto `totals` con agregados a nivel del sitio y un arreglo `views` con datos por página. Cada entrada incluye: + +- **path**: La ruta de la página de documentación +- **human**: Eventos de vista de contenido del tráfico humano +- **ai**: Eventos de vista de contenido del tráfico IA +- **total**: Total de eventos de vista de contenido en esta página diff --git a/es/api/analytics/visitors.mdx b/es/api/analytics/visitors.mdx new file mode 100644 index 000000000..4567235d7 --- /dev/null +++ b/es/api/analytics/visitors.mdx @@ -0,0 +1,31 @@ +--- +title: "Obtener visitantes únicos" +description: "Obtén los conteos aproximados de visitantes únicos por página y a nivel del sitio, divididos entre tráfico humano e IA." +openapi: /es/analytics.openapi.json GET /v1/analytics/{projectId}/visitors +keywords: ["analytics", "visitantes", "visitantes únicos", "tráfico", "exportación"] +--- + +
+ ## Uso +
+ +Usa este endpoint para exportar los datos analíticos de visitantes únicos. Los resultados incluyen totales a nivel del sitio y desgloses por página, divididos entre tráfico humano e IA. El campo `total` está deduplicado entre tráfico humano e IA. + +Pagina los resultados usando paginación basada en offset. Incrementa `offset` por `limit` mientras `hasMore` sea true. + +
+ ## Filtrado +
+ +Filtra los datos de visitantes por rango de fechas usando los parámetros `dateFrom` y `dateTo`. + +
+ ## Datos de respuesta +
+ +La respuesta incluye un objeto `totals` con agregados a nivel del sitio y un arreglo `visitors` con datos por página. Cada entrada incluye: + +- **path**: La ruta de la página de documentación +- **human**: Visitantes únicos del tráfico humano +- **ai**: Visitantes únicos del tráfico IA +- **total**: Visitantes distintos aproximados (deduplicados entre humano e IA) diff --git a/fr/analytics.openapi.json b/fr/analytics.openapi.json index 58b955a19..232939b1b 100644 --- a/fr/analytics.openapi.json +++ b/fr/analytics.openapi.json @@ -3,7 +3,7 @@ "info": { "title": "Mintlify Analytics Export API", "version": "1.0.0", - "description": "API d’exportation des données Analytics de la documentation" + "description": "API for exporting documentation analytics data" }, "servers": [ { @@ -16,20 +16,20 @@ "bearerAuth": { "type": "http", "scheme": "bearer", - "description": "L’en-tête Authorization requiert un jeton Bearer. Utilisez une clé d’API administrateur (préfixée par `mint_`). Il s’agit d’une clé secrète côté serveur. Générez-en une depuis la [page API keys](https://dashboard.mintlify.com/settings/organization/api-keys) dans votre Dashboard." + "description": "The Authorization header expects a Bearer token. Use an admin API key (prefixed with `mint_`). This is a server-side secret key. Generate one on the [API keys page](https://dashboard.mintlify.com/settings/organization/api-keys) in your 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." + "description": "Your project ID. Can be copied from the [API keys](https://dashboard.mintlify.com/settings/organization/api-keys) page in your dashboard." }, "FeedbackResponse": { "type": "object", "properties": { "feedback": { "type": "array", - "description": "Liste des retours.", + "description": "List of feedback entries.", "items": { "anyOf": [ { @@ -37,25 +37,25 @@ "properties": { "id": { "type": "string", - "description": "Identifiant unique du retour." + "description": "Unique feedback identifier." }, "path": { "type": "string", - "description": "Le chemin ou l’URL du document source." + "description": "The path or URL to the source document." }, "comment": { "type": [ "string", "null" ], - "description": "Texte du commentaire de l’utilisateur." + "description": "Text of the user's feedback comment." }, "createdAt": { "type": [ "string", "null" ], - "description": "Horodatage de l’envoi du retour." + "description": "Timestamp when the feedback was submitted." }, "source": { "type": "string", @@ -63,7 +63,7 @@ "code_snippet", "contextual" ], - "description": "Source du retour. `code_snippet` correspond à un retour sur un code block, `contextual` à un retour au niveau de la page." + "description": "Where the feedback originated. `code_snippet` is feedback on a code block, `contextual` is page-level feedback." }, "status": { "type": "string", @@ -73,7 +73,7 @@ "resolved", "dismissed" ], - "description": "Statut actuel de révision du retour." + "description": "Current review status of the feedback." } }, "required": [ @@ -90,25 +90,25 @@ "properties": { "id": { "type": "string", - "description": "Identifiant unique du retour." + "description": "Unique feedback identifier." }, "path": { "type": "string", - "description": "Chemin ou URL du document source." + "description": "The path or URL to the source document." }, "comment": { "type": [ "string", "null" ], - "description": "Texte du commentaire de l’utilisateur." + "description": "Text of the user's feedback comment." }, "createdAt": { "type": [ "string", "null" ], - "description": "Horodatage de l’envoi du retour." + "description": "Timestamp when the feedback was submitted." }, "source": { "type": "string", @@ -116,7 +116,7 @@ "code_snippet", "contextual" ], - "description": "Source du retour. `code_snippet` correspond à un retour sur un code block, `contextual` à un retour au niveau de la page." + "description": "Where the feedback originated. `code_snippet` is feedback on a code block, `contextual` is page-level feedback." }, "status": { "type": "string", @@ -126,18 +126,18 @@ "resolved", "dismissed" ], - "description": "Statut actuel d’examen du retour." + "description": "Current review status of the feedback." }, "helpful": { "type": "boolean", - "description": "Indique si l’utilisateur a jugé le contenu utile." + "description": "Whether the user found the content helpful." }, "contact": { "type": [ "string", "null" ], - "description": "Adresse e-mail fournie par l’utilisateur pour le suivi." + "description": "Email address the user provided for follow-up." } }, "required": [ @@ -156,25 +156,25 @@ "properties": { "id": { "type": "string", - "description": "Identifiant unique du retour." + "description": "Unique feedback identifier." }, "path": { "type": "string", - "description": "Chemin ou URL du document source." + "description": "The path or URL to the source document." }, "comment": { "type": [ "string", "null" ], - "description": "Texte du commentaire de l’utilisateur." + "description": "Text of the user's feedback comment." }, "createdAt": { "type": [ "string", "null" ], - "description": "Horodatage de l’envoi du retour." + "description": "Timestamp when the feedback was submitted." }, "source": { "type": "string", @@ -182,7 +182,7 @@ "code_snippet", "contextual" ], - "description": "Origine du retour. `code_snippet` correspond à un retour sur un code block, `contextual` à un retour concernant la page entière." + "description": "Where the feedback originated. `code_snippet` is feedback on a code block, `contextual` is page-level feedback." }, "status": { "type": "string", @@ -192,25 +192,25 @@ "resolved", "dismissed" ], - "description": "Statut actuel d’examen du retour." + "description": "Current review status of the feedback." }, "code": { "type": "string", - "description": "Extrait de code auquel le retour se rapporte." + "description": "The code snippet the feedback relates to." }, "filename": { "type": [ "string", "null" ], - "description": "Nom de fichier associé à l’extrait de code." + "description": "Filename associated with the code snippet." }, "lang": { "type": [ "string", "null" ], - "description": "Langage de programmation de l’extrait de code." + "description": "Programming language of the code snippet." } }, "required": [ @@ -233,11 +233,11 @@ "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." + "description": "Cursor to retrieve the next page of results. Null if no more results." }, "hasMore": { "type": "boolean", - "description": "Indique si des résultats supplémentaires sont disponibles au-delà de cette page." + "description": "Whether additional results are available beyond this page." } }, "required": [ @@ -251,17 +251,17 @@ "properties": { "error": { "type": "string", - "description": "Message d’erreur décrivant ce qui s’est mal passé." + "description": "Error message describing what went wrong." }, "details": { "type": "array", - "description": "Détails supplémentaires sur l’erreur.", + "description": "Additional details about the error.", "items": { "type": "object", "properties": { "message": { "type": "string", - "description": "Description d’une erreur spécifique de validation ou de traitement." + "description": "Description of a specific validation or processing error." } }, "required": [ @@ -279,39 +279,39 @@ "properties": { "conversations": { "type": "array", - "description": "Liste des conversations de l’Assistant.", + "description": "List of assistant conversations.", "items": { "type": "object", "properties": { "id": { "type": "string", - "description": "Identifiant unique de la conversation." + "description": "Unique conversation identifier." }, "timestamp": { "type": "string", - "description": "Horodatage de la conversation." + "description": "Timestamp when the conversation occurred." }, "query": { "type": "string", - "description": "La question de l’utilisateur adressée à l’Assistant." + "description": "The user's question to the assistant." }, "response": { "type": "string", - "description": "La réponse générée par l’Assistant." + "description": "The assistant's response." }, "sources": { "type": "array", - "description": "Pages de documentation référencées dans la réponse.", + "description": "Documentation pages referenced in the response.", "items": { "type": "object", "properties": { "title": { "type": "string", - "description": "Titre de la page de documentation référencée." + "description": "Title of the referenced documentation page." }, "url": { "type": "string", - "description": "URL de la page de documentation référencée." + "description": "URL of the referenced documentation page." } }, "required": [ @@ -325,7 +325,7 @@ "string", "null" ], - "description": "Catégorie de regroupement automatiquement attribuée à la conversation, le cas échéant." + "description": "Auto-assigned category grouping for the conversation, if applicable." } }, "required": [ @@ -343,11 +343,11 @@ "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." + "description": "Cursor to retrieve the next page of results. Null if no more results." }, "hasMore": { "type": "boolean", - "description": "Indique si des résultats supplémentaires sont disponibles au‑delà de cette page." + "description": "Whether additional results are available beyond this page." } }, "required": [ @@ -450,7 +450,7 @@ "totalSearches": { "type": "integer", "minimum": 0, - "description": "Total count of search events in the requested date range." + "description": "Total count of search events in the requested date range (sum of all hits, not distinct queries)." }, "nextCursor": { "type": [ @@ -465,6 +465,122 @@ "totalSearches", "nextCursor" ] + }, + "ViewsTrafficTotals": { + "type": "object", + "properties": { + "human": { + "type": "number", + "description": "Site-wide content view events from human traffic." + }, + "ai": { + "type": "number", + "description": "Site-wide content view events from AI bot traffic." + }, + "total": { + "type": "number", + "description": "Site-wide content view events." + } + }, + "required": ["human", "ai", "total"] + }, + "ViewsByPageResponse": { + "type": "object", + "properties": { + "totals": { + "$ref": "#/components/schemas/ViewsTrafficTotals", + "description": "Site-wide view totals for the date range." + }, + "views": { + "type": "array", + "description": "Per-page view counts.", + "items": { + "type": "object", + "properties": { + "path": { + "type": "string", + "description": "The documentation page path." + }, + "human": { + "type": "number", + "description": "Content view events on this path from human traffic." + }, + "ai": { + "type": "number", + "description": "Content view events on this path from AI bot traffic." + }, + "total": { + "type": "number", + "description": "Total content view events on this path." + } + }, + "required": ["path", "human", "ai", "total"] + } + }, + "hasMore": { + "type": "boolean", + "description": "Whether additional results are available beyond this page." + } + }, + "required": ["totals", "views", "hasMore"] + }, + "VisitorsTrafficTotals": { + "type": "object", + "properties": { + "human": { + "type": "number", + "description": "Site-wide unique visitors from human traffic." + }, + "ai": { + "type": "number", + "description": "Site-wide unique visitors from AI bot traffic." + }, + "total": { + "type": "number", + "description": "Site-wide approximate distinct visitors with any qualifying view (deduplicated across human and AI)." + } + }, + "required": ["human", "ai", "total"] + }, + "VisitorsByPageResponse": { + "type": "object", + "properties": { + "totals": { + "$ref": "#/components/schemas/VisitorsTrafficTotals", + "description": "Site-wide unique visitor totals for the date range." + }, + "visitors": { + "type": "array", + "description": "Per-page visitor counts.", + "items": { + "type": "object", + "properties": { + "path": { + "type": "string", + "description": "The documentation page path." + }, + "human": { + "type": "number", + "description": "Unique visitors from human traffic." + }, + "ai": { + "type": "number", + "description": "Unique visitors from AI bot traffic." + }, + "total": { + "type": "number", + "description": "Approximate distinct visitors with any qualifying view on this path (deduplicated across human and AI)." + } + }, + "required": ["path", "human", "ai", "total"] + } + }, + "hasMore": { + "type": "boolean", + "description": "Whether additional results are available beyond this page." + } + }, + "required": ["totals", "visitors", "hasMore"] } }, "parameters": { @@ -481,8 +597,8 @@ "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", + "summary": "Get user feedback", + "description": "Returns paginated user feedback with optional filtering", "tags": [ "Analytics" ], @@ -498,7 +614,7 @@ { "schema": { "type": "string", - "description": "Date au format ISO 8601 ou AAAA-MM-JJ", + "description": "Date in ISO 8601 or YYYY-MM-DD format", "example": "2024-01-01" }, "required": false, @@ -508,7 +624,7 @@ { "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.", + "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, @@ -522,7 +638,7 @@ "code_snippet", "contextual" ], - "description": "Filtrer par source des retours utilisateurs" + "description": "Filter by feedback source" }, "required": false, "name": "source", @@ -531,7 +647,7 @@ { "schema": { "type": "string", - "description": "Liste de statuts séparés par des virgules pour le filtrage" + "description": "Comma-separated list of statuses to filter by" }, "required": false, "name": "status", @@ -543,7 +659,7 @@ "minimum": 1, "maximum": 100, "default": 50, - "description": "Nombre maximal de résultats par page" + "description": "Max results per page" }, "required": false, "name": "limit", @@ -552,7 +668,7 @@ { "schema": { "type": "string", - "description": "Curseur de pagination" + "description": "Pagination cursor" }, "required": false, "name": "cursor", @@ -561,7 +677,7 @@ ], "responses": { "200": { - "description": "Données de retours utilisateurs paginées", + "description": "Feedback data with pagination", "content": { "application/json": { "schema": { @@ -571,7 +687,7 @@ } }, "400": { - "description": "Paramètres de requête invalides", + "description": "Invalid query parameters", "content": { "application/json": { "schema": { @@ -581,7 +697,7 @@ } }, "500": { - "description": "Erreur serveur", + "description": "Server error", "content": { "application/json": { "schema": { @@ -595,8 +711,8 @@ }, "/v1/analytics/{projectId}/feedback/by-page": { "get": { - "summary": "Obtenir les retours par page", - "description": "Renvoie les comptages de retours par chemin de page", + "summary": "Get feedback by page", + "description": "Returns feedback counts aggregated by documentation page path (thumbs up/down for contextual feedback, code snippet count, and total per page)", "tags": [ "Analytics" ], @@ -612,7 +728,7 @@ { "schema": { "type": "string", - "description": "Date au format ISO 8601 ou AAAA-MM-JJ", + "description": "Date in ISO 8601 or YYYY-MM-DD format", "example": "2024-01-01" }, "required": false, @@ -622,7 +738,7 @@ { "schema": { "type": "string", - "description": "Borne superieure exclusive", + "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, @@ -635,7 +751,7 @@ "minimum": 1, "maximum": 100, "default": 10, - "description": "Nombre maximal de resultats par page" + "description": "Max results per page" }, "required": false, "name": "limit", @@ -648,7 +764,7 @@ "code_snippet", "contextual" ], - "description": "Filtrer par source des retours" + "description": "Filter by feedback source" }, "required": false, "name": "source", @@ -657,7 +773,7 @@ { "schema": { "type": "string", - "description": "Statuts separes par des virgules" + "description": "Comma-separated list of statuses to filter by" }, "required": false, "name": "status", @@ -666,7 +782,7 @@ ], "responses": { "200": { - "description": "Agregats de retours par page", + "description": "Per-page feedback aggregates with pagination flag", "content": { "application/json": { "schema": { @@ -676,7 +792,7 @@ } }, "400": { - "description": "Parametres de requete invalides", + "description": "Invalid query parameters", "content": { "application/json": { "schema": { @@ -686,7 +802,7 @@ } }, "500": { - "description": "Erreur serveur", + "description": "Server error", "content": { "application/json": { "schema": { @@ -700,8 +816,8 @@ }, "/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", + "summary": "Get assistant conversations", + "description": "Returns paginated AI assistant conversation history", "tags": [ "Analytics" ], @@ -717,7 +833,7 @@ { "schema": { "type": "string", - "description": "Date au format ISO 8601 ou AAAA-MM-JJ", + "description": "Date in ISO 8601 or YYYY-MM-DD format", "example": "2024-01-01" }, "required": false, @@ -727,7 +843,7 @@ { "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.", + "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, @@ -740,7 +856,7 @@ "minimum": 1, "maximum": 1000, "default": 100, - "description": "Nombre maximal de résultats par page" + "description": "Max results per page" }, "required": false, "name": "limit", @@ -750,7 +866,7 @@ "schema": { "type": "string", "format": "ulid", - "description": "Curseur de pagination (format ULID)" + "description": "Pagination cursor (ULID format)" }, "required": false, "name": "cursor", @@ -759,7 +875,7 @@ ], "responses": { "200": { - "description": "Données de conversation paginées", + "description": "Conversation data with pagination", "content": { "application/json": { "schema": { @@ -769,7 +885,7 @@ } }, "400": { - "description": "Paramètres de requête invalides", + "description": "Invalid query parameters", "content": { "application/json": { "schema": { @@ -779,7 +895,7 @@ } }, "500": { - "description": "Erreur serveur", + "description": "Server error", "content": { "application/json": { "schema": { @@ -793,8 +909,8 @@ }, "/v1/analytics/{projectId}/searches": { "get": { - "summary": "Obtenir les requetes de recherche", - "description": "Renvoie les termes de recherche pagines classes par nombre de requetes", + "summary": "Get search queries", + "description": "Returns paginated documentation search terms for the date range, ordered by hit count descending. Each row includes click-through rate, the most-clicked result path for that query (if any), and the last time the term was searched. `totalSearches` is the total number of search query events in the same date range (sum of all hits, not distinct queries).", "tags": [ "Analytics" ], @@ -810,7 +926,7 @@ { "schema": { "type": "string", - "description": "Date au format ISO 8601 ou AAAA-MM-JJ", + "description": "Date in ISO 8601 or YYYY-MM-DD format", "example": "2024-01-01" }, "required": false, @@ -820,7 +936,7 @@ { "schema": { "type": "string", - "description": "Borne superieure exclusive", + "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, @@ -833,7 +949,7 @@ "minimum": 1, "maximum": 100, "default": 50, - "description": "Nombre maximal de termes par page" + "description": "Max search terms per page (ordered by hit count descending)" }, "required": false, "name": "limit", @@ -842,7 +958,7 @@ { "schema": { "type": "string", - "description": "Curseur de pagination opaque" + "description": "Opaque pagination cursor from the previous response" }, "required": false, "name": "cursor", @@ -851,7 +967,7 @@ ], "responses": { "200": { - "description": "Agregats de termes de recherche", + "description": "Search term aggregates with pagination", "content": { "application/json": { "schema": { @@ -861,7 +977,195 @@ } }, "400": { - "description": "Parametres invalides", + "description": "Invalid query parameters or cursor", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AnalyticsErrorResponse" + } + } + } + }, + "500": { + "description": "Server error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AnalyticsErrorResponse" + } + } + } + } + } + } + }, + "/v1/analytics/{projectId}/views": { + "get": { + "summary": "Get page views", + "description": "Returns per-path and site-wide content view event counts, split by human and AI traffic.", + "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": "integer", + "minimum": 1, + "maximum": 250, + "default": 50, + "description": "Max results per page (1-250, default 50). Increment offset by limit while hasMore is true to paginate." + }, + "required": false, + "name": "limit", + "in": "query" + }, + { + "schema": { + "type": "integer", + "minimum": 0, + "default": 0, + "description": "Number of rows to skip. Use offset = (page - 1) * limit for page-based access." + }, + "required": false, + "name": "offset", + "in": "query" + } + ], + "responses": { + "200": { + "description": "Site-wide and per-path content view event counts", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ViewsByPageResponse" + } + } + } + }, + "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}/visitors": { + "get": { + "summary": "Get unique visitors", + "description": "Returns per-path and site-wide approximate distinct visitors by traffic type. The `total` field is deduplicated across human and AI (union of distinct visitor IDs with any qualifying content view).", + "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": "integer", + "minimum": 1, + "maximum": 250, + "default": 50, + "description": "Max results per page (1-250, default 50). Increment offset by limit while hasMore is true to paginate." + }, + "required": false, + "name": "limit", + "in": "query" + }, + { + "schema": { + "type": "integer", + "minimum": 0, + "default": 0, + "description": "Number of rows to skip. Use offset = (page - 1) * limit for page-based access." + }, + "required": false, + "name": "offset", + "in": "query" + } + ], + "responses": { + "200": { + "description": "Site-wide totals and per-path visitor counts", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/VisitorsByPageResponse" + } + } + } + }, + "400": { + "description": "Invalid query parameters", "content": { "application/json": { "schema": { @@ -871,7 +1175,7 @@ } }, "500": { - "description": "Erreur serveur", + "description": "Server error", "content": { "application/json": { "schema": { @@ -885,4 +1189,4 @@ } }, "webhooks": {} -} +} \ No newline at end of file diff --git a/fr/api/analytics/views.mdx b/fr/api/analytics/views.mdx new file mode 100644 index 000000000..d32360ba2 --- /dev/null +++ b/fr/api/analytics/views.mdx @@ -0,0 +1,31 @@ +--- +title: "Obtenir les vues de pages" +description: "Récupérez les compteurs de vues de contenu par page et à l'échelle du site, répartis entre trafic humain et IA." +openapi: /fr/analytics.openapi.json GET /v1/analytics/{projectId}/views +keywords: ["analytics", "vues", "pages vues", "trafic", "export"] +--- + +
+ ## Utilisation +
+ +Utilisez cet endpoint pour exporter les données analytiques de vues de pages. Les résultats incluent les totaux à l'échelle du site et les détails par page, répartis entre trafic humain et IA. + +Parcourez les résultats avec une pagination basée sur l'offset. Incrémentez `offset` de `limit` tant que `hasMore` est true. + +
+ ## Filtrage +
+ +Filtrez les données de vues par plage de dates à l'aide des paramètres `dateFrom` et `dateTo`. + +
+ ## Données de la réponse +
+ +La réponse inclut un objet `totals` avec les agrégats à l'échelle du site et un tableau `views` avec les données par page. Chaque entrée inclut : + +- **path** : le chemin de la page de documentation +- **human** : événements de vue de contenu provenant du trafic humain +- **ai** : événements de vue de contenu provenant du trafic IA +- **total** : total des événements de vue de contenu sur cette page diff --git a/fr/api/analytics/visitors.mdx b/fr/api/analytics/visitors.mdx new file mode 100644 index 000000000..4b7c6abb9 --- /dev/null +++ b/fr/api/analytics/visitors.mdx @@ -0,0 +1,31 @@ +--- +title: "Obtenir les visiteurs uniques" +description: "Récupérez les compteurs approximatifs de visiteurs uniques par page et à l'échelle du site, répartis entre trafic humain et IA." +openapi: /fr/analytics.openapi.json GET /v1/analytics/{projectId}/visitors +keywords: ["analytics", "visiteurs", "visiteurs uniques", "trafic", "export"] +--- + +
+ ## Utilisation +
+ +Utilisez cet endpoint pour exporter les données analytiques de visiteurs uniques. Les résultats incluent les totaux à l'échelle du site et les détails par page, répartis entre trafic humain et IA. Le champ `total` est dédupliqué entre le trafic humain et IA. + +Parcourez les résultats avec une pagination basée sur l'offset. Incrémentez `offset` de `limit` tant que `hasMore` est true. + +
+ ## Filtrage +
+ +Filtrez les données de visiteurs par plage de dates à l'aide des paramètres `dateFrom` et `dateTo`. + +
+ ## Données de la réponse +
+ +La réponse inclut un objet `totals` avec les agrégats à l'échelle du site et un tableau `visitors` avec les données par page. Chaque entrée inclut : + +- **path** : le chemin de la page de documentation +- **human** : visiteurs uniques provenant du trafic humain +- **ai** : visiteurs uniques provenant du trafic IA +- **total** : visiteurs distincts approximatifs (dédupliqués entre humain et IA) diff --git a/zh/analytics.openapi.json b/zh/analytics.openapi.json index c4b0c40f9..232939b1b 100644 --- a/zh/analytics.openapi.json +++ b/zh/analytics.openapi.json @@ -3,12 +3,12 @@ "info": { "title": "Mintlify Analytics Export API", "version": "1.0.0", - "description": "用于导出文档 Analytics 数据的 API" + "description": "API for exporting documentation analytics data" }, "servers": [ { "url": "https://api.mintlify.com", - "description": "生产环境" + "description": "Production" } ], "components": { @@ -16,20 +16,20 @@ "bearerAuth": { "type": "http", "scheme": "bearer", - "description": "Authorization 请求头需要使用 Bearer Token。请使用管理员 API key（以 `mint_` 开头）。这是仅供服务端使用的密钥。你可以在控制台的 [API keys 页面](https://dashboard.mintlify.com/settings/organization/api-keys) 中生成。" + "description": "The Authorization header expects a Bearer token. Use an admin API key (prefixed with `mint_`). This is a server-side secret key. Generate one on the [API keys page](https://dashboard.mintlify.com/settings/organization/api-keys) in your dashboard." } }, "schemas": { "projectId": { "type": "string", - "description": "你的项目 ID，可在控制台的 [API keys](https://dashboard.mintlify.com/settings/organization/api-keys) 页面中复制。" + "description": "Your project ID. Can be copied from the [API keys](https://dashboard.mintlify.com/settings/organization/api-keys) page in your dashboard." }, "FeedbackResponse": { "type": "object", "properties": { "feedback": { "type": "array", - "description": "反馈条目的列表。", + "description": "List of feedback entries.", "items": { "anyOf": [ { @@ -37,25 +37,25 @@ "properties": { "id": { "type": "string", - "description": "反馈的唯一标识符。" + "description": "Unique feedback identifier." }, "path": { "type": "string", - "description": "源文档的路径或 URL。" + "description": "The path or URL to the source document." }, "comment": { "type": [ "string", "null" ], - "description": "用户提交的反馈内容。" + "description": "Text of the user's feedback comment." }, "createdAt": { "type": [ "string", "null" ], - "description": "提交该反馈时的时间戳。" + "description": "Timestamp when the feedback was submitted." }, "source": { "type": "string", @@ -63,7 +63,7 @@ "code_snippet", "contextual" ], - "description": "反馈的来源类型。`code_snippet` 表示针对代码块的反馈，`contextual` 表示页面级别的反馈。" + "description": "Where the feedback originated. `code_snippet` is feedback on a code block, `contextual` is page-level feedback." }, "status": { "type": "string", @@ -73,7 +73,7 @@ "resolved", "dismissed" ], - "description": "该反馈当前的审核状态。" + "description": "Current review status of the feedback." } }, "required": [ @@ -90,25 +90,25 @@ "properties": { "id": { "type": "string", - "description": "该反馈的唯一标识符。" + "description": "Unique feedback identifier." }, "path": { "type": "string", - "description": "源文档的路径或 URL。" + "description": "The path or URL to the source document." }, "comment": { "type": [ "string", "null" ], - "description": "用户提交的反馈内容。" + "description": "Text of the user's feedback comment." }, "createdAt": { "type": [ "string", "null" ], - "description": "提交该反馈时的时间戳。" + "description": "Timestamp when the feedback was submitted." }, "source": { "type": "string", @@ -116,7 +116,7 @@ "code_snippet", "contextual" ], - "description": "反馈的来源类型。`code_snippet` 表示针对代码块的反馈，`contextual` 表示页面级别的反馈。" + "description": "Where the feedback originated. `code_snippet` is feedback on a code block, `contextual` is page-level feedback." }, "status": { "type": "string", @@ -126,18 +126,18 @@ "resolved", "dismissed" ], - "description": "反馈当前的审核状态。" + "description": "Current review status of the feedback." }, "helpful": { "type": "boolean", - "description": "用户是否认为该内容有帮助。" + "description": "Whether the user found the content helpful." }, "contact": { "type": [ "string", "null" ], - "description": "用户提供的用于后续联系的电子邮件地址。" + "description": "Email address the user provided for follow-up." } }, "required": [ @@ -156,25 +156,25 @@ "properties": { "id": { "type": "string", - "description": "反馈的唯一标识符。" + "description": "Unique feedback identifier." }, "path": { "type": "string", - "description": "源文档的路径或 URL。" + "description": "The path or URL to the source document." }, "comment": { "type": [ "string", "null" ], - "description": "用户反馈评论的正文内容。" + "description": "Text of the user's feedback comment." }, "createdAt": { "type": [ "string", "null" ], - "description": "提交该反馈时的时间戳。" + "description": "Timestamp when the feedback was submitted." }, "source": { "type": "string", @@ -182,7 +182,7 @@ "code_snippet", "contextual" ], - "description": "反馈的来源类型。`code_snippet` 表示针对代码块的反馈，`contextual` 表示针对整页的反馈。" + "description": "Where the feedback originated. `code_snippet` is feedback on a code block, `contextual` is page-level feedback." }, "status": { "type": "string", @@ -192,25 +192,25 @@ "resolved", "dismissed" ], - "description": "反馈当前的审核状态。" + "description": "Current review status of the feedback." }, "code": { "type": "string", - "description": "与该反馈相关的代码片段。" + "description": "The code snippet the feedback relates to." }, "filename": { "type": [ "string", "null" ], - "description": "与代码片段关联的文件名。" + "description": "Filename associated with the code snippet." }, "lang": { "type": [ "string", "null" ], - "description": "代码片段所使用的编程语言。" + "description": "Programming language of the code snippet." } }, "required": [ @@ -233,11 +233,11 @@ "string", "null" ], - "description": "用于获取下一页结果的游标。如果没有更多结果，则为 null。" + "description": "Cursor to retrieve the next page of results. Null if no more results." }, "hasMore": { "type": "boolean", - "description": "当前页之后是否还有更多结果。" + "description": "Whether additional results are available beyond this page." } }, "required": [ @@ -251,17 +251,17 @@ "properties": { "error": { "type": "string", - "description": "描述错误原因的错误信息。" + "description": "Error message describing what went wrong." }, "details": { "type": "array", - "description": "关于该错误的其他详细信息。", + "description": "Additional details about the error.", "items": { "type": "object", "properties": { "message": { "type": "string", - "description": "对某个特定校验或处理错误的说明。" + "description": "Description of a specific validation or processing error." } }, "required": [ @@ -279,39 +279,39 @@ "properties": { "conversations": { "type": "array", - "description": "AI 助手会话列表。", + "description": "List of assistant conversations.", "items": { "type": "object", "properties": { "id": { "type": "string", - "description": "会话的唯一标识符。" + "description": "Unique conversation identifier." }, "timestamp": { "type": "string", - "description": "会话发生时的时间戳。" + "description": "Timestamp when the conversation occurred." }, "query": { "type": "string", - "description": "用户向 AI 助手提出的问题。" + "description": "The user's question to the assistant." }, "response": { "type": "string", - "description": "AI 助手的回答。" + "description": "The assistant's response." }, "sources": { "type": "array", - "description": "在回答中被引用的文档页面。", + "description": "Documentation pages referenced in the response.", "items": { "type": "object", "properties": { "title": { "type": "string", - "description": "被引用文档页面的标题。" + "description": "Title of the referenced documentation page." }, "url": { "type": "string", - "description": "被引用文档页面的 URL。" + "description": "URL of the referenced documentation page." } }, "required": [ @@ -325,7 +325,7 @@ "string", "null" ], - "description": "会话自动分配的分类分组（如适用）。" + "description": "Auto-assigned category grouping for the conversation, if applicable." } }, "required": [ @@ -343,11 +343,11 @@ "string", "null" ], - "description": "用于获取下一页结果的游标；如果没有更多结果则为 null。" + "description": "Cursor to retrieve the next page of results. Null if no more results." }, "hasMore": { "type": "boolean", - "description": "指示在当前页之外是否还有更多可用结果。" + "description": "Whether additional results are available beyond this page." } }, "required": [ @@ -450,7 +450,7 @@ "totalSearches": { "type": "integer", "minimum": 0, - "description": "Total count of search events in the requested date range." + "description": "Total count of search events in the requested date range (sum of all hits, not distinct queries)." }, "nextCursor": { "type": [ @@ -465,6 +465,122 @@ "totalSearches", "nextCursor" ] + }, + "ViewsTrafficTotals": { + "type": "object", + "properties": { + "human": { + "type": "number", + "description": "Site-wide content view events from human traffic." + }, + "ai": { + "type": "number", + "description": "Site-wide content view events from AI bot traffic." + }, + "total": { + "type": "number", + "description": "Site-wide content view events." + } + }, + "required": ["human", "ai", "total"] + }, + "ViewsByPageResponse": { + "type": "object", + "properties": { + "totals": { + "$ref": "#/components/schemas/ViewsTrafficTotals", + "description": "Site-wide view totals for the date range." + }, + "views": { + "type": "array", + "description": "Per-page view counts.", + "items": { + "type": "object", + "properties": { + "path": { + "type": "string", + "description": "The documentation page path." + }, + "human": { + "type": "number", + "description": "Content view events on this path from human traffic." + }, + "ai": { + "type": "number", + "description": "Content view events on this path from AI bot traffic." + }, + "total": { + "type": "number", + "description": "Total content view events on this path." + } + }, + "required": ["path", "human", "ai", "total"] + } + }, + "hasMore": { + "type": "boolean", + "description": "Whether additional results are available beyond this page." + } + }, + "required": ["totals", "views", "hasMore"] + }, + "VisitorsTrafficTotals": { + "type": "object", + "properties": { + "human": { + "type": "number", + "description": "Site-wide unique visitors from human traffic." + }, + "ai": { + "type": "number", + "description": "Site-wide unique visitors from AI bot traffic." + }, + "total": { + "type": "number", + "description": "Site-wide approximate distinct visitors with any qualifying view (deduplicated across human and AI)." + } + }, + "required": ["human", "ai", "total"] + }, + "VisitorsByPageResponse": { + "type": "object", + "properties": { + "totals": { + "$ref": "#/components/schemas/VisitorsTrafficTotals", + "description": "Site-wide unique visitor totals for the date range." + }, + "visitors": { + "type": "array", + "description": "Per-page visitor counts.", + "items": { + "type": "object", + "properties": { + "path": { + "type": "string", + "description": "The documentation page path." + }, + "human": { + "type": "number", + "description": "Unique visitors from human traffic." + }, + "ai": { + "type": "number", + "description": "Unique visitors from AI bot traffic." + }, + "total": { + "type": "number", + "description": "Approximate distinct visitors with any qualifying view on this path (deduplicated across human and AI)." + } + }, + "required": ["path", "human", "ai", "total"] + } + }, + "hasMore": { + "type": "boolean", + "description": "Whether additional results are available beyond this page." + } + }, + "required": ["totals", "visitors", "hasMore"] } }, "parameters": { @@ -481,8 +597,8 @@ "paths": { "/v1/analytics/{projectId}/feedback": { "get": { - "summary": "获取用户反馈列表", - "description": "返回按页划分的用户反馈，并支持可选筛选条件", + "summary": "Get user feedback", + "description": "Returns paginated user feedback with optional filtering", "tags": [ "Analytics" ], @@ -498,7 +614,7 @@ { "schema": { "type": "string", - "description": "ISO 8601 或 YYYY-MM-DD 格式的日期", + "description": "Date in ISO 8601 or YYYY-MM-DD format", "example": "2024-01-01" }, "required": false, @@ -508,7 +624,7 @@ { "schema": { "type": "string", - "description": "ISO 8601 或 YYYY-MM-DD 格式的日期。`dateTo` 为不包含在内的上界。结果包括指定日期之前的所有日期，但不包括指定日期当天。", + "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, @@ -522,7 +638,7 @@ "code_snippet", "contextual" ], - "description": "按反馈来源进行筛选" + "description": "Filter by feedback source" }, "required": false, "name": "source", @@ -531,7 +647,7 @@ { "schema": { "type": "string", - "description": "用于筛选的以逗号分隔的状态列表" + "description": "Comma-separated list of statuses to filter by" }, "required": false, "name": "status", @@ -543,7 +659,7 @@ "minimum": 1, "maximum": 100, "default": 50, - "description": "每页返回的最大结果数" + "description": "Max results per page" }, "required": false, "name": "limit", @@ -552,7 +668,7 @@ { "schema": { "type": "string", - "description": "分页游标" + "description": "Pagination cursor" }, "required": false, "name": "cursor", @@ -561,7 +677,7 @@ ], "responses": { "200": { - "description": "包含分页信息的反馈数据", + "description": "Feedback data with pagination", "content": { "application/json": { "schema": { @@ -571,7 +687,7 @@ } }, "400": { - "description": "无效的查询参数", + "description": "Invalid query parameters", "content": { "application/json": { "schema": { @@ -581,7 +697,7 @@ } }, "500": { - "description": "服务器错误", + "description": "Server error", "content": { "application/json": { "schema": { @@ -595,8 +711,8 @@ }, "/v1/analytics/{projectId}/feedback/by-page": { "get": { - "summary": "按页面获取反馈", - "description": "返回按文档页面路径汇总的反馈计数", + "summary": "Get feedback by page", + "description": "Returns feedback counts aggregated by documentation page path (thumbs up/down for contextual feedback, code snippet count, and total per page)", "tags": [ "Analytics" ], @@ -612,7 +728,7 @@ { "schema": { "type": "string", - "description": "ISO 8601 或 YYYY-MM-DD 格式的日期", + "description": "Date in ISO 8601 or YYYY-MM-DD format", "example": "2024-01-01" }, "required": false, @@ -622,7 +738,7 @@ { "schema": { "type": "string", - "description": "不包含在内的上界", + "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, @@ -635,7 +751,7 @@ "minimum": 1, "maximum": 100, "default": 10, - "description": "每页返回的最大结果数" + "description": "Max results per page" }, "required": false, "name": "limit", @@ -648,7 +764,7 @@ "code_snippet", "contextual" ], - "description": "按反馈来源筛选" + "description": "Filter by feedback source" }, "required": false, "name": "source", @@ -657,7 +773,7 @@ { "schema": { "type": "string", - "description": "以逗号分隔的状态列表" + "description": "Comma-separated list of statuses to filter by" }, "required": false, "name": "status", @@ -666,7 +782,7 @@ ], "responses": { "200": { - "description": "按页面汇总的反馈数据", + "description": "Per-page feedback aggregates with pagination flag", "content": { "application/json": { "schema": { @@ -676,7 +792,7 @@ } }, "400": { - "description": "无效的查询参数", + "description": "Invalid query parameters", "content": { "application/json": { "schema": { @@ -686,7 +802,7 @@ } }, "500": { - "description": "服务器错误", + "description": "Server error", "content": { "application/json": { "schema": { @@ -700,8 +816,8 @@ }, "/v1/analytics/{projectId}/assistant": { "get": { - "summary": "获取 AI 助手会话记录", - "description": "返回分页后的 AI 助手会话历史", + "summary": "Get assistant conversations", + "description": "Returns paginated AI assistant conversation history", "tags": [ "Analytics" ], @@ -717,7 +833,7 @@ { "schema": { "type": "string", - "description": "ISO 8601 或 YYYY-MM-DD 格式的日期", + "description": "Date in ISO 8601 or YYYY-MM-DD format", "example": "2024-01-01" }, "required": false, @@ -727,7 +843,7 @@ { "schema": { "type": "string", - "description": "ISO 8601 或 YYYY-MM-DD 格式的日期。`dateTo` 为不包含在内的上限。结果将包含早于该日期的记录，但不包含该日期当天的记录。", + "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, @@ -740,7 +856,7 @@ "minimum": 1, "maximum": 1000, "default": 100, - "description": "每页返回的最大结果数" + "description": "Max results per page" }, "required": false, "name": "limit", @@ -750,7 +866,7 @@ "schema": { "type": "string", "format": "ulid", - "description": "分页游标（ULID 格式）" + "description": "Pagination cursor (ULID format)" }, "required": false, "name": "cursor", @@ -759,7 +875,7 @@ ], "responses": { "200": { - "description": "包含分页信息的会话数据", + "description": "Conversation data with pagination", "content": { "application/json": { "schema": { @@ -769,7 +885,7 @@ } }, "400": { - "description": "无效的查询参数", + "description": "Invalid query parameters", "content": { "application/json": { "schema": { @@ -779,7 +895,7 @@ } }, "500": { - "description": "服务器错误", + "description": "Server error", "content": { "application/json": { "schema": { @@ -793,8 +909,8 @@ }, "/v1/analytics/{projectId}/searches": { "get": { - "summary": "获取搜索查询", - "description": "返回指定日期范围内的搜索词，按搜索次数降序排列", + "summary": "Get search queries", + "description": "Returns paginated documentation search terms for the date range, ordered by hit count descending. Each row includes click-through rate, the most-clicked result path for that query (if any), and the last time the term was searched. `totalSearches` is the total number of search query events in the same date range (sum of all hits, not distinct queries).", "tags": [ "Analytics" ], @@ -810,7 +926,7 @@ { "schema": { "type": "string", - "description": "ISO 8601 或 YYYY-MM-DD 格式的日期", + "description": "Date in ISO 8601 or YYYY-MM-DD format", "example": "2024-01-01" }, "required": false, @@ -820,7 +936,7 @@ { "schema": { "type": "string", - "description": "不包含在内的上界", + "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, @@ -833,7 +949,7 @@ "minimum": 1, "maximum": 100, "default": 50, - "description": "每页返回的最大搜索词数" + "description": "Max search terms per page (ordered by hit count descending)" }, "required": false, "name": "limit", @@ -842,7 +958,7 @@ { "schema": { "type": "string", - "description": "上一次响应中的分页游标" + "description": "Opaque pagination cursor from the previous response" }, "required": false, "name": "cursor", @@ -851,7 +967,7 @@ ], "responses": { "200": { - "description": "搜索词汇总数据", + "description": "Search term aggregates with pagination", "content": { "application/json": { "schema": { @@ -861,7 +977,195 @@ } }, "400": { - "description": "无效的查询参数或游标", + "description": "Invalid query parameters or cursor", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AnalyticsErrorResponse" + } + } + } + }, + "500": { + "description": "Server error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AnalyticsErrorResponse" + } + } + } + } + } + } + }, + "/v1/analytics/{projectId}/views": { + "get": { + "summary": "Get page views", + "description": "Returns per-path and site-wide content view event counts, split by human and AI traffic.", + "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": "integer", + "minimum": 1, + "maximum": 250, + "default": 50, + "description": "Max results per page (1-250, default 50). Increment offset by limit while hasMore is true to paginate." + }, + "required": false, + "name": "limit", + "in": "query" + }, + { + "schema": { + "type": "integer", + "minimum": 0, + "default": 0, + "description": "Number of rows to skip. Use offset = (page - 1) * limit for page-based access." + }, + "required": false, + "name": "offset", + "in": "query" + } + ], + "responses": { + "200": { + "description": "Site-wide and per-path content view event counts", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ViewsByPageResponse" + } + } + } + }, + "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}/visitors": { + "get": { + "summary": "Get unique visitors", + "description": "Returns per-path and site-wide approximate distinct visitors by traffic type. The `total` field is deduplicated across human and AI (union of distinct visitor IDs with any qualifying content view).", + "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": "integer", + "minimum": 1, + "maximum": 250, + "default": 50, + "description": "Max results per page (1-250, default 50). Increment offset by limit while hasMore is true to paginate." + }, + "required": false, + "name": "limit", + "in": "query" + }, + { + "schema": { + "type": "integer", + "minimum": 0, + "default": 0, + "description": "Number of rows to skip. Use offset = (page - 1) * limit for page-based access." + }, + "required": false, + "name": "offset", + "in": "query" + } + ], + "responses": { + "200": { + "description": "Site-wide totals and per-path visitor counts", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/VisitorsByPageResponse" + } + } + } + }, + "400": { + "description": "Invalid query parameters", "content": { "application/json": { "schema": { @@ -871,7 +1175,7 @@ } }, "500": { - "description": "服务器错误", + "description": "Server error", "content": { "application/json": { "schema": { @@ -885,4 +1189,4 @@ } }, "webhooks": {} -} +} \ No newline at end of file diff --git a/zh/api/analytics/views.mdx b/zh/api/analytics/views.mdx new file mode 100644 index 000000000..44e84a650 --- /dev/null +++ b/zh/api/analytics/views.mdx @@ -0,0 +1,31 @@ +--- +title: "获取页面浏览量" +description: "获取按页面和全站的内容浏览事件计数，按人类和 AI 流量分类。" +openapi: /zh/analytics.openapi.json GET /v1/analytics/{projectId}/views +keywords: ["Analytics", "浏览量", "页面浏览", "流量", "导出"] +--- + +
+ ## 使用方法 +
+ +使用此端点导出页面浏览分析数据。结果包括全站总计和按页面的明细，按人类和 AI 流量分类。 + +使用基于偏移量的分页浏览结果。当 `hasMore` 为 true 时，将 `offset` 增加 `limit` 的值。 + +
+ ## 筛选 +
+ +使用 `dateFrom` 和 `dateTo` 参数按日期范围过滤浏览数据。 + +
+ ## 响应数据 +
+ +响应包含一个 `totals` 对象（全站聚合数据）和一个 `views` 数组（按页面的数据）。每个条目包含： + +- **path**：文档页面路径 +- **human**：来自人类流量的内容浏览事件数 +- **ai**：来自 AI 机器人流量的内容浏览事件数 +- **total**：该页面的总内容浏览事件数 diff --git a/zh/api/analytics/visitors.mdx b/zh/api/analytics/visitors.mdx new file mode 100644 index 000000000..9343b0697 --- /dev/null +++ b/zh/api/analytics/visitors.mdx @@ -0,0 +1,31 @@ +--- +title: "获取独立访客" +description: "获取按页面和全站的近似独立访客计数，按人类和 AI 流量分类。" +openapi: /zh/analytics.openapi.json GET /v1/analytics/{projectId}/visitors +keywords: ["Analytics", "访客", "独立访客", "流量", "导出"] +--- + +
+ ## 使用方法 +
+ +使用此端点导出独立访客分析数据。结果包括全站总计和按页面的明细，按人类和 AI 流量分类。`total` 字段在人类和 AI 流量之间去重。 + +使用基于偏移量的分页浏览结果。当 `hasMore` 为 true 时，将 `offset` 增加 `limit` 的值。 + +
+ ## 筛选 +
+ +使用 `dateFrom` 和 `dateTo` 参数按日期范围过滤访客数据。 + +
+ ## 响应数据 +
+ +响应包含一个 `totals` 对象（全站聚合数据）和一个 `visitors` 数组（按页面的数据）。每个条目包含： + +- **path**：文档页面路径 +- **human**：来自人类流量的独立访客数 +- **ai**：来自 AI 机器人流量的独立访客数 +- **total**：近似独立访客数（在人类和 AI 之间去重） From b1c7de60fd4023d6fcdb89ff3e8332f1c83b5acd Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Tue, 31 Mar 2026 16:42:01 -0700 Subject: [PATCH 3/7] remove translated files --- docs.json | 18 +- es/analytics.openapi.json | 751 +++----------------------- es/api/analytics/feedback-by-page.mdx | 36 -- es/api/analytics/searches.mdx | 34 -- es/api/analytics/views.mdx | 31 -- es/api/analytics/visitors.mdx | 31 -- fr/analytics.openapi.json | 749 +++---------------------- fr/api/analytics/feedback-by-page.mdx | 36 -- fr/api/analytics/searches.mdx | 34 -- fr/api/analytics/views.mdx | 31 -- fr/api/analytics/visitors.mdx | 31 -- zh/analytics.openapi.json | 751 +++----------------------- zh/api/analytics/feedback-by-page.mdx | 36 -- zh/api/analytics/searches.mdx | 34 -- zh/api/analytics/views.mdx | 31 -- zh/api/analytics/visitors.mdx | 31 -- 16 files changed, 218 insertions(+), 2447 deletions(-) delete mode 100644 es/api/analytics/feedback-by-page.mdx delete mode 100644 es/api/analytics/searches.mdx delete mode 100644 es/api/analytics/views.mdx delete mode 100644 es/api/analytics/visitors.mdx delete mode 100644 fr/api/analytics/feedback-by-page.mdx delete mode 100644 fr/api/analytics/searches.mdx delete mode 100644 fr/api/analytics/views.mdx delete mode 100644 fr/api/analytics/visitors.mdx delete mode 100644 zh/api/analytics/feedback-by-page.mdx delete mode 100644 zh/api/analytics/searches.mdx delete mode 100644 zh/api/analytics/views.mdx delete mode 100644 zh/api/analytics/visitors.mdx diff --git a/docs.json b/docs.json index 4f6d438f1..26d1c11a4 100644 --- a/docs.json +++ b/docs.json @@ -749,11 +749,7 @@ "icon": "chart-line", "pages": [ "fr/api/analytics/feedback", - "fr/api/analytics/feedback-by-page", - "fr/api/analytics/assistant-conversations", - "fr/api/analytics/searches", - "fr/api/analytics/views", - "fr/api/analytics/visitors" + "fr/api/analytics/assistant-conversations" ] } ] @@ -1125,11 +1121,7 @@ "icon": "chart-line", "pages": [ "es/api/analytics/feedback", - "es/api/analytics/feedback-by-page", - "es/api/analytics/assistant-conversations", - "es/api/analytics/searches", - "es/api/analytics/views", - "es/api/analytics/visitors" + "es/api/analytics/assistant-conversations" ] } ] @@ -1501,11 +1493,7 @@ "icon": "chart-line", "pages": [ "zh/api/analytics/feedback", - "zh/api/analytics/feedback-by-page", - "zh/api/analytics/assistant-conversations", - "zh/api/analytics/searches", - "zh/api/analytics/views", - "zh/api/analytics/visitors" + "zh/api/analytics/assistant-conversations" ] } ] diff --git a/es/analytics.openapi.json b/es/analytics.openapi.json index 232939b1b..a0a93c8b7 100644 --- a/es/analytics.openapi.json +++ b/es/analytics.openapi.json @@ -3,12 +3,12 @@ "info": { "title": "Mintlify Analytics Export API", "version": "1.0.0", - "description": "API for exporting documentation analytics data" + "description": "API para exportar datos de Analytics de la documentación" }, "servers": [ { "url": "https://api.mintlify.com", - "description": "Production" + "description": "Producción" } ], "components": { @@ -16,20 +16,20 @@ "bearerAuth": { "type": "http", "scheme": "bearer", - "description": "The Authorization header expects a Bearer token. Use an admin API key (prefixed with `mint_`). This is a server-side secret key. Generate one on the [API keys page](https://dashboard.mintlify.com/settings/organization/api-keys) in your dashboard." + "description": "El encabezado Authorization requiere un token Bearer. Usa una clave de API de administrador (con el prefijo `mint_`). Esta es una clave secreta del lado del servidor. Genérala en la [página de claves de API](https://dashboard.mintlify.com/settings/organization/api-keys) de tu dashboard." } }, "schemas": { "projectId": { "type": "string", - "description": "Your project ID. Can be copied from the [API keys](https://dashboard.mintlify.com/settings/organization/api-keys) page in your dashboard." + "description": "Tu ID de proyecto. Puedes copiarlo desde la página [API keys](https://dashboard.mintlify.com/settings/organization/api-keys) en tu dashboard." }, "FeedbackResponse": { "type": "object", "properties": { "feedback": { "type": "array", - "description": "List of feedback entries.", + "description": "Lista de entradas de comentarios.", "items": { "anyOf": [ { @@ -37,33 +37,34 @@ "properties": { "id": { "type": "string", - "description": "Unique feedback identifier." + "description": "Identificador único del comentario." }, "path": { "type": "string", - "description": "The path or URL to the source document." + "description": "La ruta o URL del documento de origen." }, "comment": { "type": [ "string", "null" ], - "description": "Text of the user's feedback comment." + "description": "Texto del comentario del usuario." }, "createdAt": { "type": [ "string", "null" ], - "description": "Timestamp when the feedback was submitted." + "description": "Fecha y hora en la que se envió el comentario." }, "source": { "type": "string", "enum": [ "code_snippet", - "contextual" + "contextual", + "thumbs_only" ], - "description": "Where the feedback originated. `code_snippet` is feedback on a code block, `contextual` is page-level feedback." + "description": "Origen del comentario. `code_snippet` indica un comentario sobre un bloque de código, `contextual` indica un comentario a nivel de página, `thumbs_only` es un voto de pulgar arriba/abajo." }, "status": { "type": "string", @@ -73,7 +74,7 @@ "resolved", "dismissed" ], - "description": "Current review status of the feedback." + "description": "Estado de revisión actual del comentario." } }, "required": [ @@ -90,33 +91,34 @@ "properties": { "id": { "type": "string", - "description": "Unique feedback identifier." + "description": "Identificador único del comentario." }, "path": { "type": "string", - "description": "The path or URL to the source document." + "description": "La ruta o URL del documento de origen." }, "comment": { "type": [ "string", "null" ], - "description": "Text of the user's feedback comment." + "description": "Texto del comentario del usuario." }, "createdAt": { "type": [ "string", "null" ], - "description": "Timestamp when the feedback was submitted." + "description": "Fecha y hora en la que se envió el comentario." }, "source": { "type": "string", "enum": [ "code_snippet", - "contextual" + "contextual", + "thumbs_only" ], - "description": "Where the feedback originated. `code_snippet` is feedback on a code block, `contextual` is page-level feedback." + "description": "Origen del comentario. `code_snippet` indica un comentario sobre un bloque de código, `contextual` indica un comentario a nivel de página, `thumbs_only` es un voto de pulgar arriba/abajo." }, "status": { "type": "string", @@ -126,18 +128,18 @@ "resolved", "dismissed" ], - "description": "Current review status of the feedback." + "description": "Estado actual de revisión del comentario." }, "helpful": { "type": "boolean", - "description": "Whether the user found the content helpful." + "description": "Indica si el usuario considera útil el contenido." }, "contact": { "type": [ "string", "null" ], - "description": "Email address the user provided for follow-up." + "description": "Dirección de correo electrónico proporcionada por el usuario para el seguimiento." } }, "required": [ @@ -156,33 +158,34 @@ "properties": { "id": { "type": "string", - "description": "Unique feedback identifier." + "description": "Identificador único del comentario." }, "path": { "type": "string", - "description": "The path or URL to the source document." + "description": "La ruta o URL del documento de origen." }, "comment": { "type": [ "string", "null" ], - "description": "Text of the user's feedback comment." + "description": "Texto del comentario del usuario." }, "createdAt": { "type": [ "string", "null" ], - "description": "Timestamp when the feedback was submitted." + "description": "Marca de tiempo del envío del comentario." }, "source": { "type": "string", "enum": [ "code_snippet", - "contextual" + "contextual", + "thumbs_only" ], - "description": "Where the feedback originated. `code_snippet` is feedback on a code block, `contextual` is page-level feedback." + "description": "Origen del comentario. `code_snippet` es un comentario sobre un bloque de código, `contextual` es un comentario a nivel de página, `thumbs_only` es un voto de pulgar arriba/abajo." }, "status": { "type": "string", @@ -192,25 +195,25 @@ "resolved", "dismissed" ], - "description": "Current review status of the feedback." + "description": "Estado actual de revisión del comentario." }, "code": { "type": "string", - "description": "The code snippet the feedback relates to." + "description": "Fragmento de código al que hace referencia el comentario." }, "filename": { "type": [ "string", "null" ], - "description": "Filename associated with the code snippet." + "description": "Nombre de archivo asociado al fragmento de código." }, "lang": { "type": [ "string", "null" ], - "description": "Programming language of the code snippet." + "description": "Lenguaje de programación del fragmento de código." } }, "required": [ @@ -233,11 +236,11 @@ "string", "null" ], - "description": "Cursor to retrieve the next page of results. Null if no more results." + "description": "Cursor para recuperar la página siguiente de resultados. Nulo si no hay más resultados." }, "hasMore": { "type": "boolean", - "description": "Whether additional results are available beyond this page." + "description": "Indica si hay más resultados después de esta página." } }, "required": [ @@ -251,17 +254,17 @@ "properties": { "error": { "type": "string", - "description": "Error message describing what went wrong." + "description": "Mensaje de error que describe lo que salió mal." }, "details": { "type": "array", - "description": "Additional details about the error.", + "description": "Detalles adicionales del error.", "items": { "type": "object", "properties": { "message": { "type": "string", - "description": "Description of a specific validation or processing error." + "description": "Descripción de un error específico de validación o procesamiento." } }, "required": [ @@ -279,39 +282,39 @@ "properties": { "conversations": { "type": "array", - "description": "List of assistant conversations.", + "description": "Lista de conversaciones del assistant.", "items": { "type": "object", "properties": { "id": { "type": "string", - "description": "Unique conversation identifier." + "description": "Identificador único de la conversación." }, "timestamp": { "type": "string", - "description": "Timestamp when the conversation occurred." + "description": "Marca de tiempo en la que se produjo la conversación." }, "query": { "type": "string", - "description": "The user's question to the assistant." + "description": "La pregunta del usuario para el assistant." }, "response": { "type": "string", - "description": "The assistant's response." + "description": "La respuesta del assistant." }, "sources": { "type": "array", - "description": "Documentation pages referenced in the response.", + "description": "Páginas de la documentación mencionadas en la respuesta.", "items": { "type": "object", "properties": { "title": { "type": "string", - "description": "Title of the referenced documentation page." + "description": "Título de la página de documentación mencionada." }, "url": { "type": "string", - "description": "URL of the referenced documentation page." + "description": "URL de la página de documentación mencionada." } }, "required": [ @@ -325,7 +328,7 @@ "string", "null" ], - "description": "Auto-assigned category grouping for the conversation, if applicable." + "description": "Categoría de agrupación asignada automáticamente a la conversación, si corresponde." } }, "required": [ @@ -343,11 +346,11 @@ "string", "null" ], - "description": "Cursor to retrieve the next page of results. Null if no more results." + "description": "Cursor para obtener la siguiente página de resultados. Es nulo si no hay más resultados." }, "hasMore": { "type": "boolean", - "description": "Whether additional results are available beyond this page." + "description": "Indica si hay resultados adicionales más allá de esta página." } }, "required": [ @@ -355,232 +358,6 @@ "nextCursor", "hasMore" ] - }, - "FeedbackGroupedByPageResponse": { - "type": "object", - "properties": { - "feedback": { - "type": "array", - "description": "Feedback counts aggregated by documentation page path.", - "items": { - "type": "object", - "properties": { - "path": { - "type": "string", - "description": "The documentation page path." - }, - "thumbsUp": { - "type": "number", - "description": "Number of positive (thumbs up) contextual feedback entries." - }, - "thumbsDown": { - "type": "number", - "description": "Number of negative (thumbs down) contextual feedback entries." - }, - "code": { - "type": "number", - "description": "Number of code snippet feedback entries." - }, - "total": { - "type": "number", - "description": "Total feedback entries for this page." - } - }, - "required": [ - "path", - "thumbsUp", - "thumbsDown", - "code", - "total" - ] - } - }, - "hasMore": { - "type": "boolean", - "description": "Whether additional results are available beyond this page." - } - }, - "required": [ - "feedback", - "hasMore" - ] - }, - "SearchesResponse": { - "type": "object", - "properties": { - "searches": { - "type": "array", - "description": "Search terms ordered by hit count descending.", - "items": { - "type": "object", - "properties": { - "searchQuery": { - "type": "string", - "description": "The search term entered by users." - }, - "hits": { - "type": "number", - "description": "Number of times this term was searched." - }, - "ctr": { - "type": "number", - "description": "Click-through rate for this search term." - }, - "topClickedPage": { - "type": [ - "string", - "null" - ], - "description": "The most-clicked result path for this query, if any." - }, - "lastSearchedAt": { - "type": "string", - "description": "Timestamp of the last time this term was searched." - } - }, - "required": [ - "searchQuery", - "hits", - "ctr", - "topClickedPage", - "lastSearchedAt" - ] - } - }, - "totalSearches": { - "type": "integer", - "minimum": 0, - "description": "Total count of search events in the requested date range (sum of all hits, not distinct queries)." - }, - "nextCursor": { - "type": [ - "string", - "null" - ], - "description": "Opaque pagination cursor for the next page. Null if no more results." - } - }, - "required": [ - "searches", - "totalSearches", - "nextCursor" - ] - }, - "ViewsTrafficTotals": { - "type": "object", - "properties": { - "human": { - "type": "number", - "description": "Site-wide content view events from human traffic." - }, - "ai": { - "type": "number", - "description": "Site-wide content view events from AI bot traffic." - }, - "total": { - "type": "number", - "description": "Site-wide content view events." - } - }, - "required": ["human", "ai", "total"] - }, - "ViewsByPageResponse": { - "type": "object", - "properties": { - "totals": { - "$ref": "#/components/schemas/ViewsTrafficTotals", - "description": "Site-wide view totals for the date range." - }, - "views": { - "type": "array", - "description": "Per-page view counts.", - "items": { - "type": "object", - "properties": { - "path": { - "type": "string", - "description": "The documentation page path." - }, - "human": { - "type": "number", - "description": "Content view events on this path from human traffic." - }, - "ai": { - "type": "number", - "description": "Content view events on this path from AI bot traffic." - }, - "total": { - "type": "number", - "description": "Total content view events on this path." - } - }, - "required": ["path", "human", "ai", "total"] - } - }, - "hasMore": { - "type": "boolean", - "description": "Whether additional results are available beyond this page." - } - }, - "required": ["totals", "views", "hasMore"] - }, - "VisitorsTrafficTotals": { - "type": "object", - "properties": { - "human": { - "type": "number", - "description": "Site-wide unique visitors from human traffic." - }, - "ai": { - "type": "number", - "description": "Site-wide unique visitors from AI bot traffic." - }, - "total": { - "type": "number", - "description": "Site-wide approximate distinct visitors with any qualifying view (deduplicated across human and AI)." - } - }, - "required": ["human", "ai", "total"] - }, - "VisitorsByPageResponse": { - "type": "object", - "properties": { - "totals": { - "$ref": "#/components/schemas/VisitorsTrafficTotals", - "description": "Site-wide unique visitor totals for the date range." - }, - "visitors": { - "type": "array", - "description": "Per-page visitor counts.", - "items": { - "type": "object", - "properties": { - "path": { - "type": "string", - "description": "The documentation page path." - }, - "human": { - "type": "number", - "description": "Unique visitors from human traffic." - }, - "ai": { - "type": "number", - "description": "Unique visitors from AI bot traffic." - }, - "total": { - "type": "number", - "description": "Approximate distinct visitors with any qualifying view on this path (deduplicated across human and AI)." - } - }, - "required": ["path", "human", "ai", "total"] - } - }, - "hasMore": { - "type": "boolean", - "description": "Whether additional results are available beyond this page." - } - }, - "required": ["totals", "visitors", "hasMore"] } }, "parameters": { @@ -597,8 +374,8 @@ "paths": { "/v1/analytics/{projectId}/feedback": { "get": { - "summary": "Get user feedback", - "description": "Returns paginated user feedback with optional filtering", + "summary": "Obtener comentarios de los usuarios", + "description": "Devuelve comentarios de usuarios con paginación y filtrado opcional", "tags": [ "Analytics" ], @@ -614,7 +391,7 @@ { "schema": { "type": "string", - "description": "Date in ISO 8601 or YYYY-MM-DD format", + "description": "Fecha en formato ISO 8601 o AAAA-MM-DD", "example": "2024-01-01" }, "required": false, @@ -624,7 +401,7 @@ { "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.", + "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, @@ -636,9 +413,10 @@ "type": "string", "enum": [ "code_snippet", - "contextual" + "contextual", + "thumbs_only" ], - "description": "Filter by feedback source" + "description": "Filtrar por el origen de los comentarios" }, "required": false, "name": "source", @@ -647,7 +425,7 @@ { "schema": { "type": "string", - "description": "Comma-separated list of statuses to filter by" + "description": "Lista de estados separados por comas por los que filtrar" }, "required": false, "name": "status", @@ -659,7 +437,7 @@ "minimum": 1, "maximum": 100, "default": 50, - "description": "Max results per page" + "description": "Número máximo de resultados por página" }, "required": false, "name": "limit", @@ -668,7 +446,7 @@ { "schema": { "type": "string", - "description": "Pagination cursor" + "description": "Cursor de paginación" }, "required": false, "name": "cursor", @@ -677,7 +455,7 @@ ], "responses": { "200": { - "description": "Feedback data with pagination", + "description": "Datos de comentarios paginados", "content": { "application/json": { "schema": { @@ -687,112 +465,7 @@ } }, "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}/feedback/by-page": { - "get": { - "summary": "Get feedback by page", - "description": "Returns feedback counts aggregated by documentation page path (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": "number", - "minimum": 1, - "maximum": 100, - "default": 10, - "description": "Max results per page" - }, - "required": false, - "name": "limit", - "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" - } - ], - "responses": { - "200": { - "description": "Per-page feedback aggregates with pagination flag", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/FeedbackGroupedByPageResponse" - } - } - } - }, - "400": { - "description": "Invalid query parameters", + "description": "Parámetros de búsqueda no válidos", "content": { "application/json": { "schema": { @@ -802,7 +475,7 @@ } }, "500": { - "description": "Server error", + "description": "Error del servidor", "content": { "application/json": { "schema": { @@ -816,8 +489,8 @@ }, "/v1/analytics/{projectId}/assistant": { "get": { - "summary": "Get assistant conversations", - "description": "Returns paginated AI assistant conversation history", + "summary": "Obtener conversaciones del assistant", + "description": "Devuelve el historial paginado de conversaciones del Asistente de IA", "tags": [ "Analytics" ], @@ -833,7 +506,7 @@ { "schema": { "type": "string", - "description": "Date in ISO 8601 or YYYY-MM-DD format", + "description": "Fecha en formato ISO 8601 o AAAA-MM-DD", "example": "2024-01-01" }, "required": false, @@ -843,7 +516,7 @@ { "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.", + "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, @@ -856,7 +529,7 @@ "minimum": 1, "maximum": 1000, "default": 100, - "description": "Max results per page" + "description": "Número máximo de resultados por página" }, "required": false, "name": "limit", @@ -866,7 +539,7 @@ "schema": { "type": "string", "format": "ulid", - "description": "Pagination cursor (ULID format)" + "description": "Cursor de paginación (formato ULID)" }, "required": false, "name": "cursor", @@ -875,7 +548,7 @@ ], "responses": { "200": { - "description": "Conversation data with pagination", + "description": "Datos de conversación paginados", "content": { "application/json": { "schema": { @@ -885,287 +558,7 @@ } }, "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}/searches": { - "get": { - "summary": "Get search queries", - "description": "Returns paginated documentation search terms for the date range, ordered by hit count descending. Each row includes click-through rate, the most-clicked result path for that query (if any), and the last time the term was searched. `totalSearches` is the total number of search query events in the same date range (sum of all hits, not distinct queries).", - "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": "number", - "minimum": 1, - "maximum": 100, - "default": 50, - "description": "Max search terms per page (ordered by hit count descending)" - }, - "required": false, - "name": "limit", - "in": "query" - }, - { - "schema": { - "type": "string", - "description": "Opaque pagination cursor from the previous response" - }, - "required": false, - "name": "cursor", - "in": "query" - } - ], - "responses": { - "200": { - "description": "Search term aggregates with pagination", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/SearchesResponse" - } - } - } - }, - "400": { - "description": "Invalid query parameters or cursor", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/AnalyticsErrorResponse" - } - } - } - }, - "500": { - "description": "Server error", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/AnalyticsErrorResponse" - } - } - } - } - } - } - }, - "/v1/analytics/{projectId}/views": { - "get": { - "summary": "Get page views", - "description": "Returns per-path and site-wide content view event counts, split by human and AI traffic.", - "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": "integer", - "minimum": 1, - "maximum": 250, - "default": 50, - "description": "Max results per page (1-250, default 50). Increment offset by limit while hasMore is true to paginate." - }, - "required": false, - "name": "limit", - "in": "query" - }, - { - "schema": { - "type": "integer", - "minimum": 0, - "default": 0, - "description": "Number of rows to skip. Use offset = (page - 1) * limit for page-based access." - }, - "required": false, - "name": "offset", - "in": "query" - } - ], - "responses": { - "200": { - "description": "Site-wide and per-path content view event counts", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ViewsByPageResponse" - } - } - } - }, - "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}/visitors": { - "get": { - "summary": "Get unique visitors", - "description": "Returns per-path and site-wide approximate distinct visitors by traffic type. The `total` field is deduplicated across human and AI (union of distinct visitor IDs with any qualifying content view).", - "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": "integer", - "minimum": 1, - "maximum": 250, - "default": 50, - "description": "Max results per page (1-250, default 50). Increment offset by limit while hasMore is true to paginate." - }, - "required": false, - "name": "limit", - "in": "query" - }, - { - "schema": { - "type": "integer", - "minimum": 0, - "default": 0, - "description": "Number of rows to skip. Use offset = (page - 1) * limit for page-based access." - }, - "required": false, - "name": "offset", - "in": "query" - } - ], - "responses": { - "200": { - "description": "Site-wide totals and per-path visitor counts", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/VisitorsByPageResponse" - } - } - } - }, - "400": { - "description": "Invalid query parameters", + "description": "Parámetros de búsqueda no válidos", "content": { "application/json": { "schema": { @@ -1175,7 +568,7 @@ } }, "500": { - "description": "Server error", + "description": "Error del servidor", "content": { "application/json": { "schema": { diff --git a/es/api/analytics/feedback-by-page.mdx b/es/api/analytics/feedback-by-page.mdx deleted file mode 100644 index de614a96b..000000000 --- a/es/api/analytics/feedback-by-page.mdx +++ /dev/null @@ -1,36 +0,0 @@ ---- -title: "Obtener comentarios por página" -description: "Obtén los conteos de comentarios de los usuarios agregados por página de documentación, incluyendo valoraciones de pulgar arriba/abajo y comentarios sobre fragmentos de código." -openapi: /es/analytics.openapi.json GET /v1/analytics/{projectId}/feedback/by-page -keywords: ["analytics", "comentarios", "exportación", "por página", "agregado"] ---- - -
- ## Uso -
- -Usa este endpoint para exportar los comentarios de los usuarios agregados por ruta de página de documentación. Cada entrada muestra el conteo total de comentarios para una página, desglosado por tipo. - -Pagina los resultados usando el indicador `hasMore` en la respuesta. - -
- ## Filtrado -
- -Filtra los 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` - -
- ## Datos de respuesta -
- -Cada entrada de página incluye: - -- **path**: La ruta de la página de documentación -- **thumbsUp**: Conteo de comentarios contextuales positivos -- **thumbsDown**: Conteo de comentarios contextuales negativos -- **code**: Conteo de comentarios sobre fragmentos de código -- **total**: Total de entradas de comentarios para la página diff --git a/es/api/analytics/searches.mdx b/es/api/analytics/searches.mdx deleted file mode 100644 index 2a6555033..000000000 --- a/es/api/analytics/searches.mdx +++ /dev/null @@ -1,34 +0,0 @@ ---- -title: "Obtener consultas de búsqueda" -description: "Obtén los términos de búsqueda de la documentación con conteos de búsquedas, tasas de clics y las páginas más clicadas." -openapi: /es/analytics.openapi.json GET /v1/analytics/{projectId}/searches -keywords: ["analytics", "búsqueda", "exportación", "consultas", "términos de búsqueda"] ---- - -
- ## Uso -
- -Usa este endpoint para exportar los datos analíticos de búsqueda de tu documentación. Los resultados se ordenan por número de búsquedas de forma descendente, mostrando los términos que más buscan tus usuarios. - -Pagina los resultados usando el parámetro `nextCursor` devuelto en la respuesta. Continúa obteniendo resultados mientras `nextCursor` no sea null. - -
- ## Filtrado -
- -Filtra los datos de búsqueda por rango de fechas usando los parámetros `dateFrom` y `dateTo`. - -
- ## Datos de respuesta -
- -Cada entrada de término de búsqueda incluye: - -- **searchQuery**: El término de búsqueda introducido por los usuarios -- **hits**: Número de veces que se buscó este término -- **ctr**: Tasa de clics para este término de búsqueda -- **topClickedPage**: La ruta del resultado más clicado para esta consulta, si existe -- **lastSearchedAt**: Marca de tiempo de la última vez que se buscó este término - -La respuesta también incluye `totalSearches`, que es el conteo total de todos los eventos de búsqueda en el rango de fechas solicitado (suma de todos los hits, no consultas distintas). diff --git a/es/api/analytics/views.mdx b/es/api/analytics/views.mdx deleted file mode 100644 index 764c89d1c..000000000 --- a/es/api/analytics/views.mdx +++ /dev/null @@ -1,31 +0,0 @@ ---- -title: "Obtener vistas de páginas" -description: "Obtén los conteos de vistas de contenido por página y a nivel del sitio, divididos entre tráfico humano e IA." -openapi: /es/analytics.openapi.json GET /v1/analytics/{projectId}/views -keywords: ["analytics", "vistas", "vistas de página", "tráfico", "exportación"] ---- - -
- ## Uso -
- -Usa este endpoint para exportar los datos analíticos de vistas de páginas. Los resultados incluyen totales a nivel del sitio y desgloses por página, divididos entre tráfico humano e IA. - -Pagina los resultados usando paginación basada en offset. Incrementa `offset` por `limit` mientras `hasMore` sea true. - -
- ## Filtrado -
- -Filtra los datos de vistas por rango de fechas usando los parámetros `dateFrom` y `dateTo`. - -
- ## Datos de respuesta -
- -La respuesta incluye un objeto `totals` con agregados a nivel del sitio y un arreglo `views` con datos por página. Cada entrada incluye: - -- **path**: La ruta de la página de documentación -- **human**: Eventos de vista de contenido del tráfico humano -- **ai**: Eventos de vista de contenido del tráfico IA -- **total**: Total de eventos de vista de contenido en esta página diff --git a/es/api/analytics/visitors.mdx b/es/api/analytics/visitors.mdx deleted file mode 100644 index 4567235d7..000000000 --- a/es/api/analytics/visitors.mdx +++ /dev/null @@ -1,31 +0,0 @@ ---- -title: "Obtener visitantes únicos" -description: "Obtén los conteos aproximados de visitantes únicos por página y a nivel del sitio, divididos entre tráfico humano e IA." -openapi: /es/analytics.openapi.json GET /v1/analytics/{projectId}/visitors -keywords: ["analytics", "visitantes", "visitantes únicos", "tráfico", "exportación"] ---- - -
- ## Uso -
- -Usa este endpoint para exportar los datos analíticos de visitantes únicos. Los resultados incluyen totales a nivel del sitio y desgloses por página, divididos entre tráfico humano e IA. El campo `total` está deduplicado entre tráfico humano e IA. - -Pagina los resultados usando paginación basada en offset. Incrementa `offset` por `limit` mientras `hasMore` sea true. - -
- ## Filtrado -
- -Filtra los datos de visitantes por rango de fechas usando los parámetros `dateFrom` y `dateTo`. - -
- ## Datos de respuesta -
- -La respuesta incluye un objeto `totals` con agregados a nivel del sitio y un arreglo `visitors` con datos por página. Cada entrada incluye: - -- **path**: La ruta de la página de documentación -- **human**: Visitantes únicos del tráfico humano -- **ai**: Visitantes únicos del tráfico IA -- **total**: Visitantes distintos aproximados (deduplicados entre humano e IA) diff --git a/fr/analytics.openapi.json b/fr/analytics.openapi.json index 232939b1b..5bc77a706 100644 --- a/fr/analytics.openapi.json +++ b/fr/analytics.openapi.json @@ -3,7 +3,7 @@ "info": { "title": "Mintlify Analytics Export API", "version": "1.0.0", - "description": "API for exporting documentation analytics data" + "description": "API d’exportation des données Analytics de la documentation" }, "servers": [ { @@ -16,20 +16,20 @@ "bearerAuth": { "type": "http", "scheme": "bearer", - "description": "The Authorization header expects a Bearer token. Use an admin API key (prefixed with `mint_`). This is a server-side secret key. Generate one on the [API keys page](https://dashboard.mintlify.com/settings/organization/api-keys) in your dashboard." + "description": "L’en-tête Authorization requiert un jeton Bearer. Utilisez une clé d’API administrateur (préfixée par `mint_`). Il s’agit d’une clé secrète côté serveur. Générez-en une depuis la [page API keys](https://dashboard.mintlify.com/settings/organization/api-keys) dans votre Dashboard." } }, "schemas": { "projectId": { "type": "string", - "description": "Your project ID. Can be copied from the [API keys](https://dashboard.mintlify.com/settings/organization/api-keys) page in your dashboard." + "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": "List of feedback entries.", + "description": "Liste des retours.", "items": { "anyOf": [ { @@ -37,33 +37,34 @@ "properties": { "id": { "type": "string", - "description": "Unique feedback identifier." + "description": "Identifiant unique du retour." }, "path": { "type": "string", - "description": "The path or URL to the source document." + "description": "Le chemin ou l’URL du document source." }, "comment": { "type": [ "string", "null" ], - "description": "Text of the user's feedback comment." + "description": "Texte du commentaire de l’utilisateur." }, "createdAt": { "type": [ "string", "null" ], - "description": "Timestamp when the feedback was submitted." + "description": "Horodatage de l’envoi du retour." }, "source": { "type": "string", "enum": [ "code_snippet", - "contextual" + "contextual", + "thumbs_only" ], - "description": "Where the feedback originated. `code_snippet` is feedback on a code block, `contextual` is page-level feedback." + "description": "Source du retour. `code_snippet` correspond à un retour sur un code block, `contextual` à un retour au niveau de la page, `thumbs_only` est un vote pouce vers le haut/bas." }, "status": { "type": "string", @@ -73,7 +74,7 @@ "resolved", "dismissed" ], - "description": "Current review status of the feedback." + "description": "Statut actuel de révision du retour." } }, "required": [ @@ -90,33 +91,34 @@ "properties": { "id": { "type": "string", - "description": "Unique feedback identifier." + "description": "Identifiant unique du retour." }, "path": { "type": "string", - "description": "The path or URL to the source document." + "description": "Chemin ou URL du document source." }, "comment": { "type": [ "string", "null" ], - "description": "Text of the user's feedback comment." + "description": "Texte du commentaire de l’utilisateur." }, "createdAt": { "type": [ "string", "null" ], - "description": "Timestamp when the feedback was submitted." + "description": "Horodatage de l’envoi du retour." }, "source": { "type": "string", "enum": [ "code_snippet", - "contextual" + "contextual", + "thumbs_only" ], - "description": "Where the feedback originated. `code_snippet` is feedback on a code block, `contextual` is page-level feedback." + "description": "Source du retour. `code_snippet` correspond à un retour sur un code block, `contextual` à un retour au niveau de la page, `thumbs_only` est un vote pouce vers le haut/bas." }, "status": { "type": "string", @@ -126,18 +128,18 @@ "resolved", "dismissed" ], - "description": "Current review status of the feedback." + "description": "Statut actuel d’examen du retour." }, "helpful": { "type": "boolean", - "description": "Whether the user found the content helpful." + "description": "Indique si l’utilisateur a jugé le contenu utile." }, "contact": { "type": [ "string", "null" ], - "description": "Email address the user provided for follow-up." + "description": "Adresse e-mail fournie par l’utilisateur pour le suivi." } }, "required": [ @@ -156,33 +158,34 @@ "properties": { "id": { "type": "string", - "description": "Unique feedback identifier." + "description": "Identifiant unique du retour." }, "path": { "type": "string", - "description": "The path or URL to the source document." + "description": "Chemin ou URL du document source." }, "comment": { "type": [ "string", "null" ], - "description": "Text of the user's feedback comment." + "description": "Texte du commentaire de l’utilisateur." }, "createdAt": { "type": [ "string", "null" ], - "description": "Timestamp when the feedback was submitted." + "description": "Horodatage de l’envoi du retour." }, "source": { "type": "string", "enum": [ "code_snippet", - "contextual" + "contextual", + "thumbs_only" ], - "description": "Where the feedback originated. `code_snippet` is feedback on a code block, `contextual` is page-level feedback." + "description": "Origine du retour. `code_snippet` correspond à un retour sur un code block, `contextual` à un retour concernant la page entière, `thumbs_only` est un vote pouce vers le haut/bas." }, "status": { "type": "string", @@ -192,25 +195,25 @@ "resolved", "dismissed" ], - "description": "Current review status of the feedback." + "description": "Statut actuel d’examen du retour." }, "code": { "type": "string", - "description": "The code snippet the feedback relates to." + "description": "Extrait de code auquel le retour se rapporte." }, "filename": { "type": [ "string", "null" ], - "description": "Filename associated with the code snippet." + "description": "Nom de fichier associé à l’extrait de code." }, "lang": { "type": [ "string", "null" ], - "description": "Programming language of the code snippet." + "description": "Langage de programmation de l’extrait de code." } }, "required": [ @@ -233,11 +236,11 @@ "string", "null" ], - "description": "Cursor to retrieve the next page of results. Null if no more results." + "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": "Whether additional results are available beyond this page." + "description": "Indique si des résultats supplémentaires sont disponibles au-delà de cette page." } }, "required": [ @@ -251,17 +254,17 @@ "properties": { "error": { "type": "string", - "description": "Error message describing what went wrong." + "description": "Message d’erreur décrivant ce qui s’est mal passé." }, "details": { "type": "array", - "description": "Additional details about the error.", + "description": "Détails supplémentaires sur l’erreur.", "items": { "type": "object", "properties": { "message": { "type": "string", - "description": "Description of a specific validation or processing error." + "description": "Description d’une erreur spécifique de validation ou de traitement." } }, "required": [ @@ -279,39 +282,39 @@ "properties": { "conversations": { "type": "array", - "description": "List of assistant conversations.", + "description": "Liste des conversations de l’Assistant.", "items": { "type": "object", "properties": { "id": { "type": "string", - "description": "Unique conversation identifier." + "description": "Identifiant unique de la conversation." }, "timestamp": { "type": "string", - "description": "Timestamp when the conversation occurred." + "description": "Horodatage de la conversation." }, "query": { "type": "string", - "description": "The user's question to the assistant." + "description": "La question de l’utilisateur adressée à l’Assistant." }, "response": { "type": "string", - "description": "The assistant's response." + "description": "La réponse générée par l’Assistant." }, "sources": { "type": "array", - "description": "Documentation pages referenced in the response.", + "description": "Pages de documentation référencées dans la réponse.", "items": { "type": "object", "properties": { "title": { "type": "string", - "description": "Title of the referenced documentation page." + "description": "Titre de la page de documentation référencée." }, "url": { "type": "string", - "description": "URL of the referenced documentation page." + "description": "URL de la page de documentation référencée." } }, "required": [ @@ -325,7 +328,7 @@ "string", "null" ], - "description": "Auto-assigned category grouping for the conversation, if applicable." + "description": "Catégorie de regroupement automatiquement attribuée à la conversation, le cas échéant." } }, "required": [ @@ -343,11 +346,11 @@ "string", "null" ], - "description": "Cursor to retrieve the next page of results. Null if no more results." + "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": "Whether additional results are available beyond this page." + "description": "Indique si des résultats supplémentaires sont disponibles au‑delà de cette page." } }, "required": [ @@ -355,232 +358,6 @@ "nextCursor", "hasMore" ] - }, - "FeedbackGroupedByPageResponse": { - "type": "object", - "properties": { - "feedback": { - "type": "array", - "description": "Feedback counts aggregated by documentation page path.", - "items": { - "type": "object", - "properties": { - "path": { - "type": "string", - "description": "The documentation page path." - }, - "thumbsUp": { - "type": "number", - "description": "Number of positive (thumbs up) contextual feedback entries." - }, - "thumbsDown": { - "type": "number", - "description": "Number of negative (thumbs down) contextual feedback entries." - }, - "code": { - "type": "number", - "description": "Number of code snippet feedback entries." - }, - "total": { - "type": "number", - "description": "Total feedback entries for this page." - } - }, - "required": [ - "path", - "thumbsUp", - "thumbsDown", - "code", - "total" - ] - } - }, - "hasMore": { - "type": "boolean", - "description": "Whether additional results are available beyond this page." - } - }, - "required": [ - "feedback", - "hasMore" - ] - }, - "SearchesResponse": { - "type": "object", - "properties": { - "searches": { - "type": "array", - "description": "Search terms ordered by hit count descending.", - "items": { - "type": "object", - "properties": { - "searchQuery": { - "type": "string", - "description": "The search term entered by users." - }, - "hits": { - "type": "number", - "description": "Number of times this term was searched." - }, - "ctr": { - "type": "number", - "description": "Click-through rate for this search term." - }, - "topClickedPage": { - "type": [ - "string", - "null" - ], - "description": "The most-clicked result path for this query, if any." - }, - "lastSearchedAt": { - "type": "string", - "description": "Timestamp of the last time this term was searched." - } - }, - "required": [ - "searchQuery", - "hits", - "ctr", - "topClickedPage", - "lastSearchedAt" - ] - } - }, - "totalSearches": { - "type": "integer", - "minimum": 0, - "description": "Total count of search events in the requested date range (sum of all hits, not distinct queries)." - }, - "nextCursor": { - "type": [ - "string", - "null" - ], - "description": "Opaque pagination cursor for the next page. Null if no more results." - } - }, - "required": [ - "searches", - "totalSearches", - "nextCursor" - ] - }, - "ViewsTrafficTotals": { - "type": "object", - "properties": { - "human": { - "type": "number", - "description": "Site-wide content view events from human traffic." - }, - "ai": { - "type": "number", - "description": "Site-wide content view events from AI bot traffic." - }, - "total": { - "type": "number", - "description": "Site-wide content view events." - } - }, - "required": ["human", "ai", "total"] - }, - "ViewsByPageResponse": { - "type": "object", - "properties": { - "totals": { - "$ref": "#/components/schemas/ViewsTrafficTotals", - "description": "Site-wide view totals for the date range." - }, - "views": { - "type": "array", - "description": "Per-page view counts.", - "items": { - "type": "object", - "properties": { - "path": { - "type": "string", - "description": "The documentation page path." - }, - "human": { - "type": "number", - "description": "Content view events on this path from human traffic." - }, - "ai": { - "type": "number", - "description": "Content view events on this path from AI bot traffic." - }, - "total": { - "type": "number", - "description": "Total content view events on this path." - } - }, - "required": ["path", "human", "ai", "total"] - } - }, - "hasMore": { - "type": "boolean", - "description": "Whether additional results are available beyond this page." - } - }, - "required": ["totals", "views", "hasMore"] - }, - "VisitorsTrafficTotals": { - "type": "object", - "properties": { - "human": { - "type": "number", - "description": "Site-wide unique visitors from human traffic." - }, - "ai": { - "type": "number", - "description": "Site-wide unique visitors from AI bot traffic." - }, - "total": { - "type": "number", - "description": "Site-wide approximate distinct visitors with any qualifying view (deduplicated across human and AI)." - } - }, - "required": ["human", "ai", "total"] - }, - "VisitorsByPageResponse": { - "type": "object", - "properties": { - "totals": { - "$ref": "#/components/schemas/VisitorsTrafficTotals", - "description": "Site-wide unique visitor totals for the date range." - }, - "visitors": { - "type": "array", - "description": "Per-page visitor counts.", - "items": { - "type": "object", - "properties": { - "path": { - "type": "string", - "description": "The documentation page path." - }, - "human": { - "type": "number", - "description": "Unique visitors from human traffic." - }, - "ai": { - "type": "number", - "description": "Unique visitors from AI bot traffic." - }, - "total": { - "type": "number", - "description": "Approximate distinct visitors with any qualifying view on this path (deduplicated across human and AI)." - } - }, - "required": ["path", "human", "ai", "total"] - } - }, - "hasMore": { - "type": "boolean", - "description": "Whether additional results are available beyond this page." - } - }, - "required": ["totals", "visitors", "hasMore"] } }, "parameters": { @@ -597,8 +374,8 @@ "paths": { "/v1/analytics/{projectId}/feedback": { "get": { - "summary": "Get user feedback", - "description": "Returns paginated user feedback with optional filtering", + "summary": "Récupérer les retours des utilisateurs", + "description": "Renvoie des retours d’utilisateurs paginés avec des filtres facultatifs", "tags": [ "Analytics" ], @@ -614,7 +391,7 @@ { "schema": { "type": "string", - "description": "Date in ISO 8601 or YYYY-MM-DD format", + "description": "Date au format ISO 8601 ou AAAA-MM-JJ", "example": "2024-01-01" }, "required": false, @@ -624,7 +401,7 @@ { "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.", + "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, @@ -636,9 +413,10 @@ "type": "string", "enum": [ "code_snippet", - "contextual" + "contextual", + "thumbs_only" ], - "description": "Filter by feedback source" + "description": "Filtrer par source des retours utilisateurs" }, "required": false, "name": "source", @@ -647,7 +425,7 @@ { "schema": { "type": "string", - "description": "Comma-separated list of statuses to filter by" + "description": "Liste de statuts séparés par des virgules pour le filtrage" }, "required": false, "name": "status", @@ -659,7 +437,7 @@ "minimum": 1, "maximum": 100, "default": 50, - "description": "Max results per page" + "description": "Nombre maximal de résultats par page" }, "required": false, "name": "limit", @@ -668,7 +446,7 @@ { "schema": { "type": "string", - "description": "Pagination cursor" + "description": "Curseur de pagination" }, "required": false, "name": "cursor", @@ -677,7 +455,7 @@ ], "responses": { "200": { - "description": "Feedback data with pagination", + "description": "Données de retours utilisateurs paginées", "content": { "application/json": { "schema": { @@ -687,112 +465,7 @@ } }, "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}/feedback/by-page": { - "get": { - "summary": "Get feedback by page", - "description": "Returns feedback counts aggregated by documentation page path (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": "number", - "minimum": 1, - "maximum": 100, - "default": 10, - "description": "Max results per page" - }, - "required": false, - "name": "limit", - "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" - } - ], - "responses": { - "200": { - "description": "Per-page feedback aggregates with pagination flag", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/FeedbackGroupedByPageResponse" - } - } - } - }, - "400": { - "description": "Invalid query parameters", + "description": "Paramètres de requête invalides", "content": { "application/json": { "schema": { @@ -802,7 +475,7 @@ } }, "500": { - "description": "Server error", + "description": "Erreur serveur", "content": { "application/json": { "schema": { @@ -816,8 +489,8 @@ }, "/v1/analytics/{projectId}/assistant": { "get": { - "summary": "Get assistant conversations", - "description": "Returns paginated AI assistant conversation history", + "summary": "Récupérer les conversations de l’Assistant", + "description": "Renvoie l’historique de conversation paginé de l’Assistant IA", "tags": [ "Analytics" ], @@ -833,7 +506,7 @@ { "schema": { "type": "string", - "description": "Date in ISO 8601 or YYYY-MM-DD format", + "description": "Date au format ISO 8601 ou AAAA-MM-JJ", "example": "2024-01-01" }, "required": false, @@ -843,7 +516,7 @@ { "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.", + "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, @@ -856,7 +529,7 @@ "minimum": 1, "maximum": 1000, "default": 100, - "description": "Max results per page" + "description": "Nombre maximal de résultats par page" }, "required": false, "name": "limit", @@ -866,7 +539,7 @@ "schema": { "type": "string", "format": "ulid", - "description": "Pagination cursor (ULID format)" + "description": "Curseur de pagination (format ULID)" }, "required": false, "name": "cursor", @@ -875,7 +548,7 @@ ], "responses": { "200": { - "description": "Conversation data with pagination", + "description": "Données de conversation paginées", "content": { "application/json": { "schema": { @@ -885,287 +558,7 @@ } }, "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}/searches": { - "get": { - "summary": "Get search queries", - "description": "Returns paginated documentation search terms for the date range, ordered by hit count descending. Each row includes click-through rate, the most-clicked result path for that query (if any), and the last time the term was searched. `totalSearches` is the total number of search query events in the same date range (sum of all hits, not distinct queries).", - "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": "number", - "minimum": 1, - "maximum": 100, - "default": 50, - "description": "Max search terms per page (ordered by hit count descending)" - }, - "required": false, - "name": "limit", - "in": "query" - }, - { - "schema": { - "type": "string", - "description": "Opaque pagination cursor from the previous response" - }, - "required": false, - "name": "cursor", - "in": "query" - } - ], - "responses": { - "200": { - "description": "Search term aggregates with pagination", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/SearchesResponse" - } - } - } - }, - "400": { - "description": "Invalid query parameters or cursor", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/AnalyticsErrorResponse" - } - } - } - }, - "500": { - "description": "Server error", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/AnalyticsErrorResponse" - } - } - } - } - } - } - }, - "/v1/analytics/{projectId}/views": { - "get": { - "summary": "Get page views", - "description": "Returns per-path and site-wide content view event counts, split by human and AI traffic.", - "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": "integer", - "minimum": 1, - "maximum": 250, - "default": 50, - "description": "Max results per page (1-250, default 50). Increment offset by limit while hasMore is true to paginate." - }, - "required": false, - "name": "limit", - "in": "query" - }, - { - "schema": { - "type": "integer", - "minimum": 0, - "default": 0, - "description": "Number of rows to skip. Use offset = (page - 1) * limit for page-based access." - }, - "required": false, - "name": "offset", - "in": "query" - } - ], - "responses": { - "200": { - "description": "Site-wide and per-path content view event counts", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ViewsByPageResponse" - } - } - } - }, - "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}/visitors": { - "get": { - "summary": "Get unique visitors", - "description": "Returns per-path and site-wide approximate distinct visitors by traffic type. The `total` field is deduplicated across human and AI (union of distinct visitor IDs with any qualifying content view).", - "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": "integer", - "minimum": 1, - "maximum": 250, - "default": 50, - "description": "Max results per page (1-250, default 50). Increment offset by limit while hasMore is true to paginate." - }, - "required": false, - "name": "limit", - "in": "query" - }, - { - "schema": { - "type": "integer", - "minimum": 0, - "default": 0, - "description": "Number of rows to skip. Use offset = (page - 1) * limit for page-based access." - }, - "required": false, - "name": "offset", - "in": "query" - } - ], - "responses": { - "200": { - "description": "Site-wide totals and per-path visitor counts", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/VisitorsByPageResponse" - } - } - } - }, - "400": { - "description": "Invalid query parameters", + "description": "Paramètres de requête invalides", "content": { "application/json": { "schema": { @@ -1175,7 +568,7 @@ } }, "500": { - "description": "Server error", + "description": "Erreur serveur", "content": { "application/json": { "schema": { diff --git a/fr/api/analytics/feedback-by-page.mdx b/fr/api/analytics/feedback-by-page.mdx deleted file mode 100644 index fdb199219..000000000 --- a/fr/api/analytics/feedback-by-page.mdx +++ /dev/null @@ -1,36 +0,0 @@ ---- -title: "Obtenir les retours par page" -description: "Récupérez les comptages de retours utilisateurs agrégés par page de documentation, incluant les évaluations pouce levé/baissé et les retours sur les extraits de code." -openapi: /fr/analytics.openapi.json GET /v1/analytics/{projectId}/feedback/by-page -keywords: ["analytics", "retours", "export", "par page", "agrégé"] ---- - -
- ## Utilisation -
- -Utilisez cet endpoint pour exporter les retours utilisateurs agrégés par chemin de page de documentation. Chaque entrée affiche le nombre total de retours pour une page, ventilé par type. - -Parcourez les résultats à l'aide de l'indicateur `hasMore` dans la réponse. - -
- ## Filtrage -
- -Filtrez les retours par : - -- **Plage de dates** : utilisez `dateFrom` et `dateTo` pour limiter les résultats à une période donnée -- **Source** : filtrez par type de retour, `code_snippet` ou `contextual` -- **Statut** : filtrez par des valeurs de statut comme `pending`, `in_progress`, `resolved` ou `dismissed` - -
- ## Données de la réponse -
- -Chaque entrée de page inclut : - -- **path** : le chemin de la page de documentation -- **thumbsUp** : nombre de retours contextuels positifs -- **thumbsDown** : nombre de retours contextuels négatifs -- **code** : nombre de retours sur des extraits de code -- **total** : nombre total de retours pour la page diff --git a/fr/api/analytics/searches.mdx b/fr/api/analytics/searches.mdx deleted file mode 100644 index af75badb0..000000000 --- a/fr/api/analytics/searches.mdx +++ /dev/null @@ -1,34 +0,0 @@ ---- -title: "Obtenir les requêtes de recherche" -description: "Récupérez les termes de recherche de la documentation avec le nombre de requêtes, les taux de clics et les pages les plus cliquées." -openapi: /fr/analytics.openapi.json GET /v1/analytics/{projectId}/searches -keywords: ["analytics", "recherche", "export", "requêtes", "termes de recherche"] ---- - -
- ## Utilisation -
- -Utilisez cet endpoint pour exporter les données analytiques de recherche de votre documentation. Les résultats sont classés par nombre de requêtes décroissant, montrant les termes les plus recherchés par vos utilisateurs. - -Parcourez les résultats à l'aide du paramètre `nextCursor` renvoyé dans la réponse. Continuez à récupérer les données tant que `nextCursor` n'est pas null. - -
- ## Filtrage -
- -Filtrez les données de recherche par plage de dates à l'aide des paramètres `dateFrom` et `dateTo`. - -
- ## Données de la réponse -
- -Chaque entrée de terme de recherche inclut : - -- **searchQuery** : le terme de recherche saisi par les utilisateurs -- **hits** : nombre de fois que ce terme a été recherché -- **ctr** : taux de clics pour ce terme de recherche -- **topClickedPage** : le chemin du résultat le plus cliqué pour cette requête, le cas échéant -- **lastSearchedAt** : horodatage de la dernière recherche de ce terme - -La réponse inclut également `totalSearches`, qui correspond au nombre total d'événements de recherche dans la période demandée (somme de tous les hits, pas le nombre de requêtes distinctes). diff --git a/fr/api/analytics/views.mdx b/fr/api/analytics/views.mdx deleted file mode 100644 index d32360ba2..000000000 --- a/fr/api/analytics/views.mdx +++ /dev/null @@ -1,31 +0,0 @@ ---- -title: "Obtenir les vues de pages" -description: "Récupérez les compteurs de vues de contenu par page et à l'échelle du site, répartis entre trafic humain et IA." -openapi: /fr/analytics.openapi.json GET /v1/analytics/{projectId}/views -keywords: ["analytics", "vues", "pages vues", "trafic", "export"] ---- - -
- ## Utilisation -
- -Utilisez cet endpoint pour exporter les données analytiques de vues de pages. Les résultats incluent les totaux à l'échelle du site et les détails par page, répartis entre trafic humain et IA. - -Parcourez les résultats avec une pagination basée sur l'offset. Incrémentez `offset` de `limit` tant que `hasMore` est true. - -
- ## Filtrage -
- -Filtrez les données de vues par plage de dates à l'aide des paramètres `dateFrom` et `dateTo`. - -
- ## Données de la réponse -
- -La réponse inclut un objet `totals` avec les agrégats à l'échelle du site et un tableau `views` avec les données par page. Chaque entrée inclut : - -- **path** : le chemin de la page de documentation -- **human** : événements de vue de contenu provenant du trafic humain -- **ai** : événements de vue de contenu provenant du trafic IA -- **total** : total des événements de vue de contenu sur cette page diff --git a/fr/api/analytics/visitors.mdx b/fr/api/analytics/visitors.mdx deleted file mode 100644 index 4b7c6abb9..000000000 --- a/fr/api/analytics/visitors.mdx +++ /dev/null @@ -1,31 +0,0 @@ ---- -title: "Obtenir les visiteurs uniques" -description: "Récupérez les compteurs approximatifs de visiteurs uniques par page et à l'échelle du site, répartis entre trafic humain et IA." -openapi: /fr/analytics.openapi.json GET /v1/analytics/{projectId}/visitors -keywords: ["analytics", "visiteurs", "visiteurs uniques", "trafic", "export"] ---- - -
- ## Utilisation -
- -Utilisez cet endpoint pour exporter les données analytiques de visiteurs uniques. Les résultats incluent les totaux à l'échelle du site et les détails par page, répartis entre trafic humain et IA. Le champ `total` est dédupliqué entre le trafic humain et IA. - -Parcourez les résultats avec une pagination basée sur l'offset. Incrémentez `offset` de `limit` tant que `hasMore` est true. - -
- ## Filtrage -
- -Filtrez les données de visiteurs par plage de dates à l'aide des paramètres `dateFrom` et `dateTo`. - -
- ## Données de la réponse -
- -La réponse inclut un objet `totals` avec les agrégats à l'échelle du site et un tableau `visitors` avec les données par page. Chaque entrée inclut : - -- **path** : le chemin de la page de documentation -- **human** : visiteurs uniques provenant du trafic humain -- **ai** : visiteurs uniques provenant du trafic IA -- **total** : visiteurs distincts approximatifs (dédupliqués entre humain et IA) diff --git a/zh/analytics.openapi.json b/zh/analytics.openapi.json index 232939b1b..235fcc0e8 100644 --- a/zh/analytics.openapi.json +++ b/zh/analytics.openapi.json @@ -3,12 +3,12 @@ "info": { "title": "Mintlify Analytics Export API", "version": "1.0.0", - "description": "API for exporting documentation analytics data" + "description": "用于导出文档 Analytics 数据的 API" }, "servers": [ { "url": "https://api.mintlify.com", - "description": "Production" + "description": "生产环境" } ], "components": { @@ -16,20 +16,20 @@ "bearerAuth": { "type": "http", "scheme": "bearer", - "description": "The Authorization header expects a Bearer token. Use an admin API key (prefixed with `mint_`). This is a server-side secret key. Generate one on the [API keys page](https://dashboard.mintlify.com/settings/organization/api-keys) in your dashboard." + "description": "Authorization 请求头需要使用 Bearer Token。请使用管理员 API key（以 `mint_` 开头）。这是仅供服务端使用的密钥。你可以在控制台的 [API keys 页面](https://dashboard.mintlify.com/settings/organization/api-keys) 中生成。" } }, "schemas": { "projectId": { "type": "string", - "description": "Your project ID. Can be copied from the [API keys](https://dashboard.mintlify.com/settings/organization/api-keys) page in your dashboard." + "description": "你的项目 ID，可在控制台的 [API keys](https://dashboard.mintlify.com/settings/organization/api-keys) 页面中复制。" }, "FeedbackResponse": { "type": "object", "properties": { "feedback": { "type": "array", - "description": "List of feedback entries.", + "description": "反馈条目的列表。", "items": { "anyOf": [ { @@ -37,33 +37,34 @@ "properties": { "id": { "type": "string", - "description": "Unique feedback identifier." + "description": "反馈的唯一标识符。" }, "path": { "type": "string", - "description": "The path or URL to the source document." + "description": "源文档的路径或 URL。" }, "comment": { "type": [ "string", "null" ], - "description": "Text of the user's feedback comment." + "description": "用户提交的反馈内容。" }, "createdAt": { "type": [ "string", "null" ], - "description": "Timestamp when the feedback was submitted." + "description": "提交该反馈时的时间戳。" }, "source": { "type": "string", "enum": [ "code_snippet", - "contextual" + "contextual", + "thumbs_only" ], - "description": "Where the feedback originated. `code_snippet` is feedback on a code block, `contextual` is page-level feedback." + "description": "反馈的来源类型。`code_snippet` 表示针对代码块的反馈，`contextual` 表示页面级别的反馈，`thumbs_only` 表示点赞/点踩投票。" }, "status": { "type": "string", @@ -73,7 +74,7 @@ "resolved", "dismissed" ], - "description": "Current review status of the feedback." + "description": "该反馈当前的审核状态。" } }, "required": [ @@ -90,33 +91,34 @@ "properties": { "id": { "type": "string", - "description": "Unique feedback identifier." + "description": "该反馈的唯一标识符。" }, "path": { "type": "string", - "description": "The path or URL to the source document." + "description": "源文档的路径或 URL。" }, "comment": { "type": [ "string", "null" ], - "description": "Text of the user's feedback comment." + "description": "用户提交的反馈内容。" }, "createdAt": { "type": [ "string", "null" ], - "description": "Timestamp when the feedback was submitted." + "description": "提交该反馈时的时间戳。" }, "source": { "type": "string", "enum": [ "code_snippet", - "contextual" + "contextual", + "thumbs_only" ], - "description": "Where the feedback originated. `code_snippet` is feedback on a code block, `contextual` is page-level feedback." + "description": "反馈的来源类型。`code_snippet` 表示针对代码块的反馈，`contextual` 表示页面级别的反馈，`thumbs_only` 表示点赞/点踩投票。" }, "status": { "type": "string", @@ -126,18 +128,18 @@ "resolved", "dismissed" ], - "description": "Current review status of the feedback." + "description": "反馈当前的审核状态。" }, "helpful": { "type": "boolean", - "description": "Whether the user found the content helpful." + "description": "用户是否认为该内容有帮助。" }, "contact": { "type": [ "string", "null" ], - "description": "Email address the user provided for follow-up." + "description": "用户提供的用于后续联系的电子邮件地址。" } }, "required": [ @@ -156,33 +158,34 @@ "properties": { "id": { "type": "string", - "description": "Unique feedback identifier." + "description": "反馈的唯一标识符。" }, "path": { "type": "string", - "description": "The path or URL to the source document." + "description": "源文档的路径或 URL。" }, "comment": { "type": [ "string", "null" ], - "description": "Text of the user's feedback comment." + "description": "用户反馈评论的正文内容。" }, "createdAt": { "type": [ "string", "null" ], - "description": "Timestamp when the feedback was submitted." + "description": "提交该反馈时的时间戳。" }, "source": { "type": "string", "enum": [ "code_snippet", - "contextual" + "contextual", + "thumbs_only" ], - "description": "Where the feedback originated. `code_snippet` is feedback on a code block, `contextual` is page-level feedback." + "description": "反馈的来源类型。`code_snippet` 表示针对代码块的反馈，`contextual` 表示针对整页的反馈，`thumbs_only` 表示点赞/点踩投票。" }, "status": { "type": "string", @@ -192,25 +195,25 @@ "resolved", "dismissed" ], - "description": "Current review status of the feedback." + "description": "反馈当前的审核状态。" }, "code": { "type": "string", - "description": "The code snippet the feedback relates to." + "description": "与该反馈相关的代码片段。" }, "filename": { "type": [ "string", "null" ], - "description": "Filename associated with the code snippet." + "description": "与代码片段关联的文件名。" }, "lang": { "type": [ "string", "null" ], - "description": "Programming language of the code snippet." + "description": "代码片段所使用的编程语言。" } }, "required": [ @@ -233,11 +236,11 @@ "string", "null" ], - "description": "Cursor to retrieve the next page of results. Null if no more results." + "description": "用于获取下一页结果的游标。如果没有更多结果，则为 null。" }, "hasMore": { "type": "boolean", - "description": "Whether additional results are available beyond this page." + "description": "当前页之后是否还有更多结果。" } }, "required": [ @@ -251,17 +254,17 @@ "properties": { "error": { "type": "string", - "description": "Error message describing what went wrong." + "description": "描述错误原因的错误信息。" }, "details": { "type": "array", - "description": "Additional details about the error.", + "description": "关于该错误的其他详细信息。", "items": { "type": "object", "properties": { "message": { "type": "string", - "description": "Description of a specific validation or processing error." + "description": "对某个特定校验或处理错误的说明。" } }, "required": [ @@ -279,39 +282,39 @@ "properties": { "conversations": { "type": "array", - "description": "List of assistant conversations.", + "description": "AI 助手会话列表。", "items": { "type": "object", "properties": { "id": { "type": "string", - "description": "Unique conversation identifier." + "description": "会话的唯一标识符。" }, "timestamp": { "type": "string", - "description": "Timestamp when the conversation occurred." + "description": "会话发生时的时间戳。" }, "query": { "type": "string", - "description": "The user's question to the assistant." + "description": "用户向 AI 助手提出的问题。" }, "response": { "type": "string", - "description": "The assistant's response." + "description": "AI 助手的回答。" }, "sources": { "type": "array", - "description": "Documentation pages referenced in the response.", + "description": "在回答中被引用的文档页面。", "items": { "type": "object", "properties": { "title": { "type": "string", - "description": "Title of the referenced documentation page." + "description": "被引用文档页面的标题。" }, "url": { "type": "string", - "description": "URL of the referenced documentation page." + "description": "被引用文档页面的 URL。" } }, "required": [ @@ -325,7 +328,7 @@ "string", "null" ], - "description": "Auto-assigned category grouping for the conversation, if applicable." + "description": "会话自动分配的分类分组（如适用）。" } }, "required": [ @@ -343,11 +346,11 @@ "string", "null" ], - "description": "Cursor to retrieve the next page of results. Null if no more results." + "description": "用于获取下一页结果的游标；如果没有更多结果则为 null。" }, "hasMore": { "type": "boolean", - "description": "Whether additional results are available beyond this page." + "description": "指示在当前页之外是否还有更多可用结果。" } }, "required": [ @@ -355,232 +358,6 @@ "nextCursor", "hasMore" ] - }, - "FeedbackGroupedByPageResponse": { - "type": "object", - "properties": { - "feedback": { - "type": "array", - "description": "Feedback counts aggregated by documentation page path.", - "items": { - "type": "object", - "properties": { - "path": { - "type": "string", - "description": "The documentation page path." - }, - "thumbsUp": { - "type": "number", - "description": "Number of positive (thumbs up) contextual feedback entries." - }, - "thumbsDown": { - "type": "number", - "description": "Number of negative (thumbs down) contextual feedback entries." - }, - "code": { - "type": "number", - "description": "Number of code snippet feedback entries." - }, - "total": { - "type": "number", - "description": "Total feedback entries for this page." - } - }, - "required": [ - "path", - "thumbsUp", - "thumbsDown", - "code", - "total" - ] - } - }, - "hasMore": { - "type": "boolean", - "description": "Whether additional results are available beyond this page." - } - }, - "required": [ - "feedback", - "hasMore" - ] - }, - "SearchesResponse": { - "type": "object", - "properties": { - "searches": { - "type": "array", - "description": "Search terms ordered by hit count descending.", - "items": { - "type": "object", - "properties": { - "searchQuery": { - "type": "string", - "description": "The search term entered by users." - }, - "hits": { - "type": "number", - "description": "Number of times this term was searched." - }, - "ctr": { - "type": "number", - "description": "Click-through rate for this search term." - }, - "topClickedPage": { - "type": [ - "string", - "null" - ], - "description": "The most-clicked result path for this query, if any." - }, - "lastSearchedAt": { - "type": "string", - "description": "Timestamp of the last time this term was searched." - } - }, - "required": [ - "searchQuery", - "hits", - "ctr", - "topClickedPage", - "lastSearchedAt" - ] - } - }, - "totalSearches": { - "type": "integer", - "minimum": 0, - "description": "Total count of search events in the requested date range (sum of all hits, not distinct queries)." - }, - "nextCursor": { - "type": [ - "string", - "null" - ], - "description": "Opaque pagination cursor for the next page. Null if no more results." - } - }, - "required": [ - "searches", - "totalSearches", - "nextCursor" - ] - }, - "ViewsTrafficTotals": { - "type": "object", - "properties": { - "human": { - "type": "number", - "description": "Site-wide content view events from human traffic." - }, - "ai": { - "type": "number", - "description": "Site-wide content view events from AI bot traffic." - }, - "total": { - "type": "number", - "description": "Site-wide content view events." - } - }, - "required": ["human", "ai", "total"] - }, - "ViewsByPageResponse": { - "type": "object", - "properties": { - "totals": { - "$ref": "#/components/schemas/ViewsTrafficTotals", - "description": "Site-wide view totals for the date range." - }, - "views": { - "type": "array", - "description": "Per-page view counts.", - "items": { - "type": "object", - "properties": { - "path": { - "type": "string", - "description": "The documentation page path." - }, - "human": { - "type": "number", - "description": "Content view events on this path from human traffic." - }, - "ai": { - "type": "number", - "description": "Content view events on this path from AI bot traffic." - }, - "total": { - "type": "number", - "description": "Total content view events on this path." - } - }, - "required": ["path", "human", "ai", "total"] - } - }, - "hasMore": { - "type": "boolean", - "description": "Whether additional results are available beyond this page." - } - }, - "required": ["totals", "views", "hasMore"] - }, - "VisitorsTrafficTotals": { - "type": "object", - "properties": { - "human": { - "type": "number", - "description": "Site-wide unique visitors from human traffic." - }, - "ai": { - "type": "number", - "description": "Site-wide unique visitors from AI bot traffic." - }, - "total": { - "type": "number", - "description": "Site-wide approximate distinct visitors with any qualifying view (deduplicated across human and AI)." - } - }, - "required": ["human", "ai", "total"] - }, - "VisitorsByPageResponse": { - "type": "object", - "properties": { - "totals": { - "$ref": "#/components/schemas/VisitorsTrafficTotals", - "description": "Site-wide unique visitor totals for the date range." - }, - "visitors": { - "type": "array", - "description": "Per-page visitor counts.", - "items": { - "type": "object", - "properties": { - "path": { - "type": "string", - "description": "The documentation page path." - }, - "human": { - "type": "number", - "description": "Unique visitors from human traffic." - }, - "ai": { - "type": "number", - "description": "Unique visitors from AI bot traffic." - }, - "total": { - "type": "number", - "description": "Approximate distinct visitors with any qualifying view on this path (deduplicated across human and AI)." - } - }, - "required": ["path", "human", "ai", "total"] - } - }, - "hasMore": { - "type": "boolean", - "description": "Whether additional results are available beyond this page." - } - }, - "required": ["totals", "visitors", "hasMore"] } }, "parameters": { @@ -597,8 +374,8 @@ "paths": { "/v1/analytics/{projectId}/feedback": { "get": { - "summary": "Get user feedback", - "description": "Returns paginated user feedback with optional filtering", + "summary": "获取用户反馈列表", + "description": "返回按页划分的用户反馈，并支持可选筛选条件", "tags": [ "Analytics" ], @@ -614,7 +391,7 @@ { "schema": { "type": "string", - "description": "Date in ISO 8601 or YYYY-MM-DD format", + "description": "ISO 8601 或 YYYY-MM-DD 格式的日期", "example": "2024-01-01" }, "required": false, @@ -624,7 +401,7 @@ { "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.", + "description": "ISO 8601 或 YYYY-MM-DD 格式的日期。`dateTo` 为不包含在内的上界。结果包括指定日期之前的所有日期，但不包括指定日期当天。", "example": "2024-01-01" }, "required": false, @@ -636,9 +413,10 @@ "type": "string", "enum": [ "code_snippet", - "contextual" + "contextual", + "thumbs_only" ], - "description": "Filter by feedback source" + "description": "按反馈来源进行筛选" }, "required": false, "name": "source", @@ -647,7 +425,7 @@ { "schema": { "type": "string", - "description": "Comma-separated list of statuses to filter by" + "description": "用于筛选的以逗号分隔的状态列表" }, "required": false, "name": "status", @@ -659,7 +437,7 @@ "minimum": 1, "maximum": 100, "default": 50, - "description": "Max results per page" + "description": "每页返回的最大结果数" }, "required": false, "name": "limit", @@ -668,7 +446,7 @@ { "schema": { "type": "string", - "description": "Pagination cursor" + "description": "分页游标" }, "required": false, "name": "cursor", @@ -677,7 +455,7 @@ ], "responses": { "200": { - "description": "Feedback data with pagination", + "description": "包含分页信息的反馈数据", "content": { "application/json": { "schema": { @@ -687,112 +465,7 @@ } }, "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}/feedback/by-page": { - "get": { - "summary": "Get feedback by page", - "description": "Returns feedback counts aggregated by documentation page path (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": "number", - "minimum": 1, - "maximum": 100, - "default": 10, - "description": "Max results per page" - }, - "required": false, - "name": "limit", - "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" - } - ], - "responses": { - "200": { - "description": "Per-page feedback aggregates with pagination flag", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/FeedbackGroupedByPageResponse" - } - } - } - }, - "400": { - "description": "Invalid query parameters", + "description": "无效的查询参数", "content": { "application/json": { "schema": { @@ -802,7 +475,7 @@ } }, "500": { - "description": "Server error", + "description": "服务器错误", "content": { "application/json": { "schema": { @@ -816,8 +489,8 @@ }, "/v1/analytics/{projectId}/assistant": { "get": { - "summary": "Get assistant conversations", - "description": "Returns paginated AI assistant conversation history", + "summary": "获取 AI 助手会话记录", + "description": "返回分页后的 AI 助手会话历史", "tags": [ "Analytics" ], @@ -833,7 +506,7 @@ { "schema": { "type": "string", - "description": "Date in ISO 8601 or YYYY-MM-DD format", + "description": "ISO 8601 或 YYYY-MM-DD 格式的日期", "example": "2024-01-01" }, "required": false, @@ -843,7 +516,7 @@ { "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.", + "description": "ISO 8601 或 YYYY-MM-DD 格式的日期。`dateTo` 为不包含在内的上限。结果将包含早于该日期的记录，但不包含该日期当天的记录。", "example": "2024-01-01" }, "required": false, @@ -856,7 +529,7 @@ "minimum": 1, "maximum": 1000, "default": 100, - "description": "Max results per page" + "description": "每页返回的最大结果数" }, "required": false, "name": "limit", @@ -866,7 +539,7 @@ "schema": { "type": "string", "format": "ulid", - "description": "Pagination cursor (ULID format)" + "description": "分页游标（ULID 格式）" }, "required": false, "name": "cursor", @@ -875,7 +548,7 @@ ], "responses": { "200": { - "description": "Conversation data with pagination", + "description": "包含分页信息的会话数据", "content": { "application/json": { "schema": { @@ -885,287 +558,7 @@ } }, "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}/searches": { - "get": { - "summary": "Get search queries", - "description": "Returns paginated documentation search terms for the date range, ordered by hit count descending. Each row includes click-through rate, the most-clicked result path for that query (if any), and the last time the term was searched. `totalSearches` is the total number of search query events in the same date range (sum of all hits, not distinct queries).", - "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": "number", - "minimum": 1, - "maximum": 100, - "default": 50, - "description": "Max search terms per page (ordered by hit count descending)" - }, - "required": false, - "name": "limit", - "in": "query" - }, - { - "schema": { - "type": "string", - "description": "Opaque pagination cursor from the previous response" - }, - "required": false, - "name": "cursor", - "in": "query" - } - ], - "responses": { - "200": { - "description": "Search term aggregates with pagination", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/SearchesResponse" - } - } - } - }, - "400": { - "description": "Invalid query parameters or cursor", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/AnalyticsErrorResponse" - } - } - } - }, - "500": { - "description": "Server error", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/AnalyticsErrorResponse" - } - } - } - } - } - } - }, - "/v1/analytics/{projectId}/views": { - "get": { - "summary": "Get page views", - "description": "Returns per-path and site-wide content view event counts, split by human and AI traffic.", - "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": "integer", - "minimum": 1, - "maximum": 250, - "default": 50, - "description": "Max results per page (1-250, default 50). Increment offset by limit while hasMore is true to paginate." - }, - "required": false, - "name": "limit", - "in": "query" - }, - { - "schema": { - "type": "integer", - "minimum": 0, - "default": 0, - "description": "Number of rows to skip. Use offset = (page - 1) * limit for page-based access." - }, - "required": false, - "name": "offset", - "in": "query" - } - ], - "responses": { - "200": { - "description": "Site-wide and per-path content view event counts", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ViewsByPageResponse" - } - } - } - }, - "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}/visitors": { - "get": { - "summary": "Get unique visitors", - "description": "Returns per-path and site-wide approximate distinct visitors by traffic type. The `total` field is deduplicated across human and AI (union of distinct visitor IDs with any qualifying content view).", - "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": "integer", - "minimum": 1, - "maximum": 250, - "default": 50, - "description": "Max results per page (1-250, default 50). Increment offset by limit while hasMore is true to paginate." - }, - "required": false, - "name": "limit", - "in": "query" - }, - { - "schema": { - "type": "integer", - "minimum": 0, - "default": 0, - "description": "Number of rows to skip. Use offset = (page - 1) * limit for page-based access." - }, - "required": false, - "name": "offset", - "in": "query" - } - ], - "responses": { - "200": { - "description": "Site-wide totals and per-path visitor counts", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/VisitorsByPageResponse" - } - } - } - }, - "400": { - "description": "Invalid query parameters", + "description": "无效的查询参数", "content": { "application/json": { "schema": { @@ -1175,7 +568,7 @@ } }, "500": { - "description": "Server error", + "description": "服务器错误", "content": { "application/json": { "schema": { diff --git a/zh/api/analytics/feedback-by-page.mdx b/zh/api/analytics/feedback-by-page.mdx deleted file mode 100644 index a97277afa..000000000 --- a/zh/api/analytics/feedback-by-page.mdx +++ /dev/null @@ -1,36 +0,0 @@ ---- -title: "按页面获取反馈" -description: "获取按文档页面汇总的用户反馈计数，包括点赞/踩评分和代码片段反馈。" -openapi: /zh/analytics.openapi.json GET /v1/analytics/{projectId}/feedback/by-page -keywords: ["Analytics", "反馈", "导出", "按页面", "汇总"] ---- - -
- ## 用法 -
- -使用此端点导出按文档页面路径汇总的用户反馈。每个条目显示某个页面的反馈总数，并按类型进行细分。 - -使用响应中的 `hasMore` 标志对结果进行分页。 - -
- ## 筛选 -
- -可以按以下维度筛选反馈： - -- **日期范围**：使用 `dateFrom` 和 `dateTo` 将结果限定在特定时间段内 -- **来源**：按 `code_snippet` 或 `contextual` 等反馈来源类型进行筛选 -- **状态**：按状态值进行筛选，例如 `pending`、`in_progress`、`resolved` 或 `dismissed` - -
- ## 响应数据 -
- -每个页面条目包含： - -- **path**：文档页面路径 -- **thumbsUp**：正面上下文反馈数量 -- **thumbsDown**：负面上下文反馈数量 -- **code**：代码片段反馈数量 -- **total**：该页面的反馈总数 diff --git a/zh/api/analytics/searches.mdx b/zh/api/analytics/searches.mdx deleted file mode 100644 index 9481383f9..000000000 --- a/zh/api/analytics/searches.mdx +++ /dev/null @@ -1,34 +0,0 @@ ---- -title: "获取搜索查询" -description: "获取文档搜索词及其搜索次数、点击率和最多点击的页面。" -openapi: /zh/analytics.openapi.json GET /v1/analytics/{projectId}/searches -keywords: ["Analytics", "搜索", "导出", "查询", "搜索词"] ---- - -
- ## 使用方法 -
- -使用此端点导出文档搜索分析数据。结果按搜索次数降序排列，展示用户最常搜索的词条。 - -使用响应中返回的 `nextCursor` 参数对结果进行分页。当 `nextCursor` 不为 null 时继续获取。 - -
- ## 筛选 -
- -使用 `dateFrom` 和 `dateTo` 参数按日期范围过滤搜索数据。 - -
- ## 响应数据 -
- -每个搜索词条目包含： - -- **searchQuery**：用户输入的搜索词 -- **hits**：该词被搜索的次数 -- **ctr**：该搜索词的点击率 -- **topClickedPage**：该查询中被点击最多的结果页面路径（如果有） -- **lastSearchedAt**：该词最后一次被搜索的时间戳 - -响应还包含 `totalSearches`，即请求日期范围内所有搜索事件的总数（所有 hits 的总和，而非不同查询的数量）。 diff --git a/zh/api/analytics/views.mdx b/zh/api/analytics/views.mdx deleted file mode 100644 index 44e84a650..000000000 --- a/zh/api/analytics/views.mdx +++ /dev/null @@ -1,31 +0,0 @@ ---- -title: "获取页面浏览量" -description: "获取按页面和全站的内容浏览事件计数，按人类和 AI 流量分类。" -openapi: /zh/analytics.openapi.json GET /v1/analytics/{projectId}/views -keywords: ["Analytics", "浏览量", "页面浏览", "流量", "导出"] ---- - -
- ## 使用方法 -
- -使用此端点导出页面浏览分析数据。结果包括全站总计和按页面的明细，按人类和 AI 流量分类。 - -使用基于偏移量的分页浏览结果。当 `hasMore` 为 true 时，将 `offset` 增加 `limit` 的值。 - -
- ## 筛选 -
- -使用 `dateFrom` 和 `dateTo` 参数按日期范围过滤浏览数据。 - -
- ## 响应数据 -
- -响应包含一个 `totals` 对象（全站聚合数据）和一个 `views` 数组（按页面的数据）。每个条目包含： - -- **path**：文档页面路径 -- **human**：来自人类流量的内容浏览事件数 -- **ai**：来自 AI 机器人流量的内容浏览事件数 -- **total**：该页面的总内容浏览事件数 diff --git a/zh/api/analytics/visitors.mdx b/zh/api/analytics/visitors.mdx deleted file mode 100644 index 9343b0697..000000000 --- a/zh/api/analytics/visitors.mdx +++ /dev/null @@ -1,31 +0,0 @@ ---- -title: "获取独立访客" -description: "获取按页面和全站的近似独立访客计数，按人类和 AI 流量分类。" -openapi: /zh/analytics.openapi.json GET /v1/analytics/{projectId}/visitors -keywords: ["Analytics", "访客", "独立访客", "流量", "导出"] ---- - -
- ## 使用方法 -
- -使用此端点导出独立访客分析数据。结果包括全站总计和按页面的明细，按人类和 AI 流量分类。`total` 字段在人类和 AI 流量之间去重。 - -使用基于偏移量的分页浏览结果。当 `hasMore` 为 true 时，将 `offset` 增加 `limit` 的值。 - -
- ## 筛选 -
- -使用 `dateFrom` 和 `dateTo` 参数按日期范围过滤访客数据。 - -
- ## 响应数据 -
- -响应包含一个 `totals` 对象（全站聚合数据）和一个 `visitors` 数组（按页面的数据）。每个条目包含： - -- **path**：文档页面路径 -- **human**：来自人类流量的独立访客数 -- **ai**：来自 AI 机器人流量的独立访客数 -- **total**：近似独立访客数（在人类和 AI 之间去重） From b9c0553acd3f615272d687cca13b1af3a995cff4 Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Tue, 31 Mar 2026 16:42:27 -0700 Subject: [PATCH 4/7] remove paginate info --- api/analytics/feedback-by-page.mdx | 2 -- 1 file changed, 2 deletions(-) diff --git a/api/analytics/feedback-by-page.mdx b/api/analytics/feedback-by-page.mdx index 9e875845c..85c7f79d0 100644 --- a/api/analytics/feedback-by-page.mdx +++ b/api/analytics/feedback-by-page.mdx @@ -9,8 +9,6 @@ keywords: ["analytics", "feedback", "export", "by page", "aggregated"] Use this endpoint to export user feedback aggregated by documentation page path. Each entry shows the total feedback count for a page, broken down by type. -Paginate through results using the `hasMore` flag in the response. - ## Filtering Filter feedback by: From eca479ea1ec5fe258411532d1ebf476ced7ddca1 Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Tue, 31 Mar 2026 17:17:38 -0700 Subject: [PATCH 5/7] Apply suggestion from @ethanpalm --- api/analytics/feedback-by-page.mdx | 8 -------- 1 file changed, 8 deletions(-) diff --git a/api/analytics/feedback-by-page.mdx b/api/analytics/feedback-by-page.mdx index 85c7f79d0..d08f97a23 100644 --- a/api/analytics/feedback-by-page.mdx +++ b/api/analytics/feedback-by-page.mdx @@ -16,11 +16,3 @@ Filter feedback by: - **Source**: Filter by `code_snippet` or `contextual` feedback types - **Status**: Filter by status values like `pending`, `in_progress`, `resolved`, or `dismissed` -## Response data - -Each page entry includes: -- **path**: The documentation page path -- **thumbsUp**: Count of positive contextual feedback -- **thumbsDown**: Count of negative contextual feedback -- **code**: Count of code snippet feedback -- **total**: Total feedback entries for the page From 2a59c6324dbf3b56da5f93d544a7f44591c94e0d Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Tue, 31 Mar 2026 17:18:37 -0700 Subject: [PATCH 6/7] Apply suggestion from @ethanpalm --- api/analytics/searches.mdx | 10 ---------- 1 file changed, 10 deletions(-) diff --git a/api/analytics/searches.mdx b/api/analytics/searches.mdx index ab9a41c02..5cda5ca54 100644 --- a/api/analytics/searches.mdx +++ b/api/analytics/searches.mdx @@ -15,13 +15,3 @@ Paginate through results using the `nextCursor` parameter returned in the respon Filter search data by date range using `dateFrom` and `dateTo` parameters. -## Response data - -Each search term entry includes: -- **searchQuery**: The search term entered by users -- **hits**: Number of times this term was searched -- **ctr**: Click-through rate for this search term -- **topClickedPage**: The most-clicked result path for this query, if any -- **lastSearchedAt**: Timestamp of the last time this term was searched - -The response also includes `totalSearches`, which is the total count of all search events in the requested date range (sum of all hits, not distinct queries). From 88447255676e5675cf65217218084a35b0d69eea Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Tue, 31 Mar 2026 17:19:36 -0700 Subject: [PATCH 7/7] Apply suggestions from code review Co-authored-by: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> --- api/analytics/views.mdx | 7 ------- api/analytics/visitors.mdx | 7 ------- 2 files changed, 14 deletions(-) diff --git a/api/analytics/views.mdx b/api/analytics/views.mdx index fc505b3f6..599f5e949 100644 --- a/api/analytics/views.mdx +++ b/api/analytics/views.mdx @@ -15,10 +15,3 @@ Paginate through results using offset-based pagination. Increment `offset` by `l Filter view data by date range using `dateFrom` and `dateTo` parameters. -## Response data - -The response includes a `totals` object with site-wide aggregates and a `views` array with per-page data. Each entry includes: -- **path**: The documentation page path -- **human**: Content view events from human traffic -- **ai**: Content view events from AI bot traffic -- **total**: Total content view events on this path diff --git a/api/analytics/visitors.mdx b/api/analytics/visitors.mdx index c9a816b9a..b00949c0c 100644 --- a/api/analytics/visitors.mdx +++ b/api/analytics/visitors.mdx @@ -15,10 +15,3 @@ Paginate through results using offset-based pagination. Increment `offset` by `l Filter visitor data by date range using `dateFrom` and `dateTo` parameters. -## Response data - -The response includes a `totals` object with site-wide aggregates and a `visitors` array with per-page data. Each entry includes: -- **path**: The documentation page path -- **human**: Unique visitors from human traffic -- **ai**: Unique visitors from AI bot traffic -- **total**: Approximate distinct visitors (deduplicated across human and AI)