diff --git a/analytics.openapi.json b/analytics.openapi.json index 552d3e1d2..c6e2dd1fa 100644 --- a/analytics.openapi.json +++ b/analytics.openapi.json @@ -358,6 +358,232 @@ "nextCursor", "hasMore" ] + }, + "FeedbackGroupedByPageResponse": { + "type": "object", + "properties": { + "feedback": { + "type": "array", + "description": "Feedback counts aggregated by documentation page path.", + "items": { + "type": "object", + "properties": { + "path": { + "type": "string", + "description": "The documentation page path." + }, + "thumbsUp": { + "type": "number", + "description": "Number of positive (thumbs up) contextual feedback entries." + }, + "thumbsDown": { + "type": "number", + "description": "Number of negative (thumbs down) contextual feedback entries." + }, + "code": { + "type": "number", + "description": "Number of code snippet feedback entries." + }, + "total": { + "type": "number", + "description": "Total feedback entries for this page." + } + }, + "required": [ + "path", + "thumbsUp", + "thumbsDown", + "code", + "total" + ] + } + }, + "hasMore": { + "type": "boolean", + "description": "Whether additional results are available beyond this page." + } + }, + "required": [ + "feedback", + "hasMore" + ] + }, + "SearchesResponse": { + "type": "object", + "properties": { + "searches": { + "type": "array", + "description": "Search terms ordered by hit count descending.", + "items": { + "type": "object", + "properties": { + "searchQuery": { + "type": "string", + "description": "The search term entered by users." + }, + "hits": { + "type": "number", + "description": "Number of times this term was searched." + }, + "ctr": { + "type": "number", + "description": "Click-through rate for this search term." + }, + "topClickedPage": { + "type": [ + "string", + "null" + ], + "description": "The most-clicked result path for this query, if any." + }, + "lastSearchedAt": { + "type": "string", + "description": "Timestamp of the last time this term was searched." + } + }, + "required": [ + "searchQuery", + "hits", + "ctr", + "topClickedPage", + "lastSearchedAt" + ] + } + }, + "totalSearches": { + "type": "integer", + "minimum": 0, + "description": "Total count of search events in the requested date range (sum of all hits, not distinct queries)." + }, + "nextCursor": { + "type": [ + "string", + "null" + ], + "description": "Opaque pagination cursor for the next page. Null if no more results." + } + }, + "required": [ + "searches", + "totalSearches", + "nextCursor" + ] + }, + "ViewsTrafficTotals": { + "type": "object", + "properties": { + "human": { + "type": "number", + "description": "Site-wide content view events from human traffic." + }, + "ai": { + "type": "number", + "description": "Site-wide content view events from AI bot traffic." + }, + "total": { + "type": "number", + "description": "Site-wide content view events." + } + }, + "required": ["human", "ai", "total"] + }, + "ViewsByPageResponse": { + "type": "object", + "properties": { + "totals": { + "$ref": "#/components/schemas/ViewsTrafficTotals", + "description": "Site-wide view totals for the date range." + }, + "views": { + "type": "array", + "description": "Per-page view counts.", + "items": { + "type": "object", + "properties": { + "path": { + "type": "string", + "description": "The documentation page path." + }, + "human": { + "type": "number", + "description": "Content view events on this path from human traffic." + }, + "ai": { + "type": "number", + "description": "Content view events on this path from AI bot traffic." + }, + "total": { + "type": "number", + "description": "Total content view events on this path." + } + }, + "required": ["path", "human", "ai", "total"] + } + }, + "hasMore": { + "type": "boolean", + "description": "Whether additional results are available beyond this page." + } + }, + "required": ["totals", "views", "hasMore"] + }, + "VisitorsTrafficTotals": { + "type": "object", + "properties": { + "human": { + "type": "number", + "description": "Site-wide unique visitors from human traffic." + }, + "ai": { + "type": "number", + "description": "Site-wide unique visitors from AI bot traffic." + }, + "total": { + "type": "number", + "description": "Site-wide approximate distinct visitors with any qualifying view (deduplicated across human and AI)." + } + }, + "required": ["human", "ai", "total"] + }, + "VisitorsByPageResponse": { + "type": "object", + "properties": { + "totals": { + "$ref": "#/components/schemas/VisitorsTrafficTotals", + "description": "Site-wide unique visitor totals for the date range." + }, + "visitors": { + "type": "array", + "description": "Per-page visitor counts.", + "items": { + "type": "object", + "properties": { + "path": { + "type": "string", + "description": "The documentation page path." + }, + "human": { + "type": "number", + "description": "Unique visitors from human traffic." + }, + "ai": { + "type": "number", + "description": "Unique visitors from AI bot traffic." + }, + "total": { + "type": "number", + "description": "Approximate distinct visitors with any qualifying view on this path (deduplicated across human and AI)." + } + }, + "required": ["path", "human", "ai", "total"] + } + }, + "hasMore": { + "type": "boolean", + "description": "Whether additional results are available beyond this page." + } + }, + "required": ["totals", "visitors", "hasMore"] } }, "parameters": { @@ -487,6 +713,111 @@ } } }, + "/v1/analytics/{projectId}/feedback/by-page": { + "get": { + "summary": "Get feedback by page", + "description": "Returns feedback counts aggregated by documentation page path (thumbs up/down for contextual feedback, code snippet count, and total per page)", + "tags": [ + "Analytics" + ], + "security": [ + { + "bearerAuth": [] + } + ], + "parameters": [ + { + "$ref": "#/components/parameters/projectId" + }, + { + "schema": { + "type": "string", + "description": "Date in ISO 8601 or YYYY-MM-DD format", + "example": "2024-01-01" + }, + "required": false, + "name": "dateFrom", + "in": "query" + }, + { + "schema": { + "type": "string", + "description": "Date in ISO 8601 or YYYY-MM-DD format. `dateTo` is an exclusive upper limit. Results include dates before, but not on, the specified date.", + "example": "2024-01-01" + }, + "required": false, + "name": "dateTo", + "in": "query" + }, + { + "schema": { + "type": "number", + "minimum": 1, + "maximum": 100, + "default": 10, + "description": "Max results per page" + }, + "required": false, + "name": "limit", + "in": "query" + }, + { + "schema": { + "type": "string", + "enum": [ + "code_snippet", + "contextual" + ], + "description": "Filter by feedback source" + }, + "required": false, + "name": "source", + "in": "query" + }, + { + "schema": { + "type": "string", + "description": "Comma-separated list of statuses to filter by" + }, + "required": false, + "name": "status", + "in": "query" + } + ], + "responses": { + "200": { + "description": "Per-page feedback aggregates with pagination flag", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/FeedbackGroupedByPageResponse" + } + } + } + }, + "400": { + "description": "Invalid query parameters", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AnalyticsErrorResponse" + } + } + } + }, + "500": { + "description": "Server error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AnalyticsErrorResponse" + } + } + } + } + } + } + }, "/v1/analytics/{projectId}/assistant": { "get": { "summary": "Get assistant conversations", @@ -579,6 +910,286 @@ } } } + }, + "/v1/analytics/{projectId}/searches": { + "get": { + "summary": "Get search queries", + "description": "Returns paginated documentation search terms for the date range, ordered by hit count descending. Each row includes click-through rate, the most-clicked result path for that query (if any), and the last time the term was searched. `totalSearches` is the total number of search query events in the same date range (sum of all hits, not distinct queries).", + "tags": [ + "Analytics" + ], + "security": [ + { + "bearerAuth": [] + } + ], + "parameters": [ + { + "$ref": "#/components/parameters/projectId" + }, + { + "schema": { + "type": "string", + "description": "Date in ISO 8601 or YYYY-MM-DD format", + "example": "2024-01-01" + }, + "required": false, + "name": "dateFrom", + "in": "query" + }, + { + "schema": { + "type": "string", + "description": "Date in ISO 8601 or YYYY-MM-DD format. `dateTo` is an exclusive upper limit. Results include dates before, but not on, the specified date.", + "example": "2024-01-01" + }, + "required": false, + "name": "dateTo", + "in": "query" + }, + { + "schema": { + "type": "number", + "minimum": 1, + "maximum": 100, + "default": 50, + "description": "Max search terms per page (ordered by hit count descending)" + }, + "required": false, + "name": "limit", + "in": "query" + }, + { + "schema": { + "type": "string", + "description": "Opaque pagination cursor from the previous response" + }, + "required": false, + "name": "cursor", + "in": "query" + } + ], + "responses": { + "200": { + "description": "Search term aggregates with pagination", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/SearchesResponse" + } + } + } + }, + "400": { + "description": "Invalid query parameters or cursor", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AnalyticsErrorResponse" + } + } + } + }, + "500": { + "description": "Server error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AnalyticsErrorResponse" + } + } + } + } + } + } + }, + "/v1/analytics/{projectId}/views": { + "get": { + "summary": "Get page views", + "description": "Returns per-path and site-wide content view event counts, split by human and AI traffic.", + "tags": [ + "Analytics" + ], + "security": [ + { + "bearerAuth": [] + } + ], + "parameters": [ + { + "$ref": "#/components/parameters/projectId" + }, + { + "schema": { + "type": "string", + "description": "Date in ISO 8601 or YYYY-MM-DD format", + "example": "2024-01-01" + }, + "required": false, + "name": "dateFrom", + "in": "query" + }, + { + "schema": { + "type": "string", + "description": "Date in ISO 8601 or YYYY-MM-DD format. `dateTo` is an exclusive upper limit. Results include dates before, but not on, the specified date.", + "example": "2024-01-01" + }, + "required": false, + "name": "dateTo", + "in": "query" + }, + { + "schema": { + "type": "integer", + "minimum": 1, + "maximum": 250, + "default": 50, + "description": "Max results per page (1-250, default 50). Increment offset by limit while hasMore is true to paginate." + }, + "required": false, + "name": "limit", + "in": "query" + }, + { + "schema": { + "type": "integer", + "minimum": 0, + "default": 0, + "description": "Number of rows to skip. Use offset = (page - 1) * limit for page-based access." + }, + "required": false, + "name": "offset", + "in": "query" + } + ], + "responses": { + "200": { + "description": "Site-wide and per-path content view event counts", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ViewsByPageResponse" + } + } + } + }, + "400": { + "description": "Invalid query parameters", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AnalyticsErrorResponse" + } + } + } + }, + "500": { + "description": "Server error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AnalyticsErrorResponse" + } + } + } + } + } + } + }, + "/v1/analytics/{projectId}/visitors": { + "get": { + "summary": "Get unique visitors", + "description": "Returns per-path and site-wide approximate distinct visitors by traffic type. The `total` field is deduplicated across human and AI (union of distinct visitor IDs with any qualifying content view).", + "tags": [ + "Analytics" + ], + "security": [ + { + "bearerAuth": [] + } + ], + "parameters": [ + { + "$ref": "#/components/parameters/projectId" + }, + { + "schema": { + "type": "string", + "description": "Date in ISO 8601 or YYYY-MM-DD format", + "example": "2024-01-01" + }, + "required": false, + "name": "dateFrom", + "in": "query" + }, + { + "schema": { + "type": "string", + "description": "Date in ISO 8601 or YYYY-MM-DD format. `dateTo` is an exclusive upper limit. Results include dates before, but not on, the specified date.", + "example": "2024-01-01" + }, + "required": false, + "name": "dateTo", + "in": "query" + }, + { + "schema": { + "type": "integer", + "minimum": 1, + "maximum": 250, + "default": 50, + "description": "Max results per page (1-250, default 50). Increment offset by limit while hasMore is true to paginate." + }, + "required": false, + "name": "limit", + "in": "query" + }, + { + "schema": { + "type": "integer", + "minimum": 0, + "default": 0, + "description": "Number of rows to skip. Use offset = (page - 1) * limit for page-based access." + }, + "required": false, + "name": "offset", + "in": "query" + } + ], + "responses": { + "200": { + "description": "Site-wide totals and per-path visitor counts", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/VisitorsByPageResponse" + } + } + } + }, + "400": { + "description": "Invalid query parameters", + "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..d08f97a23 --- /dev/null +++ b/api/analytics/feedback-by-page.mdx @@ -0,0 +1,18 @@ +--- +title: "Get feedback by page" +description: "Retrieve user feedback counts aggregated by documentation page, including thumbs up/down ratings and code snippet feedback." +openapi: /analytics.openapi.json GET /v1/analytics/{projectId}/feedback/by-page +keywords: ["analytics", "feedback", "export", "by page", "aggregated"] +--- + +## Usage + +Use this endpoint to export user feedback aggregated by documentation page path. Each entry shows the total feedback count for a page, broken down by type. + +## Filtering + +Filter feedback by: +- **Date range**: Use `dateFrom` and `dateTo` to limit results to a specific time period +- **Source**: Filter by `code_snippet` or `contextual` feedback types +- **Status**: Filter by status values like `pending`, `in_progress`, `resolved`, or `dismissed` + diff --git a/api/analytics/searches.mdx b/api/analytics/searches.mdx new file mode 100644 index 000000000..5cda5ca54 --- /dev/null +++ b/api/analytics/searches.mdx @@ -0,0 +1,17 @@ +--- +title: "Get search queries" +description: "Retrieve documentation search terms with hit counts, click-through rates, and top clicked pages." +openapi: /analytics.openapi.json GET /v1/analytics/{projectId}/searches +keywords: ["analytics", "search", "export", "queries", "search terms"] +--- + +## Usage + +Use this endpoint to export documentation search analytics. Results are ordered by hit count descending, showing which terms your users search for most. + +Paginate through results using the `nextCursor` parameter returned in the response. Continue fetching while `nextCursor` is not null. + +## Filtering + +Filter search data by date range using `dateFrom` and `dateTo` parameters. + diff --git a/api/analytics/views.mdx b/api/analytics/views.mdx new file mode 100644 index 000000000..599f5e949 --- /dev/null +++ b/api/analytics/views.mdx @@ -0,0 +1,17 @@ +--- +title: "Get page views" +description: "Retrieve per-page and site-wide content view counts, split by human and AI traffic." +openapi: /analytics.openapi.json GET /v1/analytics/{projectId}/views +keywords: ["analytics", "views", "page views", "traffic", "export"] +--- + +## Usage + +Use this endpoint to export page view analytics. Results include both site-wide totals and per-page breakdowns, split by human and AI traffic. + +Paginate through results using offset-based pagination. Increment `offset` by `limit` while `hasMore` is true. + +## Filtering + +Filter view data by date range using `dateFrom` and `dateTo` parameters. + diff --git a/api/analytics/visitors.mdx b/api/analytics/visitors.mdx new file mode 100644 index 000000000..b00949c0c --- /dev/null +++ b/api/analytics/visitors.mdx @@ -0,0 +1,17 @@ +--- +title: "Get unique visitors" +description: "Retrieve per-page and site-wide approximate unique visitor counts, split by human and AI traffic." +openapi: /analytics.openapi.json GET /v1/analytics/{projectId}/visitors +keywords: ["analytics", "visitors", "unique visitors", "traffic", "export"] +--- + +## Usage + +Use this endpoint to export unique visitor analytics. Results include both site-wide totals and per-page breakdowns, split by human and AI traffic. The `total` field is deduplicated across human and AI traffic. + +Paginate through results using offset-based pagination. Increment `offset` by `limit` while `hasMore` is true. + +## Filtering + +Filter visitor data by date range using `dateFrom` and `dateTo` parameters. + diff --git a/api/introduction.mdx b/api/introduction.mdx index d5b28d6d2..a520012ea 100644 --- a/api/introduction.mdx +++ b/api/introduction.mdx @@ -16,7 +16,11 @@ The Mintlify REST (Representational State Transfer) API enables you to programma - [Create assistant message](/api/assistant/create-assistant-message-v2): Embed the assistant, trained on your docs, into any application of your choosing. - [Search documentation](/api/assistant/search): Search through your documentation. - [Get user feedback](/api/analytics/feedback): Export user feedback from your documentation. +- [Get feedback by page](/api/analytics/feedback-by-page): Export feedback counts aggregated by page. - [Get assistant conversations](/api/analytics/assistant-conversations): Export AI assistant conversation history. +- [Get search queries](/api/analytics/searches): Export documentation search terms and analytics. +- [Get page views](/api/analytics/views): Export per-page and site-wide content view counts. +- [Get unique visitors](/api/analytics/visitors): Export per-page and site-wide unique visitor counts. ### Common use cases @@ -24,7 +28,7 @@ The Mintlify REST (Representational State Transfer) API enables you to programma - **CI/CD integration**: Update documentation as part of your deployment pipeline when code changes with [Trigger update](/api/update/trigger). - **Custom integrations**: Embed the AI assistant into your product, support portal, or internal tools with [Create assistant message](/api/assistant/create-assistant-message-v2) and [Search documentation](/api/assistant/search). - **Automated editing**: Use agent jobs to programmatically update documentation at scale with [Create agent job](/api/agent/v2/create-agent-job), [Get agent job](/api/agent/v2/get-agent-job), and [Send follow-up message](/api/agent/v2/send-message). -- **Analytics export**: Export feedback 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, search analytics, page views, and visitor data for external analysis with [Get user feedback](/api/analytics/feedback), [Get feedback by page](/api/analytics/feedback-by-page), [Get assistant conversations](/api/analytics/assistant-conversations), [Get search queries](/api/analytics/searches), [Get page views](/api/analytics/views), and [Get unique visitors](/api/analytics/visitors). ## Authentication @@ -34,7 +38,7 @@ You can create up to 10 API keys per hour per organization. ### Admin API key -Use the admin API key to authenticate requests to [Trigger update](/api/update/trigger), [Get update status](/api/update/status), [Create agent job](/api/agent/v2/create-agent-job), [Get agent job](/api/agent/v2/get-agent-job), [Send follow-up message](/api/agent/v2/send-message), [Get user feedback](/api/analytics/feedback), 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 search queries](/api/analytics/searches), [Get page views](/api/analytics/views), and [Get unique visitors](/api/analytics/visitors). Admin API keys begin with the `mint_` prefix. diff --git a/docs.json b/docs.json index 36162ba31..3f9017eca 100644 --- a/docs.json +++ b/docs.json @@ -373,7 +373,11 @@ "icon": "chart-line", "pages": [ "api/analytics/feedback", - "api/analytics/assistant-conversations" + "api/analytics/feedback-by-page", + "api/analytics/assistant-conversations", + "api/analytics/searches", + "api/analytics/views", + "api/analytics/visitors" ] } ]