analytics.openapi.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"
    }
  ],
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "The Authorization header expects a Bearer token. Use an admin API key. 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 `thumbs_only`. A thumbs up or thumbs down vote on a page without a written comment. Includes whether the user found the page helpful.",
                  "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."
                    }
                  },
                  "required": [
                    "id",
                    "path",
                    "comment",
                    "createdAt",
                    "source",
                    "status",
                    "helpful"
                  ]
                },
                {
                  "description": "Returned when source is `agent`. 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 identifier for this turn. Each row in a multi-turn conversation has a different `id`."
                },
                "conversationId": {
                  "type": "string",
                  "description": "Identifier of the conversation this turn belongs to. Rows from the same conversation share the same `conversationId`. Use it as the `threadId` for the Get assistant conversation thread endpoint."
                },
                "timestamp": {
                  "type": "string",
                  "description": "Timestamp of the user message that started this turn."
                },
                "query": {
                  "type": "string",
                  "description": "The user's question to the assistant."
                },
                "response": {
                  "type": "string",
                  "description": "The assistant's response. For clarifying-question turns, this is the question the assistant asked the user."
                },
                "responseType": {
                  "type": "string",
                  "enum": [
                    "answer",
                    "clarifying_question"
                  ],
                  "description": "Type of response returned to the user. `answer` is a final answer. `clarifying_question` means the assistant asked the user a follow-up question instead of answering. Defaults to `answer` when not present."
                },
                "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 this turn. Computed per row: `unanswered` when the assistant marked the question as not covered by the available documentation. If the conversation is recorded as unanswered, for example because a response failed, and no turn was marked as not covered, every turn in the conversation is `unanswered`. Otherwise `answered`."
                },
                "queryCategory": {
                  "type": [
                    "string",
                    "null"
                  ],
                  "description": "Auto-assigned category grouping for the conversation, if applicable."
                },
                "feedback": {
                  "type": [
                    "string",
                    "null"
                  ],
                  "enum": [
                    "positive",
                    "negative",
                    null
                  ],
                  "description": "The user's thumbs rating on the assistant's response. `positive` for thumbs up, `negative` for thumbs down, or `null` if the user did not rate the response."
                },
                "pageUrl": {
                  "type": [
                    "string",
                    "null"
                  ],
                  "description": "Full URL of the documentation page where the conversation started. Null if no page path was captured."
                }
              },
              "required": [
                "id",
                "conversationId",
                "timestamp",
                "query",
                "response",
                "sources",
                "resolutionStatus",
                "queryCategory",
                "feedback",
                "pageUrl"
              ]
            }
          },
          "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": "Percentage of searches for this term that resulted in a click on a specific search result (clicks ÷ hits × 100). A click includes selecting a result with the pointer or pressing Enter when a result is highlighted. Submitting a query by itself does not count as a click. Clicking the AI assistant in the search bar, or pressing Enter to use it, counts as a search with no click and is not tracked separately in this field."
                },
                "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"]
      },
      "AssistantThreadResponse": {
        "type": "object",
        "properties": {
          "threadId": {
            "type": "string",
            "description": "Assistant conversation thread identifier (ULID)."
          },
          "createdAt": {
            "type": "string",
            "description": "Timestamp when the thread was created."
          },
          "messages": {
            "type": "array",
            "description": "Ordered list of messages exchanged in the thread.",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string",
                  "description": "Unique message identifier."
                },
                "role": {
                  "type": "string",
                  "enum": ["user", "assistant"],
                  "description": "Whether the message was sent by the user or the assistant."
                },
                "content": {
                  "type": "string",
                  "description": "The text content of the message."
                },
                "createdAt": {
                  "type": "string",
                  "description": "Timestamp when the message was sent."
                }
              },
              "required": ["id", "role", "content", "createdAt"]
            }
          }
        },
        "required": ["threadId", "createdAt", "messages"]
      },
      "AssistantCallerStatsResponse": {
        "type": "object",
        "properties": {
          "web": {
            "type": "number",
            "description": "Number of assistant conversations started from the web (documentation site)."
          },
          "api": {
            "type": "number",
            "description": "Number of assistant conversations started from API calls."
          },
          "other": {
            "type": "number",
            "description": "Number of assistant conversations started from other sources (e.g., integrations, SDKs)."
          },
          "total": {
            "type": "number",
            "description": "Total assistant conversations 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": "List feedback",
        "description": "Lists user feedback, with optional filtering and pagination.\n\nAuthenticate with an admin API key.",
        "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",
                "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": "A query parameter is invalid, such as a malformed date or a `limit` outside the allowed range, or the project ID is malformed. The response body describes the error.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AnalyticsErrorResponse"
                }
              }
            }
          },
          "401": {
            "description": "The API key is missing or invalid, or your plan doesn't include API access."
          },
          "403": {
            "description": "Your request came from an IP address that isn't on your API key's allowlist."
          },
          "404": {
            "description": "The project doesn't exist or doesn't belong to your organization."
          },
          "429": {
            "description": "You exceeded the rate limit for the analytics endpoints."
          },
          "500": {
            "description": "An unexpected server error occurred. Retry the request. If the error continues, contact support.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AnalyticsErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/v1/analytics/{projectId}/feedback/by-page": {
      "get": {
        "summary": "Get feedback by page",
        "description": "Retrieves feedback counts aggregated by documentation page path, including thumbs up and down votes for contextual feedback, code snippet feedback count, and total per page.\n\nAuthenticate with an admin API key.",
        "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",
                "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": "A query parameter is invalid, such as a malformed date or a `limit` outside the allowed range, or the project ID is malformed. The response body describes the error.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AnalyticsErrorResponse"
                }
              }
            }
          },
          "401": {
            "description": "The API key is missing or invalid, or your plan doesn't include API access."
          },
          "403": {
            "description": "Your request came from an IP address that isn't on your API key's allowlist."
          },
          "404": {
            "description": "The project doesn't exist or doesn't belong to your organization."
          },
          "429": {
            "description": "You exceeded the rate limit for the analytics endpoints."
          },
          "500": {
            "description": "An unexpected server error occurred. Retry the request. If the error continues, contact support.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AnalyticsErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/v1/analytics/{projectId}/assistant": {
      "get": {
        "summary": "List assistant conversations",
        "description": "Lists assistant conversation history, with pagination.\n\nAuthenticate with an admin API key.",
        "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": 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": "A query parameter is invalid, such as a malformed date or a `limit` outside the allowed range, or the project ID is malformed. The response body describes the error.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AnalyticsErrorResponse"
                }
              }
            }
          },
          "401": {
            "description": "The API key is missing or invalid, or your plan doesn't include API access."
          },
          "403": {
            "description": "Your request came from an IP address that isn't on your API key's allowlist."
          },
          "404": {
            "description": "The project doesn't exist or doesn't belong to your organization."
          },
          "429": {
            "description": "You exceeded the rate limit for the analytics endpoints."
          },
          "500": {
            "description": "An unexpected server error occurred. Retry the request. If the error continues, contact support.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AnalyticsErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/v1/analytics/{projectId}/assistant/threads/{threadId}": {
      "get": {
        "summary": "Get assistant conversation thread",
        "description": "Retrieves the full message transcript for a single assistant conversation thread. The thread ID is available from the assistant conversations endpoint, or as the `threadId` query parameter appended to assistant link-mode deflection support URLs.\n\nAuthenticate with an admin API key.",
        "tags": [
          "Analytics"
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/projectId"
          },
          {
            "schema": {
              "type": "string",
              "format": "ulid",
              "description": "Assistant conversation thread ID (ULID)."
            },
            "required": true,
            "name": "threadId",
            "in": "path"
          }
        ],
        "responses": {
          "200": {
            "description": "The conversation transcript",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AssistantThreadResponse"
                }
              }
            }
          },
          "400": {
            "description": "The thread ID isn't valid, or the project ID is malformed.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AnalyticsErrorResponse"
                }
              }
            }
          },
          "401": {
            "description": "The API key is missing or invalid, or your plan doesn't include API access."
          },
          "403": {
            "description": "Your request came from an IP address that isn't on your API key's allowlist."
          },
          "404": {
            "description": "The thread doesn't exist, or the project doesn't exist or doesn't belong to your organization.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AnalyticsErrorResponse"
                }
              }
            }
          },
          "429": {
            "description": "You exceeded the rate limit for the analytics endpoints."
          },
          "500": {
            "description": "An unexpected server error occurred. Retry the request. If the error continues, contact support.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AnalyticsErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/v1/analytics/{projectId}/assistant/caller-stats": {
      "get": {
        "summary": "Get assistant caller stats",
        "description": "Retrieves a breakdown of assistant conversation counts by caller type (web, API, and other) for conversations started in the specified date range.\n\nAuthenticate with an admin API key.",
        "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"
          }
        ],
        "responses": {
          "200": {
            "description": "Assistant conversation counts broken down by caller type",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AssistantCallerStatsResponse"
                }
              }
            }
          },
          "400": {
            "description": "A query parameter is invalid, such as a malformed date or a `limit` outside the allowed range, or the project ID is malformed. The response body describes the error.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AnalyticsErrorResponse"
                }
              }
            }
          },
          "401": {
            "description": "The API key is missing or invalid, or your plan doesn't include API access."
          },
          "403": {
            "description": "Your request came from an IP address that isn't on your API key's allowlist."
          },
          "404": {
            "description": "The project doesn't exist or doesn't belong to your organization."
          },
          "429": {
            "description": "You exceeded the rate limit for the analytics endpoints."
          },
          "500": {
            "description": "An unexpected server error occurred. Retry the request. If the error continues, contact support.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AnalyticsErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/v1/analytics/{projectId}/searches": {
      "get": {
        "summary": "List search queries",
        "description": "Lists documentation search terms for the date range, ordered by hit count descending, with pagination. 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).\n\nAuthenticate with an admin API key.",
        "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": "A query parameter or `cursor` is invalid, such as a malformed date or a `limit` outside the allowed range, or the project ID is malformed. The response body describes the error.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AnalyticsErrorResponse"
                }
              }
            }
          },
          "401": {
            "description": "The API key is missing or invalid, or your plan doesn't include API access."
          },
          "403": {
            "description": "Your request came from an IP address that isn't on your API key's allowlist."
          },
          "404": {
            "description": "The project doesn't exist or doesn't belong to your organization."
          },
          "429": {
            "description": "You exceeded the rate limit for the analytics endpoints."
          },
          "500": {
            "description": "An unexpected server error occurred. Retry the request. If the error continues, contact support.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AnalyticsErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/v1/analytics/{projectId}/views": {
      "get": {
        "summary": "Get page views",
        "description": "Retrieves per-path and site-wide content view event counts, split by human and AI traffic.\n\nAuthenticate with an admin API key.",
        "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": "A query parameter is invalid, such as a malformed date or a `limit` outside the allowed range, or the project ID is malformed. The response body describes the error.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AnalyticsErrorResponse"
                }
              }
            }
          },
          "401": {
            "description": "The API key is missing or invalid, or your plan doesn't include API access."
          },
          "403": {
            "description": "Your request came from an IP address that isn't on your API key's allowlist."
          },
          "404": {
            "description": "The project doesn't exist or doesn't belong to your organization."
          },
          "429": {
            "description": "You exceeded the rate limit for the analytics endpoints."
          },
          "500": {
            "description": "An unexpected server error occurred. Retry the request. If the error continues, contact support.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AnalyticsErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/v1/analytics/{projectId}/visitors": {
      "get": {
        "summary": "Get unique visitors",
        "description": "Retrieves 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).\n\nAuthenticate with an admin API key.",
        "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": "A query parameter is invalid, such as a malformed date or a `limit` outside the allowed range, or the project ID is malformed. The response body describes the error.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AnalyticsErrorResponse"
                }
              }
            }
          },
          "401": {
            "description": "The API key is missing or invalid, or your plan doesn't include API access."
          },
          "403": {
            "description": "Your request came from an IP address that isn't on your API key's allowlist."
          },
          "404": {
            "description": "The project doesn't exist or doesn't belong to your organization."
          },
          "429": {
            "description": "You exceeded the rate limit for the analytics endpoints."
          },
          "500": {
            "description": "An unexpected server error occurred. Retry the request. If the error continues, contact support.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AnalyticsErrorResponse"
                }
              }
            }
          }
        }
      }
    }
  },
  "webhooks": {}
}