mirror of
https://github.com/mintlify/docs.git
synced 2026-09-14 13:35:46 +08:00
mintlify[bot]
4b73a9127d
Co-authored-by: mintlify[bot] <109931778+mintlify[bot]@users.noreply.github.com>
699 lines
23 KiB
JSON
699 lines
23 KiB
JSON
{
|
|
"openapi": "3.1.0",
|
|
"info": {
|
|
"title": "Mintlify Analytics Export API",
|
|
"version": "1.0.0",
|
|
"description": "API para exportar datos de Analytics de la documentación"
|
|
},
|
|
"servers": [
|
|
{
|
|
"url": "https://api.mintlify.com",
|
|
"description": "Producción"
|
|
}
|
|
],
|
|
"components": {
|
|
"securitySchemes": {
|
|
"bearerAuth": {
|
|
"type": "http",
|
|
"scheme": "bearer",
|
|
"description": "El encabezado Authorization requiere un token de tipo Bearer. Usa una clave de API de administrador. Esta es una clave secreta del lado del servidor. Genera una en la [página de claves de API](https://dashboard.mintlify.com/settings/organization/api-keys) de tu dashboard."
|
|
}
|
|
},
|
|
"schemas": {
|
|
"projectId": {
|
|
"type": "string",
|
|
"description": "Tu ID de proyecto. Puedes copiarlo desde la página [API keys](https://dashboard.mintlify.com/settings/organization/api-keys) en tu dashboard."
|
|
},
|
|
"FeedbackResponse": {
|
|
"type": "object",
|
|
"properties": {
|
|
"feedback": {
|
|
"type": "array",
|
|
"description": "Lista de entradas de comentarios.",
|
|
"items": {
|
|
"anyOf": [
|
|
{
|
|
"type": "object",
|
|
"properties": {
|
|
"id": {
|
|
"type": "string",
|
|
"description": "Identificador único del comentario."
|
|
},
|
|
"path": {
|
|
"type": "string",
|
|
"description": "La ruta o URL del documento de origen."
|
|
},
|
|
"comment": {
|
|
"type": [
|
|
"string",
|
|
"null"
|
|
],
|
|
"description": "Texto del comentario del usuario."
|
|
},
|
|
"createdAt": {
|
|
"type": [
|
|
"string",
|
|
"null"
|
|
],
|
|
"description": "Fecha y hora en la que se envió el comentario."
|
|
},
|
|
"source": {
|
|
"type": "string",
|
|
"enum": [
|
|
"code_snippet",
|
|
"contextual",
|
|
"agent",
|
|
"thumbs_only"
|
|
],
|
|
"description": "Origen del comentario. `code_snippet` indica un comentario sobre un bloque de código, `contextual` indica un comentario a nivel de página, `agent` indica un comentario enviado por un agente de IA de terceros, `thumbs_only` es un voto de pulgar arriba/abajo."
|
|
},
|
|
"status": {
|
|
"type": "string",
|
|
"enum": [
|
|
"pending",
|
|
"in_progress",
|
|
"resolved",
|
|
"dismissed"
|
|
],
|
|
"description": "Estado de revisión actual del comentario."
|
|
},
|
|
"helpful": {
|
|
"type": "boolean",
|
|
"description": "Indica si el usuario considera útil el contenido."
|
|
},
|
|
"contact": {
|
|
"type": [
|
|
"string",
|
|
"null"
|
|
],
|
|
"description": "Dirección de correo electrónico proporcionada por el usuario para el seguimiento."
|
|
}
|
|
},
|
|
"required": [
|
|
"id",
|
|
"path",
|
|
"comment",
|
|
"createdAt",
|
|
"source",
|
|
"status",
|
|
"helpful",
|
|
"contact"
|
|
],
|
|
"description": "Se devuelve cuando el origen es `contextual`. Incluye si el usuario encontró útil la página y un correo electrónico de contacto opcional."
|
|
},
|
|
{
|
|
"type": "object",
|
|
"properties": {
|
|
"id": {
|
|
"type": "string",
|
|
"description": "Identificador único del comentario."
|
|
},
|
|
"path": {
|
|
"type": "string",
|
|
"description": "La ruta o URL del documento de origen."
|
|
},
|
|
"comment": {
|
|
"type": [
|
|
"string",
|
|
"null"
|
|
],
|
|
"description": "Texto del comentario del usuario."
|
|
},
|
|
"createdAt": {
|
|
"type": [
|
|
"string",
|
|
"null"
|
|
],
|
|
"description": "Fecha y hora en la que se envió el comentario."
|
|
},
|
|
"source": {
|
|
"type": "string",
|
|
"enum": [
|
|
"code_snippet",
|
|
"contextual",
|
|
"agent",
|
|
"thumbs_only"
|
|
],
|
|
"description": "Origen del comentario. `code_snippet` indica un comentario sobre un bloque de código, `contextual` indica un comentario a nivel de página, `agent` indica un comentario enviado por un agente de IA de terceros, `thumbs_only` es un voto de pulgar arriba/abajo."
|
|
},
|
|
"status": {
|
|
"type": "string",
|
|
"enum": [
|
|
"pending",
|
|
"in_progress",
|
|
"resolved",
|
|
"dismissed"
|
|
],
|
|
"description": "Estado actual de revisión del comentario."
|
|
},
|
|
"code": {
|
|
"type": "string",
|
|
"description": "Fragmento de código al que hace referencia el comentario."
|
|
},
|
|
"filename": {
|
|
"type": [
|
|
"string",
|
|
"null"
|
|
],
|
|
"description": "Nombre de archivo asociado al fragmento de código."
|
|
},
|
|
"lang": {
|
|
"type": [
|
|
"string",
|
|
"null"
|
|
],
|
|
"description": "Lenguaje de programación del fragmento de código."
|
|
}
|
|
},
|
|
"required": [
|
|
"id",
|
|
"path",
|
|
"comment",
|
|
"createdAt",
|
|
"source",
|
|
"status",
|
|
"code",
|
|
"filename",
|
|
"lang"
|
|
],
|
|
"description": "Se devuelve cuando el origen es `code_snippet`. Incluye el código, nombre de archivo y lenguaje del fragmento al que se refiere el comentario."
|
|
},
|
|
{
|
|
"type": "object",
|
|
"properties": {
|
|
"id": {
|
|
"type": "string",
|
|
"description": "Identificador único del comentario."
|
|
},
|
|
"path": {
|
|
"type": "string",
|
|
"description": "La ruta o URL del documento de origen."
|
|
},
|
|
"comment": {
|
|
"type": [
|
|
"string",
|
|
"null"
|
|
],
|
|
"description": "Texto del comentario del usuario."
|
|
},
|
|
"createdAt": {
|
|
"type": [
|
|
"string",
|
|
"null"
|
|
],
|
|
"description": "Marca de tiempo del envío del comentario."
|
|
},
|
|
"source": {
|
|
"type": "string",
|
|
"enum": [
|
|
"code_snippet",
|
|
"contextual",
|
|
"agent",
|
|
"thumbs_only"
|
|
],
|
|
"description": "Origen del comentario. `code_snippet` indica un comentario sobre un bloque de código, `contextual` indica un comentario a nivel de página, `agent` indica un comentario enviado por un agente de IA de terceros, `thumbs_only` es un voto de pulgar arriba/abajo."
|
|
},
|
|
"status": {
|
|
"type": "string",
|
|
"enum": [
|
|
"pending",
|
|
"in_progress",
|
|
"resolved",
|
|
"dismissed"
|
|
],
|
|
"description": "Estado actual de revisión del comentario."
|
|
}
|
|
},
|
|
"required": [
|
|
"id",
|
|
"path",
|
|
"comment",
|
|
"createdAt",
|
|
"source",
|
|
"status"
|
|
],
|
|
"description": "Se devuelve cuando el origen es `agent` o `thumbs_only`. Solo contiene los campos base de comentarios."
|
|
}
|
|
]
|
|
}
|
|
},
|
|
"nextCursor": {
|
|
"type": [
|
|
"string",
|
|
"null"
|
|
],
|
|
"description": "Cursor para recuperar la página siguiente de resultados. Nulo si no hay más resultados."
|
|
},
|
|
"hasMore": {
|
|
"type": "boolean",
|
|
"description": "Indica si hay más resultados después de esta página."
|
|
}
|
|
},
|
|
"required": [
|
|
"feedback",
|
|
"nextCursor",
|
|
"hasMore"
|
|
]
|
|
},
|
|
"AnalyticsErrorResponse": {
|
|
"type": "object",
|
|
"properties": {
|
|
"error": {
|
|
"type": "string",
|
|
"description": "Mensaje de error que describe lo que salió mal."
|
|
},
|
|
"details": {
|
|
"type": "array",
|
|
"description": "Detalles adicionales del error.",
|
|
"items": {
|
|
"type": "object",
|
|
"properties": {
|
|
"message": {
|
|
"type": "string",
|
|
"description": "Descripción de un error específico de validación o procesamiento."
|
|
}
|
|
},
|
|
"required": [
|
|
"message"
|
|
]
|
|
}
|
|
}
|
|
},
|
|
"required": [
|
|
"error"
|
|
]
|
|
},
|
|
"AssistantCallerStatsResponse": {
|
|
"type": "object",
|
|
"properties": {
|
|
"web": {
|
|
"type": "number",
|
|
"description": "Número de consultas del assistant originadas desde la web (sitio de documentación)."
|
|
},
|
|
"api": {
|
|
"type": "number",
|
|
"description": "Número de consultas del assistant originadas desde llamadas a la API."
|
|
},
|
|
"other": {
|
|
"type": "number",
|
|
"description": "Número de consultas del assistant desde otras fuentes (por ejemplo, integraciones, SDKs)."
|
|
},
|
|
"total": {
|
|
"type": "number",
|
|
"description": "Total de consultas del assistant en todos los tipos de origen."
|
|
}
|
|
},
|
|
"required": [
|
|
"web",
|
|
"api",
|
|
"other",
|
|
"total"
|
|
]
|
|
},
|
|
"AssistantConversationsResponse": {
|
|
"type": "object",
|
|
"properties": {
|
|
"conversations": {
|
|
"type": "array",
|
|
"description": "Lista de conversaciones del assistant.",
|
|
"items": {
|
|
"type": "object",
|
|
"properties": {
|
|
"id": {
|
|
"type": "string",
|
|
"description": "Identificador único de la conversación."
|
|
},
|
|
"timestamp": {
|
|
"type": "string",
|
|
"description": "Marca de tiempo en la que se produjo la conversación."
|
|
},
|
|
"query": {
|
|
"type": "string",
|
|
"description": "La pregunta del usuario para el assistant."
|
|
},
|
|
"response": {
|
|
"type": "string",
|
|
"description": "La respuesta del assistant."
|
|
},
|
|
"sources": {
|
|
"type": "array",
|
|
"description": "Páginas de la documentación mencionadas en la respuesta.",
|
|
"items": {
|
|
"type": "object",
|
|
"properties": {
|
|
"title": {
|
|
"type": "string",
|
|
"description": "Título de la página de documentación mencionada."
|
|
},
|
|
"url": {
|
|
"type": "string",
|
|
"description": "URL de la página de documentación mencionada."
|
|
}
|
|
},
|
|
"required": [
|
|
"title",
|
|
"url"
|
|
]
|
|
}
|
|
},
|
|
"queryCategory": {
|
|
"type": [
|
|
"string",
|
|
"null"
|
|
],
|
|
"description": "Categoría de agrupación asignada automáticamente a la conversación, si corresponde."
|
|
},
|
|
"pageUrl": {
|
|
"type": [
|
|
"string",
|
|
"null"
|
|
],
|
|
"description": "URL completa de la página de documentación donde se inició la conversación. Es null si no se capturó ninguna ruta de página."
|
|
}
|
|
},
|
|
"required": [
|
|
"id",
|
|
"timestamp",
|
|
"query",
|
|
"response",
|
|
"sources",
|
|
"queryCategory",
|
|
"pageUrl"
|
|
]
|
|
}
|
|
},
|
|
"nextCursor": {
|
|
"type": [
|
|
"string",
|
|
"null"
|
|
],
|
|
"description": "Cursor para obtener la siguiente página de resultados. Es nulo si no hay más resultados."
|
|
},
|
|
"hasMore": {
|
|
"type": "boolean",
|
|
"description": "Indica si hay resultados adicionales más allá de esta página."
|
|
}
|
|
},
|
|
"required": [
|
|
"conversations",
|
|
"nextCursor",
|
|
"hasMore"
|
|
]
|
|
}
|
|
},
|
|
"parameters": {
|
|
"projectId": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/projectId"
|
|
},
|
|
"required": true,
|
|
"name": "projectId",
|
|
"in": "path"
|
|
}
|
|
}
|
|
},
|
|
"paths": {
|
|
"/v1/analytics/{projectId}/feedback": {
|
|
"get": {
|
|
"summary": "Obtener comentarios de los usuarios",
|
|
"description": "Devuelve comentarios de usuarios con paginación y filtrado opcional\n\nAutentícate con una clave de API de administrador.",
|
|
"tags": [
|
|
"Analytics"
|
|
],
|
|
"security": [
|
|
{
|
|
"bearerAuth": []
|
|
}
|
|
],
|
|
"parameters": [
|
|
{
|
|
"$ref": "#/components/parameters/projectId"
|
|
},
|
|
{
|
|
"schema": {
|
|
"type": "string",
|
|
"description": "Fecha en formato ISO 8601 o AAAA-MM-DD",
|
|
"example": "2024-01-01"
|
|
},
|
|
"required": false,
|
|
"name": "dateFrom",
|
|
"in": "query"
|
|
},
|
|
{
|
|
"schema": {
|
|
"type": "string",
|
|
"description": "Fecha en formato ISO 8601 o AAAA-MM-DD. `dateTo` es un límite superior exclusivo. Los resultados incluyen fechas anteriores, pero no la fecha especificada.",
|
|
"example": "2024-01-01"
|
|
},
|
|
"required": false,
|
|
"name": "dateTo",
|
|
"in": "query"
|
|
},
|
|
{
|
|
"schema": {
|
|
"type": "string",
|
|
"enum": [
|
|
"code_snippet",
|
|
"contextual",
|
|
"agent",
|
|
"thumbs_only"
|
|
],
|
|
"description": "Filtrar por el origen de los comentarios"
|
|
},
|
|
"required": false,
|
|
"name": "source",
|
|
"in": "query"
|
|
},
|
|
{
|
|
"schema": {
|
|
"type": "string",
|
|
"description": "Lista de estados separados por comas por los que filtrar"
|
|
},
|
|
"required": false,
|
|
"name": "status",
|
|
"in": "query"
|
|
},
|
|
{
|
|
"schema": {
|
|
"type": "number",
|
|
"minimum": 1,
|
|
"maximum": 100,
|
|
"default": 50,
|
|
"description": "Número máximo de resultados por página"
|
|
},
|
|
"required": false,
|
|
"name": "limit",
|
|
"in": "query"
|
|
},
|
|
{
|
|
"schema": {
|
|
"type": "string",
|
|
"description": "Cursor de paginación"
|
|
},
|
|
"required": false,
|
|
"name": "cursor",
|
|
"in": "query"
|
|
}
|
|
],
|
|
"responses": {
|
|
"200": {
|
|
"description": "Datos de comentarios paginados",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/FeedbackResponse"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"400": {
|
|
"description": "Parámetros de búsqueda no válidos",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/AnalyticsErrorResponse"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"500": {
|
|
"description": "Error del servidor",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/AnalyticsErrorResponse"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"/v1/analytics/{projectId}/assistant/caller-stats": {
|
|
"get": {
|
|
"summary": "Obtener estadísticas de llamadas del assistant",
|
|
"description": "Devuelve un desglose del número de consultas del assistant por tipo de origen (web, API y otros) para el rango de fechas especificado.\n\nAutentícate con una clave de API de administrador.",
|
|
"tags": [
|
|
"Analytics"
|
|
],
|
|
"security": [
|
|
{
|
|
"bearerAuth": []
|
|
}
|
|
],
|
|
"parameters": [
|
|
{
|
|
"$ref": "#/components/parameters/projectId"
|
|
},
|
|
{
|
|
"schema": {
|
|
"type": "string",
|
|
"description": "Fecha en formato ISO 8601 o AAAA-MM-DD",
|
|
"example": "2024-01-01"
|
|
},
|
|
"required": false,
|
|
"name": "dateFrom",
|
|
"in": "query"
|
|
},
|
|
{
|
|
"schema": {
|
|
"type": "string",
|
|
"description": "Fecha en formato ISO 8601 o AAAA-MM-DD. `dateTo` es un límite superior exclusivo. Los resultados incluyen fechas anteriores, pero no la fecha especificada.",
|
|
"example": "2024-01-01"
|
|
},
|
|
"required": false,
|
|
"name": "dateTo",
|
|
"in": "query"
|
|
}
|
|
],
|
|
"responses": {
|
|
"200": {
|
|
"description": "Número de consultas del assistant desglosado por tipo de origen",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/AssistantCallerStatsResponse"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"400": {
|
|
"description": "Parámetros de búsqueda no válidos",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/AnalyticsErrorResponse"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"500": {
|
|
"description": "Error del servidor",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/AnalyticsErrorResponse"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"/v1/analytics/{projectId}/assistant": {
|
|
"get": {
|
|
"summary": "Obtener conversaciones del assistant",
|
|
"description": "Devuelve el historial paginado de conversaciones del Asistente de IA\n\nAutentícate con una clave de API de administrador.",
|
|
"tags": [
|
|
"Analytics"
|
|
],
|
|
"security": [
|
|
{
|
|
"bearerAuth": []
|
|
}
|
|
],
|
|
"parameters": [
|
|
{
|
|
"$ref": "#/components/parameters/projectId"
|
|
},
|
|
{
|
|
"schema": {
|
|
"type": "string",
|
|
"description": "Fecha en formato ISO 8601 o AAAA-MM-DD",
|
|
"example": "2024-01-01"
|
|
},
|
|
"required": false,
|
|
"name": "dateFrom",
|
|
"in": "query"
|
|
},
|
|
{
|
|
"schema": {
|
|
"type": "string",
|
|
"description": "Fecha en formato ISO 8601 o AAAA-MM-DD. `dateTo` es un límite superior exclusivo. Los resultados incluyen fechas anteriores, pero no la fecha especificada.",
|
|
"example": "2024-01-01"
|
|
},
|
|
"required": false,
|
|
"name": "dateTo",
|
|
"in": "query"
|
|
},
|
|
{
|
|
"schema": {
|
|
"type": "number",
|
|
"minimum": 1,
|
|
"maximum": 1000,
|
|
"default": 100,
|
|
"description": "Número máximo de resultados por página"
|
|
},
|
|
"required": false,
|
|
"name": "limit",
|
|
"in": "query"
|
|
},
|
|
{
|
|
"schema": {
|
|
"type": "string",
|
|
"format": "ulid",
|
|
"description": "Cursor de paginación (formato ULID)"
|
|
},
|
|
"required": false,
|
|
"name": "cursor",
|
|
"in": "query"
|
|
}
|
|
],
|
|
"responses": {
|
|
"200": {
|
|
"description": "Datos de conversación paginados",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/AssistantConversationsResponse"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"400": {
|
|
"description": "Parámetros de búsqueda no válidos",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/AnalyticsErrorResponse"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"500": {
|
|
"description": "Error del servidor",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/AnalyticsErrorResponse"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"webhooks": {}
|
|
}
|