diff --git a/analytics.openapi.json b/analytics.openapi.json index e7b80c1b6..e15eea167 100644 --- a/analytics.openapi.json +++ b/analytics.openapi.json @@ -355,6 +355,176 @@ "nextCursor", "hasMore" ] + }, + "TrafficTotals": { + "type": "object", + "description": "Site-wide traffic totals for the date range.", + "properties": { + "human": { + "type": "number", + "description": "Site-wide total from human traffic." + }, + "ai": { + "type": "number", + "description": "Site-wide total from AI bot traffic." + }, + "total": { + "type": "number", + "description": "Site-wide total across all traffic." + } + }, + "required": [ + "human", + "ai", + "total" + ] + }, + "ViewsByPageResponse": { + "type": "object", + "properties": { + "totals": { + "$ref": "#/components/schemas/TrafficTotals", + "description": "Site-wide view totals for the date range." + }, + "views": { + "type": "array", + "description": "Per-path view counts.", + "items": { + "type": "object", + "properties": { + "path": { + "type": "string", + "description": "The documentation page path." + }, + "human": { + "type": "number", + "description": "Views from human traffic." + }, + "ai": { + "type": "number", + "description": "Views from AI bot traffic." + }, + "total": { + "type": "number", + "description": "Views from all traffic." + } + }, + "required": [ + "path", + "human", + "ai", + "total" + ] + } + }, + "hasMore": { + "type": "boolean", + "description": "Whether more results exist beyond this page." + } + }, + "required": [ + "totals", + "views", + "hasMore" + ] + }, + "VisitorsByPageResponse": { + "type": "object", + "properties": { + "totals": { + "$ref": "#/components/schemas/TrafficTotals", + "description": "Site-wide unique visitor totals for the date range." + }, + "visitors": { + "type": "array", + "description": "Per-path unique 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": "Approx. distinct visitors with any qualifying view on this path (deduplicated across human and AI)." + } + }, + "required": [ + "path", + "human", + "ai", + "total" + ] + } + }, + "hasMore": { + "type": "boolean", + "description": "Whether more results exist beyond this page." + } + }, + "required": [ + "totals", + "visitors", + "hasMore" + ] + }, + "FeedbackGroupedByPageResponse": { + "type": "object", + "properties": { + "feedback": { + "type": "array", + "description": "Per-page feedback aggregates.", + "items": { + "type": "object", + "properties": { + "path": { + "type": "string", + "description": "The documentation page path." + }, + "thumbsUp": { + "type": "number", + "description": "Number of thumbs up ratings on this page." + }, + "thumbsDown": { + "type": "number", + "description": "Number of thumbs down ratings on this page." + }, + "code": { + "type": "number", + "description": "Number of code snippet feedback entries on this page." + }, + "total": { + "type": "number", + "description": "Total feedback count on this page." + } + }, + "required": [ + "path", + "thumbsUp", + "thumbsDown", + "code", + "total" + ] + } + }, + "hasMore": { + "type": "boolean", + "description": "Whether more results exist beyond this page." + } + }, + "required": [ + "feedback", + "hasMore" + ] } }, "parameters": { @@ -483,6 +653,111 @@ } } }, + "/v1/analytics/{projectId}/feedback/by-page": { + "get": { + "summary": "Get feedback grouped by page", + "description": "Returns feedback counts (thumbs up/down, code snippets, total) aggregated by page path", + "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 (default 10)" + }, + "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", + "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 +850,194 @@ } } } + }, + "/v1/analytics/{projectId}/views": { + "get": { + "summary": "Get page views by path", + "description": "Returns per-path and site-wide content view event counts.", + "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", + "example": "2024-01-31" + }, + "required": false, + "name": "dateTo", + "in": "query" + }, + { + "schema": { + "type": "number", + "minimum": 1, + "maximum": 250, + "default": 50, + "description": "Max results per page (1–250, default 50)" + }, + "required": false, + "name": "limit", + "in": "query" + }, + { + "schema": { + "type": "number", + "minimum": 0, + "default": 0, + "description": "Number of rows to skip" + }, + "required": false, + "name": "offset", + "in": "query" + } + ], + "responses": { + "200": { + "description": "Site-wide totals and per-path view 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 by page", + "description": "Returns per-path and site-wide approximate distinct visitors by traffic type. `total` 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", + "example": "2024-01-31" + }, + "required": false, + "name": "dateTo", + "in": "query" + }, + { + "schema": { + "type": "number", + "minimum": 1, + "maximum": 250, + "default": 50, + "description": "Max results per page (1–250, default 50)" + }, + "required": false, + "name": "limit", + "in": "query" + }, + { + "schema": { + "type": "number", + "minimum": 0, + "default": 0, + "description": "Number of rows to skip" + }, + "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/feedback-by-page.mdx b/api/analytics/feedback-by-page.mdx new file mode 100644 index 000000000..5fb4facff --- /dev/null +++ b/api/analytics/feedback-by-page.mdx @@ -0,0 +1,23 @@ +--- +title: "Get feedback by page" +description: "Retrieve feedback counts aggregated by page path, including thumbs up/down and code snippet counts." +openapi: /analytics.openapi.json GET /v1/analytics/{projectId}/feedback/by-page +keywords: ["analytics", "feedback", "by page", "export", "aggregated"] +--- + +## Usage + +Use this endpoint to export per-page feedback aggregates from your documentation. Each row includes counts for thumbs up, thumbs down, code snippet feedback, and a combined total. + +## Response fields + +Every item in the response includes: +- **path**: The documentation page path +- **thumbsUp**: Number of positive (thumbs up) ratings +- **thumbsDown**: Number of negative (thumbs down) ratings +- **code**: Number of code snippet feedback entries +- **total**: Combined feedback count across all types + +## Filtering + +Filter results by date range using `dateFrom` and `dateTo`, by feedback source using `source`, and by status using `status`. diff --git a/api/analytics/views.mdx b/api/analytics/views.mdx new file mode 100644 index 000000000..94727c967 --- /dev/null +++ b/api/analytics/views.mdx @@ -0,0 +1,25 @@ +--- +title: "Get page views" +description: "Retrieve per-path and site-wide content view event counts." +openapi: /analytics.openapi.json GET /v1/analytics/{projectId}/views +keywords: ["analytics", "views", "page views", "export", "traffic"] +--- + +## Usage + +Use this endpoint to export per-page view counts from your documentation. Each row includes a breakdown of human and AI bot views, plus a combined total. + +Paginate through results using offset-based pagination. Increment `offset` by `limit` while `hasMore` is `true`. + +## Traffic breakdown + +Every response includes: +- **human**: Views from regular browser traffic +- **ai**: Views from AI bot crawlers (e.g. GPTBot, ClaudeBot) +- **total**: Combined view count across all traffic + +The `totals` object contains the same breakdown aggregated across your entire site for the selected date range. + +## Filtering + +Filter views by date range using `dateFrom` and `dateTo` parameters. diff --git a/api/analytics/visitors.mdx b/api/analytics/visitors.mdx new file mode 100644 index 000000000..fe7107a71 --- /dev/null +++ b/api/analytics/visitors.mdx @@ -0,0 +1,25 @@ +--- +title: "Get unique visitors" +description: "Retrieve per-path and site-wide approximate distinct visitors by traffic type." +openapi: /analytics.openapi.json GET /v1/analytics/{projectId}/visitors +keywords: ["analytics", "visitors", "unique visitors", "export", "traffic"] +--- + +## Usage + +Use this endpoint to export per-page unique visitor counts from your documentation. Visitors are deduplicated by user ID or anonymous ID. + +Paginate through results using offset-based pagination. Increment `offset` by `limit` while `hasMore` is `true`. + +## Traffic breakdown + +Every response includes: +- **human**: Unique visitors from regular browser traffic +- **ai**: Unique visitors from AI bot crawlers (e.g. GPTBot, ClaudeBot) +- **total**: Combined unique visitor count across all traffic + +The `totals` object contains the same breakdown aggregated across your entire site for the selected date range. + +## Filtering + +Filter visitors by date range using `dateFrom` and `dateTo` parameters. diff --git a/api/introduction.mdx b/api/introduction.mdx index d5b28d6d2..a6674071c 100644 --- a/api/introduction.mdx +++ b/api/introduction.mdx @@ -16,7 +16,10 @@ 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 path. - [Get assistant conversations](/api/analytics/assistant-conversations): Export AI assistant conversation history. +- [Get page views](/api/analytics/views): Export per-path and site-wide content view event counts. +- [Get unique visitors](/api/analytics/visitors): Export per-path and site-wide approximate distinct visitors by traffic type. ### Common use cases @@ -24,7 +27,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, 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 page views](/api/analytics/views), and [Get unique visitors](/api/analytics/visitors). ## Authentication @@ -34,7 +37,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), [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 53867420a..0a10a8e31 100644 --- a/docs.json +++ b/docs.json @@ -371,7 +371,10 @@ "icon": "chart-line", "pages": [ "api/analytics/feedback", - "api/analytics/assistant-conversations" + "api/analytics/feedback-by-page", + "api/analytics/assistant-conversations", + "api/analytics/views", + "api/analytics/visitors" ] } ] @@ -741,7 +744,10 @@ "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/views", + "fr/api/analytics/visitors" ] } ] @@ -1111,7 +1117,10 @@ "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/views", + "es/api/analytics/visitors" ] } ] @@ -1481,7 +1490,10 @@ "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/views", + "zh/api/analytics/visitors" ] } ] diff --git a/es/analytics.openapi.json b/es/analytics.openapi.json index 636f47515..e15eea167 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": [ @@ -355,6 +355,176 @@ "nextCursor", "hasMore" ] + }, + "TrafficTotals": { + "type": "object", + "description": "Site-wide traffic totals for the date range.", + "properties": { + "human": { + "type": "number", + "description": "Site-wide total from human traffic." + }, + "ai": { + "type": "number", + "description": "Site-wide total from AI bot traffic." + }, + "total": { + "type": "number", + "description": "Site-wide total across all traffic." + } + }, + "required": [ + "human", + "ai", + "total" + ] + }, + "ViewsByPageResponse": { + "type": "object", + "properties": { + "totals": { + "$ref": "#/components/schemas/TrafficTotals", + "description": "Site-wide view totals for the date range." + }, + "views": { + "type": "array", + "description": "Per-path view counts.", + "items": { + "type": "object", + "properties": { + "path": { + "type": "string", + "description": "The documentation page path." + }, + "human": { + "type": "number", + "description": "Views from human traffic." + }, + "ai": { + "type": "number", + "description": "Views from AI bot traffic." + }, + "total": { + "type": "number", + "description": "Views from all traffic." + } + }, + "required": [ + "path", + "human", + "ai", + "total" + ] + } + }, + "hasMore": { + "type": "boolean", + "description": "Whether more results exist beyond this page." + } + }, + "required": [ + "totals", + "views", + "hasMore" + ] + }, + "VisitorsByPageResponse": { + "type": "object", + "properties": { + "totals": { + "$ref": "#/components/schemas/TrafficTotals", + "description": "Site-wide unique visitor totals for the date range." + }, + "visitors": { + "type": "array", + "description": "Per-path unique 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": "Approx. distinct visitors with any qualifying view on this path (deduplicated across human and AI)." + } + }, + "required": [ + "path", + "human", + "ai", + "total" + ] + } + }, + "hasMore": { + "type": "boolean", + "description": "Whether more results exist beyond this page." + } + }, + "required": [ + "totals", + "visitors", + "hasMore" + ] + }, + "FeedbackGroupedByPageResponse": { + "type": "object", + "properties": { + "feedback": { + "type": "array", + "description": "Per-page feedback aggregates.", + "items": { + "type": "object", + "properties": { + "path": { + "type": "string", + "description": "The documentation page path." + }, + "thumbsUp": { + "type": "number", + "description": "Number of thumbs up ratings on this page." + }, + "thumbsDown": { + "type": "number", + "description": "Number of thumbs down ratings on this page." + }, + "code": { + "type": "number", + "description": "Number of code snippet feedback entries on this page." + }, + "total": { + "type": "number", + "description": "Total feedback count on this page." + } + }, + "required": [ + "path", + "thumbsUp", + "thumbsDown", + "code", + "total" + ] + } + }, + "hasMore": { + "type": "boolean", + "description": "Whether more results exist beyond this page." + } + }, + "required": [ + "feedback", + "hasMore" + ] } }, "parameters": { @@ -371,8 +541,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" ], @@ -388,7 +558,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, @@ -398,7 +568,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, @@ -412,7 +582,7 @@ "code_snippet", "contextual" ], - "description": "Filtrar por el origen de los comentarios" + "description": "Filter by feedback source" }, "required": false, "name": "source", @@ -421,7 +591,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", @@ -433,7 +603,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", @@ -442,7 +612,7 @@ { "schema": { "type": "string", - "description": "Cursor de paginación" + "description": "Pagination cursor" }, "required": false, "name": "cursor", @@ -451,7 +621,7 @@ ], "responses": { "200": { - "description": "Datos de comentarios paginados", + "description": "Feedback data with pagination", "content": { "application/json": { "schema": { @@ -461,7 +631,112 @@ } }, "400": { - "description": "Parámetros de búsqueda no válidos", + "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 grouped by page", + "description": "Returns feedback counts (thumbs up/down, code snippets, total) aggregated by page path", + "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 (default 10)" + }, + "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", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/FeedbackGroupedByPageResponse" + } + } + } + }, + "400": { + "description": "Invalid query parameters", "content": { "application/json": { "schema": { @@ -471,7 +746,7 @@ } }, "500": { - "description": "Error del servidor", + "description": "Server error", "content": { "application/json": { "schema": { @@ -485,8 +760,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" ], @@ -502,7 +777,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, @@ -512,7 +787,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, @@ -525,7 +800,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", @@ -535,7 +810,7 @@ "schema": { "type": "string", "format": "ulid", - "description": "Cursor de paginación (formato ULID)" + "description": "Pagination cursor (ULID format)" }, "required": false, "name": "cursor", @@ -544,7 +819,7 @@ ], "responses": { "200": { - "description": "Datos de conversación paginados", + "description": "Conversation data with pagination", "content": { "application/json": { "schema": { @@ -554,7 +829,195 @@ } }, "400": { - "description": "Parámetros de búsqueda no válidos", + "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}/views": { + "get": { + "summary": "Get page views by path", + "description": "Returns per-path and site-wide content view event counts.", + "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", + "example": "2024-01-31" + }, + "required": false, + "name": "dateTo", + "in": "query" + }, + { + "schema": { + "type": "number", + "minimum": 1, + "maximum": 250, + "default": 50, + "description": "Max results per page (1–250, default 50)" + }, + "required": false, + "name": "limit", + "in": "query" + }, + { + "schema": { + "type": "number", + "minimum": 0, + "default": 0, + "description": "Number of rows to skip" + }, + "required": false, + "name": "offset", + "in": "query" + } + ], + "responses": { + "200": { + "description": "Site-wide totals and per-path view 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 by page", + "description": "Returns per-path and site-wide approximate distinct visitors by traffic type. `total` 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", + "example": "2024-01-31" + }, + "required": false, + "name": "dateTo", + "in": "query" + }, + { + "schema": { + "type": "number", + "minimum": 1, + "maximum": 250, + "default": 50, + "description": "Max results per page (1–250, default 50)" + }, + "required": false, + "name": "limit", + "in": "query" + }, + { + "schema": { + "type": "number", + "minimum": 0, + "default": 0, + "description": "Number of rows to skip" + }, + "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": { @@ -564,7 +1027,7 @@ } }, "500": { - "description": "Error del servidor", + "description": "Server error", "content": { "application/json": { "schema": { diff --git a/es/api/analytics/feedback-by-page.mdx b/es/api/analytics/feedback-by-page.mdx new file mode 100644 index 000000000..5fb4facff --- /dev/null +++ b/es/api/analytics/feedback-by-page.mdx @@ -0,0 +1,23 @@ +--- +title: "Get feedback by page" +description: "Retrieve feedback counts aggregated by page path, including thumbs up/down and code snippet counts." +openapi: /analytics.openapi.json GET /v1/analytics/{projectId}/feedback/by-page +keywords: ["analytics", "feedback", "by page", "export", "aggregated"] +--- + +## Usage + +Use this endpoint to export per-page feedback aggregates from your documentation. Each row includes counts for thumbs up, thumbs down, code snippet feedback, and a combined total. + +## Response fields + +Every item in the response includes: +- **path**: The documentation page path +- **thumbsUp**: Number of positive (thumbs up) ratings +- **thumbsDown**: Number of negative (thumbs down) ratings +- **code**: Number of code snippet feedback entries +- **total**: Combined feedback count across all types + +## Filtering + +Filter results by date range using `dateFrom` and `dateTo`, by feedback source using `source`, and by status using `status`. diff --git a/es/api/analytics/views.mdx b/es/api/analytics/views.mdx new file mode 100644 index 000000000..94727c967 --- /dev/null +++ b/es/api/analytics/views.mdx @@ -0,0 +1,25 @@ +--- +title: "Get page views" +description: "Retrieve per-path and site-wide content view event counts." +openapi: /analytics.openapi.json GET /v1/analytics/{projectId}/views +keywords: ["analytics", "views", "page views", "export", "traffic"] +--- + +## Usage + +Use this endpoint to export per-page view counts from your documentation. Each row includes a breakdown of human and AI bot views, plus a combined total. + +Paginate through results using offset-based pagination. Increment `offset` by `limit` while `hasMore` is `true`. + +## Traffic breakdown + +Every response includes: +- **human**: Views from regular browser traffic +- **ai**: Views from AI bot crawlers (e.g. GPTBot, ClaudeBot) +- **total**: Combined view count across all traffic + +The `totals` object contains the same breakdown aggregated across your entire site for the selected date range. + +## Filtering + +Filter views by date range using `dateFrom` and `dateTo` parameters. diff --git a/es/api/analytics/visitors.mdx b/es/api/analytics/visitors.mdx new file mode 100644 index 000000000..fe7107a71 --- /dev/null +++ b/es/api/analytics/visitors.mdx @@ -0,0 +1,25 @@ +--- +title: "Get unique visitors" +description: "Retrieve per-path and site-wide approximate distinct visitors by traffic type." +openapi: /analytics.openapi.json GET /v1/analytics/{projectId}/visitors +keywords: ["analytics", "visitors", "unique visitors", "export", "traffic"] +--- + +## Usage + +Use this endpoint to export per-page unique visitor counts from your documentation. Visitors are deduplicated by user ID or anonymous ID. + +Paginate through results using offset-based pagination. Increment `offset` by `limit` while `hasMore` is `true`. + +## Traffic breakdown + +Every response includes: +- **human**: Unique visitors from regular browser traffic +- **ai**: Unique visitors from AI bot crawlers (e.g. GPTBot, ClaudeBot) +- **total**: Combined unique visitor count across all traffic + +The `totals` object contains the same breakdown aggregated across your entire site for the selected date range. + +## Filtering + +Filter visitors by date range using `dateFrom` and `dateTo` parameters. diff --git a/es/api/introduction.mdx b/es/api/introduction.mdx index 08c5d5acc..3ffd6d54c 100644 --- a/es/api/introduction.mdx +++ b/es/api/introduction.mdx @@ -18,7 +18,10 @@ La REST (Representational State Transfer) API de Mintlify te permite interactuar * [Create assistant message](/es/api/assistant/create-assistant-message-v2): Integra el assistant, entrenado con tu documentación, en cualquier aplicación que elijas. * [Search documentation](/es/api/assistant/search): Busca en tu documentación. * [Get user feedback](/es/api/analytics/feedback): Exporta los comentarios de los usuarios de tu documentación. +* [Get feedback by page](/es/api/analytics/feedback-by-page): Exporta las estadísticas de feedback agrupadas por página. * [Get assistant conversations](/es/api/analytics/assistant-conversations): Exporta el historial de conversaciones del Asistente de IA. +* [Get page views](/es/api/analytics/views): Exporta el recuento de vistas por página y a nivel de sitio. +* [Get unique visitors](/es/api/analytics/visitors): Exporta el recuento de visitantes únicos por página y a nivel de sitio.
### Casos de uso comunes @@ -28,7 +31,7 @@ La REST (Representational State Transfer) API de Mintlify te permite interactuar * **Integración CI/CD**: Actualiza la documentación como parte de tu pipeline de implementación cuando el código cambie con [Trigger update](/es/api/update/trigger). * **Integraciones personalizadas**: Inserta el Asistente de IA en tu producto, portal de soporte o herramientas internas con [Create assistant message](/es/api/assistant/create-assistant-message-v2) y [Search documentation](/es/api/assistant/search). * **Edición automatizada**: Usa trabajos de agente para actualizar la documentación programáticamente y a escala con [Create agent job](/es/api/agent/v2/create-agent-job), [Get agent job](/es/api/agent/v2/get-agent-job) y [Send follow-up message](/es/api/agent/v2/send-message). -* **Exportación de Analytics**: Exporta comentarios y conversaciones del Asistente de IA para análisis externo con [Get user feedback](/es/api/analytics/feedback) y [Get assistant conversations](/es/api/analytics/assistant-conversations). +* **Exportación de Analytics**: Exporta comentarios, conversaciones del Asistente de IA, vistas de páginas y datos de visitantes para análisis externo con [Get user feedback](/es/api/analytics/feedback), [Get feedback by page](/es/api/analytics/feedback-by-page), [Get assistant conversations](/es/api/analytics/assistant-conversations), [Get page views](/es/api/analytics/views) y [Get unique visitors](/es/api/analytics/visitors).
## Autenticación @@ -42,7 +45,7 @@ Puedes crear hasta 10 API keys por hora y por organización. ### Clave de la API de administrador
-Usa la clave de la API de administrador para autenticar solicitudes a [Trigger update](/es/api/update/trigger), [Get update status](/es/api/update/status), [Create agent job](/es/api/agent/v2/create-agent-job), [Get agent job](/es/api/agent/v2/get-agent-job), [Send follow-up message](/es/api/agent/v2/send-message), [Get user feedback](/es/api/analytics/feedback) y [Get assistant conversations](/es/api/analytics/assistant-conversations). +Usa la clave de la API de administrador para autenticar solicitudes a [Trigger update](/es/api/update/trigger), [Get update status](/es/api/update/status), [Create agent job](/es/api/agent/v2/create-agent-job), [Get agent job](/es/api/agent/v2/get-agent-job), [Send follow-up message](/es/api/agent/v2/send-message), [Get user feedback](/es/api/analytics/feedback), [Get feedback by page](/es/api/analytics/feedback-by-page), [Get assistant conversations](/es/api/analytics/assistant-conversations), [Get page views](/es/api/analytics/views) y [Get unique visitors](/es/api/analytics/visitors). Las claves de la API de administrador comienzan con el prefijo `mint_`. diff --git a/fr/analytics.openapi.json b/fr/analytics.openapi.json index b41ea2b03..e15eea167 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": [ @@ -355,6 +355,176 @@ "nextCursor", "hasMore" ] + }, + "TrafficTotals": { + "type": "object", + "description": "Site-wide traffic totals for the date range.", + "properties": { + "human": { + "type": "number", + "description": "Site-wide total from human traffic." + }, + "ai": { + "type": "number", + "description": "Site-wide total from AI bot traffic." + }, + "total": { + "type": "number", + "description": "Site-wide total across all traffic." + } + }, + "required": [ + "human", + "ai", + "total" + ] + }, + "ViewsByPageResponse": { + "type": "object", + "properties": { + "totals": { + "$ref": "#/components/schemas/TrafficTotals", + "description": "Site-wide view totals for the date range." + }, + "views": { + "type": "array", + "description": "Per-path view counts.", + "items": { + "type": "object", + "properties": { + "path": { + "type": "string", + "description": "The documentation page path." + }, + "human": { + "type": "number", + "description": "Views from human traffic." + }, + "ai": { + "type": "number", + "description": "Views from AI bot traffic." + }, + "total": { + "type": "number", + "description": "Views from all traffic." + } + }, + "required": [ + "path", + "human", + "ai", + "total" + ] + } + }, + "hasMore": { + "type": "boolean", + "description": "Whether more results exist beyond this page." + } + }, + "required": [ + "totals", + "views", + "hasMore" + ] + }, + "VisitorsByPageResponse": { + "type": "object", + "properties": { + "totals": { + "$ref": "#/components/schemas/TrafficTotals", + "description": "Site-wide unique visitor totals for the date range." + }, + "visitors": { + "type": "array", + "description": "Per-path unique 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": "Approx. distinct visitors with any qualifying view on this path (deduplicated across human and AI)." + } + }, + "required": [ + "path", + "human", + "ai", + "total" + ] + } + }, + "hasMore": { + "type": "boolean", + "description": "Whether more results exist beyond this page." + } + }, + "required": [ + "totals", + "visitors", + "hasMore" + ] + }, + "FeedbackGroupedByPageResponse": { + "type": "object", + "properties": { + "feedback": { + "type": "array", + "description": "Per-page feedback aggregates.", + "items": { + "type": "object", + "properties": { + "path": { + "type": "string", + "description": "The documentation page path." + }, + "thumbsUp": { + "type": "number", + "description": "Number of thumbs up ratings on this page." + }, + "thumbsDown": { + "type": "number", + "description": "Number of thumbs down ratings on this page." + }, + "code": { + "type": "number", + "description": "Number of code snippet feedback entries on this page." + }, + "total": { + "type": "number", + "description": "Total feedback count on this page." + } + }, + "required": [ + "path", + "thumbsUp", + "thumbsDown", + "code", + "total" + ] + } + }, + "hasMore": { + "type": "boolean", + "description": "Whether more results exist beyond this page." + } + }, + "required": [ + "feedback", + "hasMore" + ] } }, "parameters": { @@ -371,8 +541,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" ], @@ -388,7 +558,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, @@ -398,7 +568,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, @@ -412,7 +582,7 @@ "code_snippet", "contextual" ], - "description": "Filtrer par source des retours utilisateurs" + "description": "Filter by feedback source" }, "required": false, "name": "source", @@ -421,7 +591,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", @@ -433,7 +603,7 @@ "minimum": 1, "maximum": 100, "default": 50, - "description": "Nombre maximal de résultats par page" + "description": "Max results per page" }, "required": false, "name": "limit", @@ -442,7 +612,7 @@ { "schema": { "type": "string", - "description": "Curseur de pagination" + "description": "Pagination cursor" }, "required": false, "name": "cursor", @@ -451,7 +621,7 @@ ], "responses": { "200": { - "description": "Données de retours utilisateurs paginées", + "description": "Feedback data with pagination", "content": { "application/json": { "schema": { @@ -461,7 +631,112 @@ } }, "400": { - "description": "Paramètres de requête invalides", + "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 grouped by page", + "description": "Returns feedback counts (thumbs up/down, code snippets, total) aggregated by page path", + "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 (default 10)" + }, + "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", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/FeedbackGroupedByPageResponse" + } + } + } + }, + "400": { + "description": "Invalid query parameters", "content": { "application/json": { "schema": { @@ -471,7 +746,7 @@ } }, "500": { - "description": "Erreur serveur", + "description": "Server error", "content": { "application/json": { "schema": { @@ -485,8 +760,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" ], @@ -502,7 +777,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, @@ -512,7 +787,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, @@ -525,7 +800,7 @@ "minimum": 1, "maximum": 1000, "default": 100, - "description": "Nombre maximal de résultats par page" + "description": "Max results per page" }, "required": false, "name": "limit", @@ -535,7 +810,7 @@ "schema": { "type": "string", "format": "ulid", - "description": "Curseur de pagination (format ULID)" + "description": "Pagination cursor (ULID format)" }, "required": false, "name": "cursor", @@ -544,7 +819,7 @@ ], "responses": { "200": { - "description": "Données de conversation paginées", + "description": "Conversation data with pagination", "content": { "application/json": { "schema": { @@ -554,7 +829,195 @@ } }, "400": { - "description": "Paramètres de requête invalides", + "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}/views": { + "get": { + "summary": "Get page views by path", + "description": "Returns per-path and site-wide content view event counts.", + "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", + "example": "2024-01-31" + }, + "required": false, + "name": "dateTo", + "in": "query" + }, + { + "schema": { + "type": "number", + "minimum": 1, + "maximum": 250, + "default": 50, + "description": "Max results per page (1–250, default 50)" + }, + "required": false, + "name": "limit", + "in": "query" + }, + { + "schema": { + "type": "number", + "minimum": 0, + "default": 0, + "description": "Number of rows to skip" + }, + "required": false, + "name": "offset", + "in": "query" + } + ], + "responses": { + "200": { + "description": "Site-wide totals and per-path view 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 by page", + "description": "Returns per-path and site-wide approximate distinct visitors by traffic type. `total` 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", + "example": "2024-01-31" + }, + "required": false, + "name": "dateTo", + "in": "query" + }, + { + "schema": { + "type": "number", + "minimum": 1, + "maximum": 250, + "default": 50, + "description": "Max results per page (1–250, default 50)" + }, + "required": false, + "name": "limit", + "in": "query" + }, + { + "schema": { + "type": "number", + "minimum": 0, + "default": 0, + "description": "Number of rows to skip" + }, + "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": { @@ -564,7 +1027,7 @@ } }, "500": { - "description": "Erreur serveur", + "description": "Server error", "content": { "application/json": { "schema": { diff --git a/fr/api/analytics/feedback-by-page.mdx b/fr/api/analytics/feedback-by-page.mdx new file mode 100644 index 000000000..5fb4facff --- /dev/null +++ b/fr/api/analytics/feedback-by-page.mdx @@ -0,0 +1,23 @@ +--- +title: "Get feedback by page" +description: "Retrieve feedback counts aggregated by page path, including thumbs up/down and code snippet counts." +openapi: /analytics.openapi.json GET /v1/analytics/{projectId}/feedback/by-page +keywords: ["analytics", "feedback", "by page", "export", "aggregated"] +--- + +## Usage + +Use this endpoint to export per-page feedback aggregates from your documentation. Each row includes counts for thumbs up, thumbs down, code snippet feedback, and a combined total. + +## Response fields + +Every item in the response includes: +- **path**: The documentation page path +- **thumbsUp**: Number of positive (thumbs up) ratings +- **thumbsDown**: Number of negative (thumbs down) ratings +- **code**: Number of code snippet feedback entries +- **total**: Combined feedback count across all types + +## Filtering + +Filter results by date range using `dateFrom` and `dateTo`, by feedback source using `source`, and by status using `status`. diff --git a/fr/api/analytics/views.mdx b/fr/api/analytics/views.mdx new file mode 100644 index 000000000..94727c967 --- /dev/null +++ b/fr/api/analytics/views.mdx @@ -0,0 +1,25 @@ +--- +title: "Get page views" +description: "Retrieve per-path and site-wide content view event counts." +openapi: /analytics.openapi.json GET /v1/analytics/{projectId}/views +keywords: ["analytics", "views", "page views", "export", "traffic"] +--- + +## Usage + +Use this endpoint to export per-page view counts from your documentation. Each row includes a breakdown of human and AI bot views, plus a combined total. + +Paginate through results using offset-based pagination. Increment `offset` by `limit` while `hasMore` is `true`. + +## Traffic breakdown + +Every response includes: +- **human**: Views from regular browser traffic +- **ai**: Views from AI bot crawlers (e.g. GPTBot, ClaudeBot) +- **total**: Combined view count across all traffic + +The `totals` object contains the same breakdown aggregated across your entire site for the selected date range. + +## Filtering + +Filter views by date range using `dateFrom` and `dateTo` parameters. diff --git a/fr/api/analytics/visitors.mdx b/fr/api/analytics/visitors.mdx new file mode 100644 index 000000000..fe7107a71 --- /dev/null +++ b/fr/api/analytics/visitors.mdx @@ -0,0 +1,25 @@ +--- +title: "Get unique visitors" +description: "Retrieve per-path and site-wide approximate distinct visitors by traffic type." +openapi: /analytics.openapi.json GET /v1/analytics/{projectId}/visitors +keywords: ["analytics", "visitors", "unique visitors", "export", "traffic"] +--- + +## Usage + +Use this endpoint to export per-page unique visitor counts from your documentation. Visitors are deduplicated by user ID or anonymous ID. + +Paginate through results using offset-based pagination. Increment `offset` by `limit` while `hasMore` is `true`. + +## Traffic breakdown + +Every response includes: +- **human**: Unique visitors from regular browser traffic +- **ai**: Unique visitors from AI bot crawlers (e.g. GPTBot, ClaudeBot) +- **total**: Combined unique visitor count across all traffic + +The `totals` object contains the same breakdown aggregated across your entire site for the selected date range. + +## Filtering + +Filter visitors by date range using `dateFrom` and `dateTo` parameters. diff --git a/fr/api/introduction.mdx b/fr/api/introduction.mdx index b872d5cff..68ee51444 100644 --- a/fr/api/introduction.mdx +++ b/fr/api/introduction.mdx @@ -18,7 +18,10 @@ L'API REST (Representational State Transfer) de Mintlify vous permet d'interagir * [Create assistant message](/fr/api/assistant/create-assistant-message-v2): Intégrez l'Assistant, entraîné sur votre documentation, dans n'importe quelle application de votre choix. * [Search documentation](/fr/api/assistant/search): Effectuez une recherche dans votre documentation. * [Get user feedback](/fr/api/analytics/feedback): Exportez les retours utilisateurs issus de votre documentation. +* [Get feedback by page](/fr/api/analytics/feedback-by-page): Exportez les statistiques de feedback agrégées par page. * [Get assistant conversations](/fr/api/analytics/assistant-conversations): Exportez l'historique des conversations de l'Assistant IA. +* [Get page views](/fr/api/analytics/views): Exportez le nombre de vues par page et au niveau du site. +* [Get unique visitors](/fr/api/analytics/visitors): Exportez le nombre de visiteurs uniques par page et au niveau du site.
### Cas d'utilisation courants @@ -28,7 +31,7 @@ L'API REST (Representational State Transfer) de Mintlify vous permet d'interagir * **Intégration CI/CD** : Mettez à jour la documentation dans le cadre de votre pipeline de déploiement lorsque le code change avec [Trigger update](/fr/api/update/trigger). * **Intégrations personnalisées** : Intégrez l'Assistant IA à votre produit, portail d'assistance ou outils internes avec [Create assistant message](/fr/api/assistant/create-assistant-message-v2) et [Search documentation](/fr/api/assistant/search). * **Édition automatisée** : Utilisez des jobs d'agent pour mettre à jour la documentation de manière programmatique et à grande échelle avec [Create agent job](/fr/api/agent/v2/create-agent-job), [Get agent job](/fr/api/agent/v2/get-agent-job), et [Send follow-up message](/fr/api/agent/v2/send-message). -* **Export Analytics** : Exportez les retours utilisateurs et les conversations avec l'Assistant pour une analyse externe avec [Get user feedback](/fr/api/analytics/feedback) et [Get assistant conversations](/fr/api/analytics/assistant-conversations). +* **Export Analytics** : Exportez les retours utilisateurs, les conversations avec l'Assistant, les vues de pages et les données de visiteurs pour une analyse externe avec [Get user feedback](/fr/api/analytics/feedback), [Get feedback by page](/fr/api/analytics/feedback-by-page), [Get assistant conversations](/fr/api/analytics/assistant-conversations), [Get page views](/fr/api/analytics/views) et [Get unique visitors](/fr/api/analytics/visitors).
## Authentification @@ -42,7 +45,7 @@ Vous pouvez créer jusqu'à 10 clés d'API par heure et par organisation. ### Clé d'API administrateur
-Utilisez la clé d'API administrateur pour authentifier les requêtes vers [Trigger update](/fr/api/update/trigger), [Get update status](/fr/api/update/status), [Create agent job](/fr/api/agent/v2/create-agent-job), [Get agent job](/fr/api/agent/v2/get-agent-job), [Send follow-up message](/fr/api/agent/v2/send-message), [Get user feedback](/fr/api/analytics/feedback) et [Get assistant conversations](/fr/api/analytics/assistant-conversations). +Utilisez la clé d'API administrateur pour authentifier les requêtes vers [Trigger update](/fr/api/update/trigger), [Get update status](/fr/api/update/status), [Create agent job](/fr/api/agent/v2/create-agent-job), [Get agent job](/fr/api/agent/v2/get-agent-job), [Send follow-up message](/fr/api/agent/v2/send-message), [Get user feedback](/fr/api/analytics/feedback), [Get feedback by page](/fr/api/analytics/feedback-by-page), [Get assistant conversations](/fr/api/analytics/assistant-conversations), [Get page views](/fr/api/analytics/views) et [Get unique visitors](/fr/api/analytics/visitors). Les clés d'API administrateur commencent par le préfixe `mint_`. diff --git a/zh/analytics.openapi.json b/zh/analytics.openapi.json index 0b7a608af..e15eea167 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": [ @@ -355,6 +355,176 @@ "nextCursor", "hasMore" ] + }, + "TrafficTotals": { + "type": "object", + "description": "Site-wide traffic totals for the date range.", + "properties": { + "human": { + "type": "number", + "description": "Site-wide total from human traffic." + }, + "ai": { + "type": "number", + "description": "Site-wide total from AI bot traffic." + }, + "total": { + "type": "number", + "description": "Site-wide total across all traffic." + } + }, + "required": [ + "human", + "ai", + "total" + ] + }, + "ViewsByPageResponse": { + "type": "object", + "properties": { + "totals": { + "$ref": "#/components/schemas/TrafficTotals", + "description": "Site-wide view totals for the date range." + }, + "views": { + "type": "array", + "description": "Per-path view counts.", + "items": { + "type": "object", + "properties": { + "path": { + "type": "string", + "description": "The documentation page path." + }, + "human": { + "type": "number", + "description": "Views from human traffic." + }, + "ai": { + "type": "number", + "description": "Views from AI bot traffic." + }, + "total": { + "type": "number", + "description": "Views from all traffic." + } + }, + "required": [ + "path", + "human", + "ai", + "total" + ] + } + }, + "hasMore": { + "type": "boolean", + "description": "Whether more results exist beyond this page." + } + }, + "required": [ + "totals", + "views", + "hasMore" + ] + }, + "VisitorsByPageResponse": { + "type": "object", + "properties": { + "totals": { + "$ref": "#/components/schemas/TrafficTotals", + "description": "Site-wide unique visitor totals for the date range." + }, + "visitors": { + "type": "array", + "description": "Per-path unique 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": "Approx. distinct visitors with any qualifying view on this path (deduplicated across human and AI)." + } + }, + "required": [ + "path", + "human", + "ai", + "total" + ] + } + }, + "hasMore": { + "type": "boolean", + "description": "Whether more results exist beyond this page." + } + }, + "required": [ + "totals", + "visitors", + "hasMore" + ] + }, + "FeedbackGroupedByPageResponse": { + "type": "object", + "properties": { + "feedback": { + "type": "array", + "description": "Per-page feedback aggregates.", + "items": { + "type": "object", + "properties": { + "path": { + "type": "string", + "description": "The documentation page path." + }, + "thumbsUp": { + "type": "number", + "description": "Number of thumbs up ratings on this page." + }, + "thumbsDown": { + "type": "number", + "description": "Number of thumbs down ratings on this page." + }, + "code": { + "type": "number", + "description": "Number of code snippet feedback entries on this page." + }, + "total": { + "type": "number", + "description": "Total feedback count on this page." + } + }, + "required": [ + "path", + "thumbsUp", + "thumbsDown", + "code", + "total" + ] + } + }, + "hasMore": { + "type": "boolean", + "description": "Whether more results exist beyond this page." + } + }, + "required": [ + "feedback", + "hasMore" + ] } }, "parameters": { @@ -371,8 +541,8 @@ "paths": { "/v1/analytics/{projectId}/feedback": { "get": { - "summary": "获取用户反馈列表", - "description": "返回按页划分的用户反馈，并支持可选筛选条件", + "summary": "Get user feedback", + "description": "Returns paginated user feedback with optional filtering", "tags": [ "Analytics" ], @@ -388,7 +558,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, @@ -398,7 +568,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, @@ -412,7 +582,7 @@ "code_snippet", "contextual" ], - "description": "按反馈来源进行筛选" + "description": "Filter by feedback source" }, "required": false, "name": "source", @@ -421,7 +591,7 @@ { "schema": { "type": "string", - "description": "用于筛选的以逗号分隔的状态列表" + "description": "Comma-separated list of statuses to filter by" }, "required": false, "name": "status", @@ -433,7 +603,7 @@ "minimum": 1, "maximum": 100, "default": 50, - "description": "每页返回的最大结果数" + "description": "Max results per page" }, "required": false, "name": "limit", @@ -442,7 +612,7 @@ { "schema": { "type": "string", - "description": "分页游标" + "description": "Pagination cursor" }, "required": false, "name": "cursor", @@ -451,7 +621,7 @@ ], "responses": { "200": { - "description": "包含分页信息的反馈数据", + "description": "Feedback data with pagination", "content": { "application/json": { "schema": { @@ -461,7 +631,112 @@ } }, "400": { - "description": "无效的查询参数", + "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 grouped by page", + "description": "Returns feedback counts (thumbs up/down, code snippets, total) aggregated by page path", + "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 (default 10)" + }, + "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", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/FeedbackGroupedByPageResponse" + } + } + } + }, + "400": { + "description": "Invalid query parameters", "content": { "application/json": { "schema": { @@ -471,7 +746,7 @@ } }, "500": { - "description": "服务器错误", + "description": "Server error", "content": { "application/json": { "schema": { @@ -485,8 +760,8 @@ }, "/v1/analytics/{projectId}/assistant": { "get": { - "summary": "获取 AI 助手会话记录", - "description": "返回分页后的 AI 助手会话历史", + "summary": "Get assistant conversations", + "description": "Returns paginated AI assistant conversation history", "tags": [ "Analytics" ], @@ -502,7 +777,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, @@ -512,7 +787,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, @@ -525,7 +800,7 @@ "minimum": 1, "maximum": 1000, "default": 100, - "description": "每页返回的最大结果数" + "description": "Max results per page" }, "required": false, "name": "limit", @@ -535,7 +810,7 @@ "schema": { "type": "string", "format": "ulid", - "description": "分页游标（ULID 格式）" + "description": "Pagination cursor (ULID format)" }, "required": false, "name": "cursor", @@ -544,7 +819,7 @@ ], "responses": { "200": { - "description": "包含分页信息的会话数据", + "description": "Conversation data with pagination", "content": { "application/json": { "schema": { @@ -554,7 +829,195 @@ } }, "400": { - "description": "无效的查询参数", + "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}/views": { + "get": { + "summary": "Get page views by path", + "description": "Returns per-path and site-wide content view event counts.", + "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", + "example": "2024-01-31" + }, + "required": false, + "name": "dateTo", + "in": "query" + }, + { + "schema": { + "type": "number", + "minimum": 1, + "maximum": 250, + "default": 50, + "description": "Max results per page (1–250, default 50)" + }, + "required": false, + "name": "limit", + "in": "query" + }, + { + "schema": { + "type": "number", + "minimum": 0, + "default": 0, + "description": "Number of rows to skip" + }, + "required": false, + "name": "offset", + "in": "query" + } + ], + "responses": { + "200": { + "description": "Site-wide totals and per-path view 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 by page", + "description": "Returns per-path and site-wide approximate distinct visitors by traffic type. `total` 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", + "example": "2024-01-31" + }, + "required": false, + "name": "dateTo", + "in": "query" + }, + { + "schema": { + "type": "number", + "minimum": 1, + "maximum": 250, + "default": 50, + "description": "Max results per page (1–250, default 50)" + }, + "required": false, + "name": "limit", + "in": "query" + }, + { + "schema": { + "type": "number", + "minimum": 0, + "default": 0, + "description": "Number of rows to skip" + }, + "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": { @@ -564,7 +1027,7 @@ } }, "500": { - "description": "服务器错误", + "description": "Server error", "content": { "application/json": { "schema": { diff --git a/zh/api/analytics/feedback-by-page.mdx b/zh/api/analytics/feedback-by-page.mdx new file mode 100644 index 000000000..5fb4facff --- /dev/null +++ b/zh/api/analytics/feedback-by-page.mdx @@ -0,0 +1,23 @@ +--- +title: "Get feedback by page" +description: "Retrieve feedback counts aggregated by page path, including thumbs up/down and code snippet counts." +openapi: /analytics.openapi.json GET /v1/analytics/{projectId}/feedback/by-page +keywords: ["analytics", "feedback", "by page", "export", "aggregated"] +--- + +## Usage + +Use this endpoint to export per-page feedback aggregates from your documentation. Each row includes counts for thumbs up, thumbs down, code snippet feedback, and a combined total. + +## Response fields + +Every item in the response includes: +- **path**: The documentation page path +- **thumbsUp**: Number of positive (thumbs up) ratings +- **thumbsDown**: Number of negative (thumbs down) ratings +- **code**: Number of code snippet feedback entries +- **total**: Combined feedback count across all types + +## Filtering + +Filter results by date range using `dateFrom` and `dateTo`, by feedback source using `source`, and by status using `status`. diff --git a/zh/api/analytics/views.mdx b/zh/api/analytics/views.mdx new file mode 100644 index 000000000..94727c967 --- /dev/null +++ b/zh/api/analytics/views.mdx @@ -0,0 +1,25 @@ +--- +title: "Get page views" +description: "Retrieve per-path and site-wide content view event counts." +openapi: /analytics.openapi.json GET /v1/analytics/{projectId}/views +keywords: ["analytics", "views", "page views", "export", "traffic"] +--- + +## Usage + +Use this endpoint to export per-page view counts from your documentation. Each row includes a breakdown of human and AI bot views, plus a combined total. + +Paginate through results using offset-based pagination. Increment `offset` by `limit` while `hasMore` is `true`. + +## Traffic breakdown + +Every response includes: +- **human**: Views from regular browser traffic +- **ai**: Views from AI bot crawlers (e.g. GPTBot, ClaudeBot) +- **total**: Combined view count across all traffic + +The `totals` object contains the same breakdown aggregated across your entire site for the selected date range. + +## Filtering + +Filter views by date range using `dateFrom` and `dateTo` parameters. diff --git a/zh/api/analytics/visitors.mdx b/zh/api/analytics/visitors.mdx new file mode 100644 index 000000000..fe7107a71 --- /dev/null +++ b/zh/api/analytics/visitors.mdx @@ -0,0 +1,25 @@ +--- +title: "Get unique visitors" +description: "Retrieve per-path and site-wide approximate distinct visitors by traffic type." +openapi: /analytics.openapi.json GET /v1/analytics/{projectId}/visitors +keywords: ["analytics", "visitors", "unique visitors", "export", "traffic"] +--- + +## Usage + +Use this endpoint to export per-page unique visitor counts from your documentation. Visitors are deduplicated by user ID or anonymous ID. + +Paginate through results using offset-based pagination. Increment `offset` by `limit` while `hasMore` is `true`. + +## Traffic breakdown + +Every response includes: +- **human**: Unique visitors from regular browser traffic +- **ai**: Unique visitors from AI bot crawlers (e.g. GPTBot, ClaudeBot) +- **total**: Combined unique visitor count across all traffic + +The `totals` object contains the same breakdown aggregated across your entire site for the selected date range. + +## Filtering + +Filter visitors by date range using `dateFrom` and `dateTo` parameters. diff --git a/zh/api/introduction.mdx b/zh/api/introduction.mdx index b1844beb4..f4fa36982 100644 --- a/zh/api/introduction.mdx +++ b/zh/api/introduction.mdx @@ -18,7 +18,10 @@ Mintlify 的 REST（Representational State Transfer）API 让你可以以编程 * [Create assistant message](/zh/api/assistant/create-assistant-message-v2)：将基于您的文档训练的 AI 助手嵌入到任意您选择的应用中。 * [搜索文档](/zh/api/assistant/search)：搜索您的文档。 * [获取用户反馈](/zh/api/analytics/feedback)：从您的文档中导出用户反馈。 +* [获取按页面反馈](/zh/api/analytics/feedback-by-page)：导出按页面汇总的反馈统计数据。 * [获取 AI 助手会话](/zh/api/analytics/assistant-conversations)：导出 AI 助手的会话历史。 +* [获取页面浏览量](/zh/api/analytics/views)：导出每页和全站内容浏览事件计数。 +* [获取独立访客](/zh/api/analytics/visitors)：导出每页和全站的近似独立访客数。
### 常见用例 @@ -28,7 +31,7 @@ Mintlify 的 REST（Representational State Transfer）API 让你可以以编程 * **CI/CD 集成**：在代码变更时，将文档更新作为部署流水线的一部分来执行，使用 [Trigger update](/zh/api/update/trigger)。 * **自定义集成**：使用 [Create assistant message](/zh/api/assistant/create-assistant-message-v2) 和 [Search documentation](/zh/api/assistant/search)，将 AI 助手嵌入到你的产品、支持门户或内部工具中。 * **自动化编辑**：使用 agent 任务，以编程方式大规模更新文档，配合 [Create agent job](/zh/api/agent/v2/create-agent-job)、[Get agent job](/zh/api/agent/v2/get-agent-job) 和 [Send follow-up message](/zh/api/agent/v2/send-message)。 -* **Analytics 导出**：使用 [Get user feedback](/zh/api/analytics/feedback) 和 [Get assistant conversations](/zh/api/analytics/assistant-conversations)，导出反馈和 AI 助手会话以进行外部分析。 +* **Analytics 导出**：使用 [Get user feedback](/zh/api/analytics/feedback)、[获取按页面反馈](/zh/api/analytics/feedback-by-page)、[Get assistant conversations](/zh/api/analytics/assistant-conversations)、[获取页面浏览量](/zh/api/analytics/views) 和 [获取独立访客](/zh/api/analytics/visitors)，导出反馈、AI 助手会话、页面浏览量和访客数据以进行外部分析。
## 认证 @@ -42,7 +45,7 @@ Mintlify 的 REST（Representational State Transfer）API 让你可以以编程 ### 管理员 API key
-使用管理员 API key 对发送到 [Trigger update](/zh/api/update/trigger)、[Get update status](/zh/api/update/status)、[Create agent job](/zh/api/agent/v2/create-agent-job)、[Get agent job](/zh/api/agent/v2/get-agent-job)、[Send follow-up message](/zh/api/agent/v2/send-message)、[Get user feedback](/zh/api/analytics/feedback) 和 [Get assistant conversations](/zh/api/analytics/assistant-conversations) 的请求进行身份验证。 +使用管理员 API key 对发送到 [Trigger update](/zh/api/update/trigger)、[Get update status](/zh/api/update/status)、[Create agent job](/zh/api/agent/v2/create-agent-job)、[Get agent job](/zh/api/agent/v2/get-agent-job)、[Send follow-up message](/zh/api/agent/v2/send-message)、[Get user feedback](/zh/api/analytics/feedback)、[获取按页面反馈](/zh/api/analytics/feedback-by-page)、[Get assistant conversations](/zh/api/analytics/assistant-conversations)、[获取页面浏览量](/zh/api/analytics/views) 和 [获取独立访客](/zh/api/analytics/visitors) 的请求进行身份验证。 管理员 API key 以 `mint_` 前缀开头。