From 4a0376e7aeae4f077e10740b90c3ed24fb5e690a Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Tue, 24 Mar 2026 23:31:45 +0000 Subject: [PATCH] Add documentation for feedback-by-page analytics endpoint Generated-By: mintlify-agent --- analytics.openapi.json | 154 +++++++++++++++++++++++++++++ api/analytics/feedback-by-page.mdx | 29 ++++++ api/introduction.mdx | 5 +- docs.json | 1 + 4 files changed, 187 insertions(+), 2 deletions(-) create mode 100644 api/analytics/feedback-by-page.mdx diff --git a/analytics.openapi.json b/analytics.openapi.json index e7b80c1b6..5175d3eee 100644 --- a/analytics.openapi.json +++ b/analytics.openapi.json @@ -246,6 +246,55 @@ "hasMore" ] }, + "FeedbackGroupedByPageResponse": { + "type": "object", + "properties": { + "feedback": { + "type": "array", + "description": "List of per-page feedback aggregates, sorted by total descending.", + "items": { + "type": "object", + "properties": { + "path": { + "type": "string", + "description": "The documentation page path." + }, + "thumbsUp": { + "type": "number", + "description": "Count of positive contextual feedback." + }, + "thumbsDown": { + "type": "number", + "description": "Count of negative contextual feedback." + }, + "code": { + "type": "number", + "description": "Count of code snippet feedback." + }, + "total": { + "type": "number", + "description": "Total feedback count (thumbsUp + thumbsDown + code)." + } + }, + "required": [ + "path", + "thumbsUp", + "thumbsDown", + "code", + "total" + ] + } + }, + "hasMore": { + "type": "boolean", + "description": "Whether additional results are available beyond this page." + } + }, + "required": [ + "feedback", + "hasMore" + ] + }, "AnalyticsErrorResponse": { "type": "object", "properties": { @@ -483,6 +532,111 @@ } } }, + "/v1/analytics/{projectId}/feedback/by-page": { + "get": { + "summary": "Get feedback grouped by page", + "description": "Returns feedback counts aggregated by documentation page path, including thumbs up, thumbs down, and code snippet counts per page. Results are sorted by total feedback count in descending order.", + "tags": [ + "Analytics" + ], + "security": [ + { + "bearerAuth": [] + } + ], + "parameters": [ + { + "$ref": "#/components/parameters/projectId" + }, + { + "schema": { + "type": "string", + "description": "Date in ISO 8601 or YYYY-MM-DD format", + "example": "2024-01-01" + }, + "required": false, + "name": "dateFrom", + "in": "query" + }, + { + "schema": { + "type": "string", + "description": "Date in ISO 8601 or YYYY-MM-DD format. `dateTo` is an exclusive upper limit. Results include dates before, but not on, the specified date.", + "example": "2024-01-01" + }, + "required": false, + "name": "dateTo", + "in": "query" + }, + { + "schema": { + "type": "string", + "enum": [ + "code_snippet", + "contextual" + ], + "description": "Filter by feedback source" + }, + "required": false, + "name": "source", + "in": "query" + }, + { + "schema": { + "type": "string", + "description": "Comma-separated list of statuses to filter by" + }, + "required": false, + "name": "status", + "in": "query" + }, + { + "schema": { + "type": "number", + "minimum": 1, + "maximum": 100, + "default": 10, + "description": "Max results per page" + }, + "required": false, + "name": "limit", + "in": "query" + } + ], + "responses": { + "200": { + "description": "Per-page feedback aggregates", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/FeedbackGroupedByPageResponse" + } + } + } + }, + "400": { + "description": "Invalid query parameters", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AnalyticsErrorResponse" + } + } + } + }, + "500": { + "description": "Server error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AnalyticsErrorResponse" + } + } + } + } + } + } + }, "/v1/analytics/{projectId}/assistant": { "get": { "summary": "Get assistant conversations", diff --git a/api/analytics/feedback-by-page.mdx b/api/analytics/feedback-by-page.mdx new file mode 100644 index 000000000..d538d602c --- /dev/null +++ b/api/analytics/feedback-by-page.mdx @@ -0,0 +1,29 @@ +--- +title: "Get feedback by page" +description: "Retrieve feedback counts aggregated by documentation page, including thumbs up, thumbs down, and code snippet totals." +openapi: /analytics.openapi.json GET /v1/analytics/{projectId}/feedback/by-page +keywords: ["analytics", "feedback", "export", "aggregated feedback", "page feedback"] +--- + +## Usage + +Use this endpoint to get a high-level summary of feedback across your documentation pages. Instead of returning individual feedback entries, this endpoint groups feedback by page path and returns aggregate counts. + +Results are sorted by total feedback count in descending order, so your most-discussed pages appear first. Use the `hasMore` field to determine if additional pages of results are available. + +## Filtering + +Filter aggregated feedback by: +- **Date range**: Use `dateFrom` and `dateTo` to limit results to a specific time period +- **Source**: Filter by `code_snippet` or `contextual` feedback types +- **Status**: Filter by status values like `pending`, `in_progress`, `resolved`, or `dismissed` + +## Response fields + +Each item in the `feedback` array contains: + +- **`path`**: The documentation page path +- **`thumbsUp`**: Count of positive contextual feedback (page rated as helpful) +- **`thumbsDown`**: Count of negative contextual feedback (page rated as not helpful) +- **`code`**: Count of code snippet feedback +- **`total`**: Sum of all feedback types (`thumbsUp + thumbsDown + code`) diff --git a/api/introduction.mdx b/api/introduction.mdx index d5b28d6d2..7a4f2d69d 100644 --- a/api/introduction.mdx +++ b/api/introduction.mdx @@ -16,6 +16,7 @@ The Mintlify REST (Representational State Transfer) API enables you to programma - [Create assistant message](/api/assistant/create-assistant-message-v2): Embed the assistant, trained on your docs, into any application of your choosing. - [Search documentation](/api/assistant/search): Search through your documentation. - [Get user feedback](/api/analytics/feedback): Export user feedback from your documentation. +- [Get feedback by page](/api/analytics/feedback-by-page): Get feedback counts aggregated by documentation page. - [Get assistant conversations](/api/analytics/assistant-conversations): Export AI assistant conversation history. ### Common use cases @@ -24,7 +25,7 @@ The Mintlify REST (Representational State Transfer) API enables you to programma - **CI/CD integration**: Update documentation as part of your deployment pipeline when code changes with [Trigger update](/api/update/trigger). - **Custom integrations**: Embed the AI assistant into your product, support portal, or internal tools with [Create assistant message](/api/assistant/create-assistant-message-v2) and [Search documentation](/api/assistant/search). - **Automated editing**: Use agent jobs to programmatically update documentation at scale with [Create agent job](/api/agent/v2/create-agent-job), [Get agent job](/api/agent/v2/get-agent-job), and [Send follow-up message](/api/agent/v2/send-message). -- **Analytics export**: Export feedback and assistant conversations for external analysis with [Get user feedback](/api/analytics/feedback) and [Get assistant conversations](/api/analytics/assistant-conversations). +- **Analytics export**: Export feedback and assistant conversations for external analysis with [Get user feedback](/api/analytics/feedback), [Get feedback by page](/api/analytics/feedback-by-page), and [Get assistant conversations](/api/analytics/assistant-conversations). ## Authentication @@ -34,7 +35,7 @@ You can create up to 10 API keys per hour per organization. ### Admin API key -Use the admin API key to authenticate requests to [Trigger update](/api/update/trigger), [Get update status](/api/update/status), [Create agent job](/api/agent/v2/create-agent-job), [Get agent job](/api/agent/v2/get-agent-job), [Send follow-up message](/api/agent/v2/send-message), [Get user feedback](/api/analytics/feedback), and [Get assistant conversations](/api/analytics/assistant-conversations). +Use the admin API key to authenticate requests to [Trigger update](/api/update/trigger), [Get update status](/api/update/status), [Create agent job](/api/agent/v2/create-agent-job), [Get agent job](/api/agent/v2/get-agent-job), [Send follow-up message](/api/agent/v2/send-message), [Get user feedback](/api/analytics/feedback), [Get feedback by page](/api/analytics/feedback-by-page), and [Get assistant conversations](/api/analytics/assistant-conversations). Admin API keys begin with the `mint_` prefix. diff --git a/docs.json b/docs.json index 53867420a..bf1e8f633 100644 --- a/docs.json +++ b/docs.json @@ -371,6 +371,7 @@ "icon": "chart-line", "pages": [ "api/analytics/feedback", + "api/analytics/feedback-by-page", "api/analytics/assistant-conversations" ] }