mirror of
https://github.com/mintlify/docs.git
synced 2026-09-14 13:35:46 +08:00
Ethan Palm
1361 lines
44 KiB
JSON
1361 lines
44 KiB
JSON
{
|
|
"openapi": "3.1.0",
|
|
"info": {
|
|
"title": "Mintlify Analytics Export API",
|
|
"version": "1.0.0",
|
|
"description": "API for exporting documentation analytics data"
|
|
},
|
|
"servers": [
|
|
{
|
|
"url": "https://api.mintlify.com",
|
|
"description": "Production"
|
|
}
|
|
],
|
|
"security": [
|
|
{
|
|
"bearerAuth": []
|
|
}
|
|
],
|
|
"components": {
|
|
"securitySchemes": {
|
|
"bearerAuth": {
|
|
"type": "http",
|
|
"scheme": "bearer",
|
|
"description": "The Authorization header expects a Bearer token. Use an admin API key (prefixed with `mint_`). This is a server-side secret key. Generate one on the [API keys page](https://app.mintlify.com/settings/organization/api-keys) in your dashboard."
|
|
}
|
|
},
|
|
"schemas": {
|
|
"projectId": {
|
|
"type": "string",
|
|
"description": "Your project ID. Can be copied from the [API keys](https://app.mintlify.com/settings/organization/api-keys) page in your dashboard."
|
|
},
|
|
"FeedbackResponse": {
|
|
"type": "object",
|
|
"properties": {
|
|
"feedback": {
|
|
"type": "array",
|
|
"description": "List of feedback entries.",
|
|
"items": {
|
|
"anyOf": [
|
|
{
|
|
"description": "Returned when source is `contextual`. Includes whether the user found the page helpful and an optional contact email.",
|
|
"type": "object",
|
|
"properties": {
|
|
"id": {
|
|
"type": "string",
|
|
"description": "Unique feedback identifier."
|
|
},
|
|
"path": {
|
|
"type": "string",
|
|
"description": "The path or URL to the source document."
|
|
},
|
|
"comment": {
|
|
"type": [
|
|
"string",
|
|
"null"
|
|
],
|
|
"description": "Text of the user's feedback comment."
|
|
},
|
|
"createdAt": {
|
|
"type": [
|
|
"string",
|
|
"null"
|
|
],
|
|
"description": "Timestamp when the feedback was submitted."
|
|
},
|
|
"source": {
|
|
"type": "string",
|
|
"enum": [
|
|
"code_snippet",
|
|
"contextual",
|
|
"agent",
|
|
"thumbs_only"
|
|
],
|
|
"description": "Where the feedback originated. `code_snippet` is feedback on a code block, `contextual` is page-level feedback, `agent` is feedback submitted by a third-party AI agent, `thumbs_only` is a thumbs up/down vote."
|
|
},
|
|
"status": {
|
|
"type": "string",
|
|
"enum": [
|
|
"pending",
|
|
"in_progress",
|
|
"resolved",
|
|
"dismissed"
|
|
],
|
|
"description": "Current review status of the feedback."
|
|
},
|
|
"helpful": {
|
|
"type": "boolean",
|
|
"description": "Whether the user found the content helpful."
|
|
},
|
|
"contact": {
|
|
"type": [
|
|
"string",
|
|
"null"
|
|
],
|
|
"description": "Email address the user provided for follow-up."
|
|
}
|
|
},
|
|
"required": [
|
|
"id",
|
|
"path",
|
|
"comment",
|
|
"createdAt",
|
|
"source",
|
|
"status",
|
|
"helpful",
|
|
"contact"
|
|
]
|
|
},
|
|
{
|
|
"description": "Returned when source is `code_snippet`. Includes the code, filename, and language of the snippet the feedback relates to.",
|
|
"type": "object",
|
|
"properties": {
|
|
"id": {
|
|
"type": "string",
|
|
"description": "Unique feedback identifier."
|
|
},
|
|
"path": {
|
|
"type": "string",
|
|
"description": "The path or URL to the source document."
|
|
},
|
|
"comment": {
|
|
"type": [
|
|
"string",
|
|
"null"
|
|
],
|
|
"description": "Text of the user's feedback comment."
|
|
},
|
|
"createdAt": {
|
|
"type": [
|
|
"string",
|
|
"null"
|
|
],
|
|
"description": "Timestamp when the feedback was submitted."
|
|
},
|
|
"source": {
|
|
"type": "string",
|
|
"enum": [
|
|
"code_snippet",
|
|
"contextual",
|
|
"agent",
|
|
"thumbs_only"
|
|
],
|
|
"description": "Where the feedback originated. `code_snippet` is feedback on a code block, `contextual` is page-level feedback, `agent` is feedback submitted by a third-party AI agent, `thumbs_only` is a thumbs up/down vote."
|
|
},
|
|
"status": {
|
|
"type": "string",
|
|
"enum": [
|
|
"pending",
|
|
"in_progress",
|
|
"resolved",
|
|
"dismissed"
|
|
],
|
|
"description": "Current review status of the feedback."
|
|
},
|
|
"code": {
|
|
"type": "string",
|
|
"description": "The code snippet the feedback relates to."
|
|
},
|
|
"filename": {
|
|
"type": [
|
|
"string",
|
|
"null"
|
|
],
|
|
"description": "Filename associated with the code snippet."
|
|
},
|
|
"lang": {
|
|
"type": [
|
|
"string",
|
|
"null"
|
|
],
|
|
"description": "Programming language of the code snippet."
|
|
}
|
|
},
|
|
"required": [
|
|
"id",
|
|
"path",
|
|
"comment",
|
|
"createdAt",
|
|
"source",
|
|
"status",
|
|
"code",
|
|
"filename",
|
|
"lang"
|
|
]
|
|
},
|
|
{
|
|
"description": "Returned when source is `agent` or `thumbs_only`. Contains base feedback fields only.",
|
|
"type": "object",
|
|
"properties": {
|
|
"id": {
|
|
"type": "string",
|
|
"description": "Unique feedback identifier."
|
|
},
|
|
"path": {
|
|
"type": "string",
|
|
"description": "The path or URL to the source document."
|
|
},
|
|
"comment": {
|
|
"type": [
|
|
"string",
|
|
"null"
|
|
],
|
|
"description": "Text of the user's feedback comment."
|
|
},
|
|
"createdAt": {
|
|
"type": [
|
|
"string",
|
|
"null"
|
|
],
|
|
"description": "Timestamp when the feedback was submitted."
|
|
},
|
|
"source": {
|
|
"type": "string",
|
|
"enum": [
|
|
"code_snippet",
|
|
"contextual",
|
|
"agent",
|
|
"thumbs_only"
|
|
],
|
|
"description": "Where the feedback originated. `code_snippet` is feedback on a code block, `contextual` is page-level feedback, `agent` is feedback submitted by a third-party AI agent, `thumbs_only` is a thumbs up/down vote."
|
|
},
|
|
"status": {
|
|
"type": "string",
|
|
"enum": [
|
|
"pending",
|
|
"in_progress",
|
|
"resolved",
|
|
"dismissed"
|
|
],
|
|
"description": "Current review status of the feedback."
|
|
}
|
|
},
|
|
"required": [
|
|
"id",
|
|
"path",
|
|
"comment",
|
|
"createdAt",
|
|
"source",
|
|
"status"
|
|
]
|
|
}
|
|
]
|
|
}
|
|
},
|
|
"nextCursor": {
|
|
"type": [
|
|
"string",
|
|
"null"
|
|
],
|
|
"description": "Cursor to retrieve the next page of results. Null if no more results."
|
|
},
|
|
"hasMore": {
|
|
"type": "boolean",
|
|
"description": "Whether additional results are available beyond this page."
|
|
}
|
|
},
|
|
"required": [
|
|
"feedback",
|
|
"nextCursor",
|
|
"hasMore"
|
|
]
|
|
},
|
|
"AnalyticsErrorResponse": {
|
|
"type": "object",
|
|
"properties": {
|
|
"error": {
|
|
"type": "string",
|
|
"description": "Error message describing what went wrong."
|
|
},
|
|
"details": {
|
|
"type": "array",
|
|
"description": "Additional details about the error.",
|
|
"items": {
|
|
"type": "object",
|
|
"properties": {
|
|
"message": {
|
|
"type": "string",
|
|
"description": "Description of a specific validation or processing error."
|
|
}
|
|
},
|
|
"required": [
|
|
"message"
|
|
]
|
|
}
|
|
}
|
|
},
|
|
"required": [
|
|
"error"
|
|
]
|
|
},
|
|
"AssistantConversationsResponse": {
|
|
"type": "object",
|
|
"properties": {
|
|
"conversations": {
|
|
"type": "array",
|
|
"description": "List of assistant conversations.",
|
|
"items": {
|
|
"type": "object",
|
|
"properties": {
|
|
"id": {
|
|
"type": "string",
|
|
"description": "Unique conversation identifier."
|
|
},
|
|
"timestamp": {
|
|
"type": "string",
|
|
"description": "Timestamp when the conversation occurred."
|
|
},
|
|
"query": {
|
|
"type": "string",
|
|
"description": "The user's question to the assistant."
|
|
},
|
|
"response": {
|
|
"type": "string",
|
|
"description": "The assistant's response."
|
|
},
|
|
"sources": {
|
|
"type": "array",
|
|
"description": "Documentation pages referenced in the response.",
|
|
"items": {
|
|
"type": "object",
|
|
"properties": {
|
|
"title": {
|
|
"type": "string",
|
|
"description": "Title of the referenced documentation page."
|
|
},
|
|
"url": {
|
|
"type": "string",
|
|
"description": "URL of the referenced documentation page."
|
|
}
|
|
},
|
|
"required": [
|
|
"title",
|
|
"url"
|
|
]
|
|
}
|
|
},
|
|
"resolutionStatus": {
|
|
"type": "string",
|
|
"enum": [
|
|
"answered",
|
|
"unanswered"
|
|
],
|
|
"description": "Whether the assistant successfully answered the user's question. `unanswered` indicates the assistant could not provide a satisfactory answer based on the available documentation."
|
|
},
|
|
"queryCategory": {
|
|
"type": [
|
|
"string",
|
|
"null"
|
|
],
|
|
"description": "Auto-assigned category grouping for the conversation, if applicable."
|
|
}
|
|
},
|
|
"required": [
|
|
"id",
|
|
"timestamp",
|
|
"query",
|
|
"response",
|
|
"sources",
|
|
"resolutionStatus",
|
|
"queryCategory"
|
|
]
|
|
}
|
|
},
|
|
"nextCursor": {
|
|
"type": [
|
|
"string",
|
|
"null"
|
|
],
|
|
"description": "Cursor to retrieve the next page of results. Null if no more results."
|
|
},
|
|
"hasMore": {
|
|
"type": "boolean",
|
|
"description": "Whether additional results are available beyond this page."
|
|
}
|
|
},
|
|
"required": [
|
|
"conversations",
|
|
"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"]
|
|
},
|
|
"AssistantCallerStatsResponse": {
|
|
"type": "object",
|
|
"properties": {
|
|
"web": {
|
|
"type": "number",
|
|
"description": "Number of assistant queries originating from the web (documentation site)."
|
|
},
|
|
"api": {
|
|
"type": "number",
|
|
"description": "Number of assistant queries originating from API calls."
|
|
},
|
|
"other": {
|
|
"type": "number",
|
|
"description": "Number of assistant queries from other sources (e.g., integrations, SDKs)."
|
|
},
|
|
"total": {
|
|
"type": "number",
|
|
"description": "Total assistant queries across all caller types."
|
|
}
|
|
},
|
|
"required": ["web", "api", "other", "total"]
|
|
},
|
|
"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": {
|
|
"projectId": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/projectId"
|
|
},
|
|
"required": true,
|
|
"name": "projectId",
|
|
"in": "path"
|
|
}
|
|
}
|
|
},
|
|
"paths": {
|
|
"/v1/analytics/{projectId}/feedback": {
|
|
"get": {
|
|
"summary": "Get user feedback",
|
|
"description": "Returns paginated user feedback with optional filtering. Paginate using the `cursor` from each response while `hasMore` is `true`.",
|
|
"tags": [
|
|
"Analytics"
|
|
],
|
|
"security": [
|
|
{
|
|
"bearerAuth": []
|
|
}
|
|
],
|
|
"x-codeSamples": [
|
|
{
|
|
"lang": "bash",
|
|
"label": "cURL",
|
|
"source": "curl \"https://api.mintlify.com/v1/analytics/my-project-id/feedback?dateFrom=2024-01-01&dateTo=2024-02-01&limit=50\" \\\n -H \"Authorization: Bearer mint_xxxxx\""
|
|
}
|
|
],
|
|
"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",
|
|
"agent",
|
|
"thumbs_only"
|
|
],
|
|
"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": 50,
|
|
"description": "Max results per page"
|
|
},
|
|
"required": false,
|
|
"name": "limit",
|
|
"in": "query"
|
|
},
|
|
{
|
|
"schema": {
|
|
"type": "string",
|
|
"description": "Pagination cursor"
|
|
},
|
|
"required": false,
|
|
"name": "cursor",
|
|
"in": "query"
|
|
}
|
|
],
|
|
"responses": {
|
|
"200": {
|
|
"description": "Feedback data with pagination",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/FeedbackResponse"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"400": {
|
|
"description": "Invalid query parameters",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/AnalyticsErrorResponse"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"500": {
|
|
"description": "Server error",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/AnalyticsErrorResponse"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"/v1/analytics/{projectId}/feedback/by-page": {
|
|
"get": {
|
|
"summary": "Get feedback by page",
|
|
"description": "Returns feedback counts aggregated by documentation page path — thumbs up/down for contextual feedback, code snippet feedback count, and total per page.",
|
|
"tags": [
|
|
"Analytics"
|
|
],
|
|
"security": [
|
|
{
|
|
"bearerAuth": []
|
|
}
|
|
],
|
|
"x-codeSamples": [
|
|
{
|
|
"lang": "bash",
|
|
"label": "cURL",
|
|
"source": "curl \"https://api.mintlify.com/v1/analytics/my-project-id/feedback/by-page?dateFrom=2024-01-01&dateTo=2024-02-01\" \\\n -H \"Authorization: Bearer mint_xxxxx\""
|
|
}
|
|
],
|
|
"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",
|
|
"agent",
|
|
"thumbs_only"
|
|
],
|
|
"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",
|
|
"description": "Returns paginated AI assistant conversation history, including the user query, assistant response, sources cited, resolution status, and query category. Paginate using the `cursor` from each response while `hasMore` is `true`.",
|
|
"tags": [
|
|
"Analytics"
|
|
],
|
|
"security": [
|
|
{
|
|
"bearerAuth": []
|
|
}
|
|
],
|
|
"x-codeSamples": [
|
|
{
|
|
"lang": "bash",
|
|
"label": "cURL",
|
|
"source": "curl \"https://api.mintlify.com/v1/analytics/my-project-id/assistant?dateFrom=2024-01-01&dateTo=2024-02-01&limit=100\" \\\n -H \"Authorization: Bearer mint_xxxxx\""
|
|
}
|
|
],
|
|
"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": 1000,
|
|
"default": 100,
|
|
"description": "Max results per page"
|
|
},
|
|
"required": false,
|
|
"name": "limit",
|
|
"in": "query"
|
|
},
|
|
{
|
|
"schema": {
|
|
"type": "string",
|
|
"format": "ulid",
|
|
"description": "Pagination cursor (ULID format)"
|
|
},
|
|
"required": false,
|
|
"name": "cursor",
|
|
"in": "query"
|
|
}
|
|
],
|
|
"responses": {
|
|
"200": {
|
|
"description": "Conversation data with pagination",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/AssistantConversationsResponse"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"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/caller-stats": {
|
|
"get": {
|
|
"summary": "Get assistant caller stats",
|
|
"description": "Returns a breakdown of assistant query counts by caller type (web, API, and other) for the specified date range. Use this to understand whether queries come from your documentation site or from direct API integrations.",
|
|
"tags": [
|
|
"Analytics"
|
|
],
|
|
"security": [
|
|
{
|
|
"bearerAuth": []
|
|
}
|
|
],
|
|
"x-codeSamples": [
|
|
{
|
|
"lang": "bash",
|
|
"label": "cURL",
|
|
"source": "curl \"https://api.mintlify.com/v1/analytics/my-project-id/assistant/caller-stats?dateFrom=2024-01-01&dateTo=2024-02-01\" \\\n -H \"Authorization: Bearer mint_xxxxx\""
|
|
}
|
|
],
|
|
"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"
|
|
}
|
|
],
|
|
"responses": {
|
|
"200": {
|
|
"description": "Assistant query counts broken down by caller type",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/AssistantCallerStatsResponse"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"400": {
|
|
"description": "Invalid query parameters",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/AnalyticsErrorResponse"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"500": {
|
|
"description": "Server error",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/AnalyticsErrorResponse"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"/v1/analytics/{projectId}/searches": {
|
|
"get": {
|
|
"summary": "Get search queries",
|
|
"description": "Returns paginated documentation search terms ordered by hit count descending. Each row includes click-through rate, the most-clicked result path, and the last time the term was searched. `totalSearches` is the total search event count (sum of all hits, not distinct queries). Paginate using `nextCursor` while it is not null.",
|
|
"tags": [
|
|
"Analytics"
|
|
],
|
|
"security": [
|
|
{
|
|
"bearerAuth": []
|
|
}
|
|
],
|
|
"x-codeSamples": [
|
|
{
|
|
"lang": "bash",
|
|
"label": "cURL",
|
|
"source": "curl \"https://api.mintlify.com/v1/analytics/my-project-id/searches?dateFrom=2024-01-01&dateTo=2024-02-01&limit=50\" \\\n -H \"Authorization: Bearer mint_xxxxx\""
|
|
}
|
|
],
|
|
"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. Paginate using offset-based pagination: increment `offset` by `limit` while `hasMore` is `true`.",
|
|
"tags": [
|
|
"Analytics"
|
|
],
|
|
"security": [
|
|
{
|
|
"bearerAuth": []
|
|
}
|
|
],
|
|
"x-codeSamples": [
|
|
{
|
|
"lang": "bash",
|
|
"label": "cURL",
|
|
"source": "curl \"https://api.mintlify.com/v1/analytics/my-project-id/views?dateFrom=2024-01-01&dateTo=2024-02-01&limit=50&offset=0\" \\\n -H \"Authorization: Bearer mint_xxxxx\""
|
|
}
|
|
],
|
|
"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 split by human and AI traffic. The `total` field is deduplicated across human and AI (union of distinct visitor IDs). Paginate using offset-based pagination: increment `offset` by `limit` while `hasMore` is `true`.",
|
|
"tags": [
|
|
"Analytics"
|
|
],
|
|
"security": [
|
|
{
|
|
"bearerAuth": []
|
|
}
|
|
],
|
|
"x-codeSamples": [
|
|
{
|
|
"lang": "bash",
|
|
"label": "cURL",
|
|
"source": "curl \"https://api.mintlify.com/v1/analytics/my-project-id/visitors?dateFrom=2024-01-01&dateTo=2024-02-01&limit=50&offset=0\" \\\n -H \"Authorization: Bearer mint_xxxxx\""
|
|
}
|
|
],
|
|
"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": {}
|
|
} |