mirror of
https://github.com/mintlify/docs.git
synced 2026-09-14 13:35:46 +08:00
mintlify[bot]
880dd874eb
* Update API specs to match server implementation Generated-By: mintlify-agent * remove X-Message-Id and X-Pull-Request-Link --------- Co-authored-by: mintlify[bot] <109931778+mintlify[bot]@users.noreply.github.com> Co-authored-by: Ethan Palm <56270045+ethanpalm@users.noreply.github.com>
681 lines
26 KiB
JSON
681 lines
26 KiB
JSON
{
|
|
"openapi": "3.0.1",
|
|
"info": {
|
|
"title": "Mintlify Admin API",
|
|
"description": "Una API de operaciones administrativas, incluidas las actualizaciones de documentación y la gestión de agentes.",
|
|
"version": "2.0.0"
|
|
},
|
|
"servers": [
|
|
{
|
|
"url": "https://api.mintlify.com"
|
|
}
|
|
],
|
|
"security": [
|
|
{
|
|
"bearerAuth": []
|
|
}
|
|
],
|
|
"paths": {
|
|
"/v1/agent/{projectId}/job": {
|
|
"post": {
|
|
"summary": "Crear trabajo del agente (v1)",
|
|
"deprecated": true,
|
|
"description": "En desuso: usa [v2 create agent job](/api/agent/v2/create-agent-job) en su lugar. Crea un nuevo trabajo del agente que puede generar y editar documentación según los mensajes proporcionados y la información de la branch.",
|
|
"parameters": [
|
|
{
|
|
"name": "projectId",
|
|
"in": "path",
|
|
"required": true,
|
|
"schema": {
|
|
"type": "string"
|
|
},
|
|
"description": "El ID de tu proyecto. Se puede copiar desde la página de [API keys](https://dashboard.mintlify.com/settings/organization/api-keys) en tu dashboard."
|
|
}
|
|
],
|
|
"requestBody": {
|
|
"required": true,
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"type": "object",
|
|
"required": [
|
|
"messages"
|
|
],
|
|
"properties": {
|
|
"branch": {
|
|
"type": "string",
|
|
"description": "El nombre de la branch de Git en la que debe trabajar el agente. Si se omite, el agente genera un nombre de branch a partir del contenido del mensaje."
|
|
},
|
|
"messages": {
|
|
"type": "array",
|
|
"description": "Una lista de mensajes para proporcionar al agente. Siempre se antepone automáticamente un prompt del sistema predeterminado, por lo que normalmente solo necesitas incluir mensajes del usuario.",
|
|
"items": {
|
|
"type": "object",
|
|
"required": [
|
|
"role",
|
|
"content"
|
|
],
|
|
"properties": {
|
|
"role": {
|
|
"type": "string",
|
|
"enum": [
|
|
"system",
|
|
"user",
|
|
"assistant"
|
|
],
|
|
"description": "El rol del remitente del mensaje. Usa `user` para las instrucciones de la tarea. Usa `system` para agregar instrucciones complementarias que se añaden después del prompt del sistema predeterminado (no lo reemplaza). Usa `assistant` para proporcionar respuestas de ejemplo del assistant para el prompting de pocos ejemplos."
|
|
},
|
|
"content": {
|
|
"type": "string",
|
|
"description": "El contenido del mensaje."
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"asDraft": {
|
|
"type": "boolean",
|
|
"default": false,
|
|
"description": "Controla si la solicitud de extracción se crea en modo borrador o en modo normal. Cuando es true, crea una solicitud de extracción en borrador. Cuando es false (predeterminado), crea una solicitud de extracción regular lista para revisión."
|
|
},
|
|
"model": {
|
|
"type": "string",
|
|
"enum": [
|
|
"sonnet",
|
|
"opus"
|
|
],
|
|
"default": "sonnet",
|
|
"description": "El modelo de IA que se usará para el trabajo del agente. Usa `sonnet` para un procesamiento más rápido y rentable. Usa `opus` para un procesamiento más capaz, pero más lento."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"responses": {
|
|
"200": {
|
|
"description": "Tarea de agente creada correctamente. Devuelve una respuesta en streaming con Server-Sent Events.",
|
|
"headers": {
|
|
"X-Session-Id": {
|
|
"schema": {
|
|
"type": "string"
|
|
},
|
|
"description": "Identificador único de sesión para la tarea de agente creada."
|
|
},
|
|
"X-Branch-Name": {
|
|
"schema": {
|
|
"type": "string"
|
|
},
|
|
"description": "Nombre de la rama Git donde el agente realiza los cambios."
|
|
}
|
|
},
|
|
"content": {
|
|
"text/event-stream": {
|
|
"schema": {
|
|
"type": "string",
|
|
"description": "Flujo Server-Sent Events que contiene los detalles de ejecución y resultados de la tarea de agente."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"/v1/agent/{projectId}/job/{id}": {
|
|
"get": {
|
|
"summary": "Obtener trabajo del agente por ID (v1)",
|
|
"deprecated": true,
|
|
"description": "En desuso: usa [v2 get agent job](/api/agent/v2/get-agent-job) en su lugar. Recupera los detalles y el estado de un trabajo del agente específico a partir de su ID.",
|
|
"parameters": [
|
|
{
|
|
"name": "projectId",
|
|
"in": "path",
|
|
"required": true,
|
|
"schema": {
|
|
"type": "string"
|
|
},
|
|
"description": "El ID de tu proyecto. Puedes copiarlo desde la página de [API keys](https://dashboard.mintlify.com/settings/organization/api-keys) en tu dashboard."
|
|
},
|
|
{
|
|
"name": "id",
|
|
"in": "path",
|
|
"required": true,
|
|
"schema": {
|
|
"type": "string"
|
|
},
|
|
"description": "El identificador único del trabajo del agente que se va a recuperar."
|
|
}
|
|
],
|
|
"responses": {
|
|
"200": {
|
|
"description": "Detalles del trabajo del agente recuperados correctamente",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"type": "object",
|
|
"properties": {
|
|
"sessionId": {
|
|
"type": "string",
|
|
"description": "El subdomain al que pertenece esta sesión."
|
|
},
|
|
"subdomain": {
|
|
"type": "string",
|
|
"description": "El subdomain al que pertenece esta sesión."
|
|
},
|
|
"branch": {
|
|
"type": "string",
|
|
"description": "Nombre de la branch de Git en la que se realizaron los cambios.",
|
|
"nullable": true
|
|
},
|
|
"haulted": {
|
|
"type": "boolean",
|
|
"description": "Indica si se detuvo la ejecución de la sesión."
|
|
},
|
|
"haultReason": {
|
|
"type": "string",
|
|
"enum": [
|
|
"completed",
|
|
"github_missconfigured",
|
|
"error",
|
|
"processing",
|
|
"interrupted"
|
|
],
|
|
"description": "Motivo de la interrupción de la sesión. `processing` indica que la tarea está en curso. `interrupted` indica que la tarea fue interrumpida manualmente."
|
|
},
|
|
"pullRequestLink": {
|
|
"type": "string",
|
|
"description": "Enlace a la solicitud de extracción creada."
|
|
},
|
|
"messageToUser": {
|
|
"type": "string",
|
|
"description": "Mensaje para el usuario sobre el resultado de la sesión."
|
|
},
|
|
"todos": {
|
|
"type": "array",
|
|
"description": "Lista de tareas pendientes de la sesión.",
|
|
"items": {
|
|
"type": "object",
|
|
"properties": {
|
|
"content": {
|
|
"type": "string",
|
|
"description": "Breve descripción de la tarea."
|
|
},
|
|
"status": {
|
|
"type": "string",
|
|
"enum": [
|
|
"pending",
|
|
"in_progress",
|
|
"completed",
|
|
"cancelled"
|
|
],
|
|
"description": "Estado actual de la tarea."
|
|
},
|
|
"priority": {
|
|
"type": "string",
|
|
"enum": [
|
|
"high",
|
|
"medium",
|
|
"low"
|
|
],
|
|
"description": "Nivel de prioridad de la tarea."
|
|
},
|
|
"id": {
|
|
"type": "string",
|
|
"description": "Identificador único de la tarea pendiente."
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"userId": {
|
|
"type": "string",
|
|
"description": "El ID del usuario que creó esta sesión, si está disponible."
|
|
},
|
|
"title": {
|
|
"type": "string",
|
|
"description": "Título generado que resume el trabajo del agente."
|
|
},
|
|
"createdAt": {
|
|
"type": "string",
|
|
"format": "date-time",
|
|
"description": "Marca de tiempo de creación de la sesión."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"/v1/agent/{projectId}/jobs": {
|
|
"get": {
|
|
"summary": "Obtener todos los trabajos del agente (v1)",
|
|
"deprecated": true,
|
|
"description": "En desuso: usa [v2 get agent job](/api/agent/v2/get-agent-job) en su lugar. Recupera todas las tareas del agente para el domain especificado, incluido su estado y sus detalles.",
|
|
"parameters": [
|
|
{
|
|
"name": "projectId",
|
|
"in": "path",
|
|
"required": true,
|
|
"schema": {
|
|
"type": "string"
|
|
},
|
|
"description": "El ID de tu proyecto. Puedes copiarlo desde la página de [API keys](https://dashboard.mintlify.com/settings/organization/api-keys) en tu dashboard."
|
|
},
|
|
{
|
|
"name": "skip",
|
|
"in": "query",
|
|
"required": false,
|
|
"schema": {
|
|
"type": "integer",
|
|
"minimum": 0,
|
|
"default": 0
|
|
},
|
|
"description": "Número de resultados a omitir para la paginación."
|
|
},
|
|
{
|
|
"name": "take",
|
|
"in": "query",
|
|
"required": false,
|
|
"schema": {
|
|
"type": "integer",
|
|
"minimum": 1,
|
|
"maximum": 100,
|
|
"default": 12
|
|
},
|
|
"description": "Número de resultados a devolver. Máximo 100."
|
|
}
|
|
],
|
|
"responses": {
|
|
"200": {
|
|
"description": "Todos los trabajos del agente se recuperaron correctamente",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"type": "object",
|
|
"properties": {
|
|
"allSessions": {
|
|
"type": "array",
|
|
"description": "Matriz de todas las sesiones del agente para el domain.",
|
|
"items": {
|
|
"type": "object",
|
|
"properties": {
|
|
"sessionId": {
|
|
"type": "string",
|
|
"description": "El subdomain al que pertenece esta sesión."
|
|
},
|
|
"subdomain": {
|
|
"type": "string",
|
|
"description": "El subdomain al que pertenece esta sesión."
|
|
},
|
|
"branch": {
|
|
"type": "string",
|
|
"description": "Nombre de la branch de Git en la que se realizaron los cambios",
|
|
"nullable": true
|
|
},
|
|
"haulted": {
|
|
"type": "boolean",
|
|
"description": "Indica si se detuvo la ejecución de la sesión."
|
|
},
|
|
"haultReason": {
|
|
"type": "string",
|
|
"enum": [
|
|
"completed",
|
|
"github_missconfigured",
|
|
"error",
|
|
"processing",
|
|
"interrupted"
|
|
],
|
|
"description": "Motivo de la interrupción de la sesión. `processing` indica que la tarea está en curso. `interrupted` indica que la tarea fue interrumpida manualmente."
|
|
},
|
|
"pullRequestLink": {
|
|
"type": "string",
|
|
"description": "Enlace a la solicitud de extracción creada."
|
|
},
|
|
"messageToUser": {
|
|
"type": "string",
|
|
"description": "Mensaje para el usuario sobre el resultado de la sesión."
|
|
},
|
|
"todos": {
|
|
"type": "array",
|
|
"description": "Lista de tareas pendientes de la sesión.",
|
|
"items": {
|
|
"type": "object",
|
|
"properties": {
|
|
"content": {
|
|
"type": "string",
|
|
"description": "Breve descripción de la tarea."
|
|
},
|
|
"status": {
|
|
"type": "string",
|
|
"enum": [
|
|
"pending",
|
|
"in_progress",
|
|
"completed",
|
|
"cancelled"
|
|
],
|
|
"description": "Estado actual de la tarea."
|
|
},
|
|
"priority": {
|
|
"type": "string",
|
|
"enum": [
|
|
"high",
|
|
"medium",
|
|
"low"
|
|
],
|
|
"description": "Nivel de prioridad de la tarea."
|
|
},
|
|
"id": {
|
|
"type": "string",
|
|
"description": "Identificador único de la tarea pendiente."
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"userId": {
|
|
"type": "string",
|
|
"description": "El ID del usuario que creó esta sesión, si está disponible."
|
|
},
|
|
"title": {
|
|
"type": "string",
|
|
"description": "Título generado que resume el trabajo del agente."
|
|
},
|
|
"createdAt": {
|
|
"type": "string",
|
|
"format": "date-time",
|
|
"description": "marca de tiempo de creación de la sesión."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"/v2/agent/{projectId}/job": {
|
|
"post": {
|
|
"summary": "Crear trabajo del agente",
|
|
"description": "Crea un nuevo trabajo del agente que se ejecuta en segundo plano. El trabajo procesa el prompt de forma asíncrona; consulta periódicamente el endpoint get job para seguir el progreso. Si el agente edita archivos correctamente, se crea automáticamente una solicitud de extracción.",
|
|
"parameters": [
|
|
{
|
|
"name": "projectId",
|
|
"in": "path",
|
|
"required": true,
|
|
"schema": {
|
|
"type": "string"
|
|
},
|
|
"description": "El ID de tu proyecto. Puedes copiarlo desde la página de [API keys](https://dashboard.mintlify.com/settings/organization/api-keys) en tu dashboard."
|
|
}
|
|
],
|
|
"requestBody": {
|
|
"required": true,
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"type": "object",
|
|
"required": [
|
|
"prompt"
|
|
],
|
|
"properties": {
|
|
"prompt": {
|
|
"type": "string",
|
|
"minLength": 1,
|
|
"description": "La instrucción que debe ejecutar el agente."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"responses": {
|
|
"201": {
|
|
"description": "Trabajo del agente creado correctamente",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/AgentJob"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"400": {
|
|
"description": "Solicitud no válida",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/Error"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"429": {
|
|
"description": "superar el límite de solicitudes",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/Error"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"/v2/agent/{projectId}/job/{id}": {
|
|
"get": {
|
|
"summary": "Obtener trabajo del agente",
|
|
"description": "Recupera el estado actual y los detalles de un trabajo del agente. Consulta este endpoint para seguir el progreso del trabajo.",
|
|
"parameters": [
|
|
{
|
|
"name": "projectId",
|
|
"in": "path",
|
|
"required": true,
|
|
"schema": {
|
|
"type": "string"
|
|
},
|
|
"description": "El ID de tu proyecto. Puedes copiarlo desde la página de [API keys](https://dashboard.mintlify.com/settings/organization/api-keys) en tu dashboard."
|
|
},
|
|
{
|
|
"name": "id",
|
|
"in": "path",
|
|
"required": true,
|
|
"schema": {
|
|
"type": "string"
|
|
},
|
|
"description": "El identificador único del trabajo del agente."
|
|
}
|
|
],
|
|
"responses": {
|
|
"200": {
|
|
"description": "Detalles del trabajo del agente",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/AgentJob"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"404": {
|
|
"description": "Trabajo no encontrado",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/Error"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"/v2/agent/{projectId}/job/{id}/message": {
|
|
"post": {
|
|
"summary": "Enviar mensaje de seguimiento",
|
|
"description": "Envía un mensaje de seguimiento a un trabajo del agente existente. El mensaje se procesa de forma asíncrona: consulta periódicamente el endpoint get job para seguir el progreso.",
|
|
"parameters": [
|
|
{
|
|
"name": "projectId",
|
|
"in": "path",
|
|
"required": true,
|
|
"schema": {
|
|
"type": "string"
|
|
},
|
|
"description": "El ID de tu proyecto. Puedes copiarlo desde la página de [API keys](https://dashboard.mintlify.com/settings/organization/api-keys) de tu dashboard."
|
|
},
|
|
{
|
|
"name": "id",
|
|
"in": "path",
|
|
"required": true,
|
|
"schema": {
|
|
"type": "string"
|
|
},
|
|
"description": "El identificador único del trabajo del agente al que se enviará un mensaje."
|
|
}
|
|
],
|
|
"requestBody": {
|
|
"required": true,
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"type": "object",
|
|
"required": [
|
|
"prompt"
|
|
],
|
|
"properties": {
|
|
"prompt": {
|
|
"type": "string",
|
|
"minLength": 1,
|
|
"description": "La instrucción de seguimiento para el agente."
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"responses": {
|
|
"200": {
|
|
"description": "Mensaje enviado correctamente",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/AgentJob"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"400": {
|
|
"description": "Solicitud no válida",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/Error"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"404": {
|
|
"description": "Trabajo no encontrado",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/Error"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"429": {
|
|
"description": "Se superó el límite de solicitudes",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/Error"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"components": {
|
|
"schemas": {
|
|
"AgentJob": {
|
|
"type": "object",
|
|
"properties": {
|
|
"id": {
|
|
"type": "string",
|
|
"description": "Identificador único del trabajo del agente."
|
|
},
|
|
"status": {
|
|
"type": "string",
|
|
"enum": [
|
|
"active",
|
|
"completed",
|
|
"archived",
|
|
"failed"
|
|
],
|
|
"description": "Estado actual del trabajo. `active` — el agente está procesando la instrucción en este momento. `completed` — el agente finalizó correctamente y es posible que se haya creado una PR (verificar `prLink`). `archived` — el trabajo se ha archivado. `failed` — el agente encontró un error irrecuperable. Consulte periódicamente hasta que el estado sea `completed`, `archived` o `failed`."
|
|
},
|
|
"source": {
|
|
"type": "object",
|
|
"description": "Información del repositorio de origen.",
|
|
"properties": {
|
|
"repository": {
|
|
"type": "string",
|
|
"description": "URL completa del repositorio de GitHub."
|
|
},
|
|
"ref": {
|
|
"type": "string",
|
|
"description": "branch de Git en la que trabaja el agente.",
|
|
"nullable": true
|
|
}
|
|
}
|
|
},
|
|
"model": {
|
|
"type": "string",
|
|
"description": "El modelo de IA utilizado para esta tarea."
|
|
},
|
|
"prLink": {
|
|
"type": "string",
|
|
"format": "uri",
|
|
"example": "https://github.com/org/repo/pull/123",
|
|
"description": "URL de la solicitud de extracción de GitHub creada por el agente. `null` mientras la tarea siga `active` o si no se ha cambiado ningún archivo. Se completa cuando el agente crea correctamente una PR.",
|
|
"nullable": true
|
|
},
|
|
"createdAt": {
|
|
"type": "string",
|
|
"format": "date-time",
|
|
"description": "Marca de tiempo de creación de la tarea."
|
|
},
|
|
"archivedAt": {
|
|
"type": "string",
|
|
"format": "date-time",
|
|
"description": "Marca de tiempo de archivado de la tarea.",
|
|
"nullable": true
|
|
}
|
|
}
|
|
},
|
|
"Error": {
|
|
"type": "object",
|
|
"properties": {
|
|
"error": {
|
|
"type": "string",
|
|
"description": "Mensaje de error."
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"securitySchemes": {
|
|
"bearerAuth": {
|
|
"type": "http",
|
|
"scheme": "bearer",
|
|
"description": "El encabezado Authorization requiere un token de tipo Bearer. Usa una clave de API de administrador (con el prefijo `mint_`). Esta es una clave secreta del lado del servidor. Genera una clave en la [página de claves de API](https://dashboard.mintlify.com/settings/organization/api-keys) de tu dashboard."
|
|
}
|
|
}
|
|
}
|
|
}
|