diff --git a/analytics.openapi.json b/analytics.openapi.json index e7b80c1b6..24237b659 100644 --- a/analytics.openapi.json +++ b/analytics.openapi.json @@ -246,6 +246,55 @@ "hasMore" ] }, + "FeedbackGroupedByPageResponse": { + "type": "object", + "properties": { + "feedback": { + "type": "array", + "description": "List of per-page feedback aggregates.", + "items": { + "type": "object", + "properties": { + "path": { + "type": "string", + "description": "The page path." + }, + "thumbsUp": { + "type": "number", + "description": "Number of positive (thumbs up) contextual feedback entries for this page." + }, + "thumbsDown": { + "type": "number", + "description": "Number of negative (thumbs down) contextual feedback entries for this page." + }, + "code": { + "type": "number", + "description": "Number of code snippet feedback entries for this page." + }, + "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" + ] + }, "AnalyticsErrorResponse": { "type": "object", "properties": { @@ -355,6 +404,127 @@ "nextCursor", "hasMore" ] + }, + "TrafficTotals": { + "type": "object", + "description": "Site-wide traffic totals for the date range.", + "properties": { + "human": { + "type": "number", + "description": "Count from human traffic." + }, + "ai": { + "type": "number", + "description": "Count from AI bot traffic." + }, + "total": { + "type": "number", + "description": "Total count across all traffic types." + } + }, + "required": [ + "human", + "ai", + "total" + ] + }, + "ViewsByPageResponse": { + "type": "object", + "properties": { + "totals": { + "$ref": "#/components/schemas/TrafficTotals", + "description": "Site-wide content view event totals for the date range." + }, + "views": { + "type": "array", + "description": "Per-page content view event counts.", + "items": { + "type": "object", + "properties": { + "path": { + "type": "string", + "description": "The 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" + ] + }, + "VisitorsByPageResponse": { + "type": "object", + "properties": { + "totals": { + "$ref": "#/components/schemas/TrafficTotals", + "description": "Site-wide unique visitor totals for the date range." + }, + "visitors": { + "type": "array", + "description": "Per-page unique visitor counts.", + "items": { + "type": "object", + "properties": { + "path": { + "type": "string", + "description": "The 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": { @@ -483,6 +653,111 @@ } } }, + "/v1/analytics/{projectId}/feedback/by-page": { + "get": { + "summary": "Get feedback grouped by page", + "description": "Returns feedback counts (thumbs up, thumbs 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": "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", @@ -575,7 +850,195 @@ } } } + }, + "/v1/analytics/{projectId}/views": { + "get": { + "summary": "Get page views by path", + "description": "Returns per-path and site-wide content view event counts, broken down by human and AI bot 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": "number", + "minimum": 1, + "maximum": 250, + "default": 50, + "description": "Max results per page (1\u2013250, default 50). Increment offset by limit while hasMore is true to paginate." + }, + "required": false, + "name": "limit", + "in": "query" + }, + { + "schema": { + "type": "number", + "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 by page", + "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": "number", + "minimum": 1, + "maximum": 250, + "default": 50, + "description": "Max results per page (1\u2013250, default 50). Increment offset by limit while hasMore is true to paginate." + }, + "required": false, + "name": "limit", + "in": "query" + }, + { + "schema": { + "type": "number", + "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": {} -} \ No newline at end of file +} diff --git a/api/analytics/feedback-by-page.mdx b/api/analytics/feedback-by-page.mdx new file mode 100644 index 000000000..1d4979373 --- /dev/null +++ b/api/analytics/feedback-by-page.mdx @@ -0,0 +1,28 @@ +--- +title: "Get feedback by page" +description: "Retrieve user feedback counts aggregated by page path, including thumbs up, thumbs down, and code snippet totals." +openapi: /analytics.openapi.json GET /v1/analytics/{projectId}/feedback/by-page +keywords: ["analytics", "feedback", "export", "per-page", "aggregated"] +--- + +## Usage + +Use this endpoint to get a summary of feedback grouped by page path. Each entry includes the count of thumbs up, thumbs down, and code snippet feedback for that page. + +Paginate through results by incrementing the `limit` parameter. Continue fetching while `hasMore` is `true`. + +## Filtering + +Filter feedback by: +- **Date range**: Use `dateFrom` and `dateTo` to limit results to a specific time period +- **Source**: Filter by `code_snippet` or `contextual` feedback types +- **Status**: Filter by status values like `pending`, `in_progress`, `resolved`, or `dismissed` + +## Response data + +Each entry in the response includes: +- **path**: The page path +- **thumbsUp**: Count of positive contextual feedback +- **thumbsDown**: Count of negative contextual feedback +- **code**: Count of code snippet feedback +- **total**: Total feedback entries for the page diff --git a/api/analytics/views.mdx b/api/analytics/views.mdx new file mode 100644 index 000000000..60179be9d --- /dev/null +++ b/api/analytics/views.mdx @@ -0,0 +1,23 @@ +--- +title: "Get page views" +description: "Retrieve per-page and site-wide content view event counts, broken down by human and AI bot traffic." +openapi: /analytics.openapi.json GET /v1/analytics/{projectId}/views +keywords: ["analytics", "views", "page views", "export", "traffic"] +--- + +## Usage + +Use this endpoint to export page view counts from your documentation. Views are broken down by human and AI bot traffic for each page path, along with site-wide totals. + +Paginate through results using offset-based pagination. Increment `offset` by `limit` while `hasMore` is `true`. + +## Filtering + +Filter views by date range using `dateFrom` and `dateTo` parameters. + +## Response data + +The response includes: +- **totals**: Site-wide view counts broken down by `human`, `ai`, and `total` +- **views**: Per-page view counts, each with `path`, `human`, `ai`, and `total` fields +- **hasMore**: Whether additional pages of results are available diff --git a/api/analytics/visitors.mdx b/api/analytics/visitors.mdx new file mode 100644 index 000000000..3ec620dba --- /dev/null +++ b/api/analytics/visitors.mdx @@ -0,0 +1,25 @@ +--- +title: "Get unique visitors" +description: "Retrieve per-page and site-wide unique visitor counts, broken down by human and AI bot traffic." +openapi: /analytics.openapi.json GET /v1/analytics/{projectId}/visitors +keywords: ["analytics", "visitors", "unique visitors", "export", "traffic"] +--- + +## Usage + +Use this endpoint to export unique visitor counts from your documentation. Visitors are broken down by human and AI bot traffic for each page path, along with site-wide totals. + +The `total` field represents the approximate number of distinct visitors across both human and AI traffic, deduplicated by visitor ID. + +Paginate through results using offset-based pagination. Increment `offset` by `limit` while `hasMore` is `true`. + +## Filtering + +Filter visitors by date range using `dateFrom` and `dateTo` parameters. + +## Response data + +The response includes: +- **totals**: Site-wide unique visitor counts broken down by `human`, `ai`, and `total` +- **visitors**: Per-page visitor counts, each with `path`, `human`, `ai`, and `total` fields +- **hasMore**: Whether additional pages of results are available diff --git a/api/introduction.mdx b/api/introduction.mdx index d5b28d6d2..d0d2098fe 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-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 +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, 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 af1132fe7..4666788a5 100644 --- a/docs.json +++ b/docs.json @@ -373,7 +373,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" ] } ]