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 `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."
                },
                "pageUrl": {
                  "type": [
                    "string",
                    "null"
                  ],
                  "description": "Full URL of the documentation page where the conversation started. Null if no page path was captured."
                }
              },
              "required": [
                "id",
                "timestamp",
                "query",
                "response",
                "sources",
                "resolutionStatus",
                "queryCategory",
                "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": "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\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": "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 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": "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\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": "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.\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 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 for the date range, ordered by hit count descending. Each row includes click-through rate, the most-clicked result path for that query (if any), and the last time the term was searched. `totalSearches` is the total number of search query events in the same date range (sum of all hits, not distinct queries).\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": "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.\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": "Invalid query parameters",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AnalyticsErrorResponse"
                }
              }
            }
          },
          "500": {
            "description": "Server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AnalyticsErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/v1/analytics/{projectId}/visitors": {
      "get": {
        "summary": "Get unique visitors",
        "description": "Returns per-path and site-wide approximate distinct visitors by traffic type. The `total` field is deduplicated across human and AI (union of distinct visitor IDs with any qualifying content view).\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": "Invalid query parameters",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AnalyticsErrorResponse"
                }
              }
            }
          },
          "500": {
            "description": "Server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AnalyticsErrorResponse"
                }
              }
            }
          }
        }
      }
    }
  },
  "webhooks": {}
}