mintlify__docs/zh/openapi.json

{
  "openapi": "3.0.1",
  "info": {
    "title": "Mintlify External API",
    "description": "用于管理 Mintlify 文档并访问各类资源的 API。",
    "version": "1.0.0"
  },
  "servers": [
    {
      "url": "https://api.mintlify.com/v1"
    }
  ],
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "x-mcp": {
    "enabled": true
  },
  "paths": {
    "/project/update/{projectId}": {
      "post": {
        "summary": "触发更新",
        "description": "为你的文档项目排队一次部署更新。返回一个状态 ID，用于跟踪更新进度。更新将从你配置的部署用分支触发。",
        "parameters": [
          {
            "name": "projectId",
            "in": "path",
            "description": "项目 ID。可在控制台的 [API keys](https://dashboard.mintlify.com/settings/organization/api-keys) 页面中复制。",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "202": {
            "description": "成功响应",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "statusId": {
                      "type": "string",
                      "description": "已触发的更新的状态 ID。"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/project/update-status/{statusId}": {
      "get": {
        "summary": "获取更新状态",
        "description": "通过状态 ID 获取更新状态",
        "parameters": [
          {
            "name": "statusId",
            "in": "path",
            "description": "已触发的更新的状态 ID。",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "成功响应",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "_id": {
                      "type": "string",
                      "description": "已触发更新项的状态 ID。"
                    },
                    "projectId": {
                      "type": "string",
                      "description": "文档项目的 ID。"
                    },
                    "createdAt": {
                      "type": "string",
                      "description": "具有指定 UTC 日期时间的 ISODate"
                    },
                    "endedAt": {
                      "type": "string",
                      "description": "包含指定 UTC 日期时间的 ISODate"
                    },
                    "status": {
                      "type": "string",
                      "enum": [
                        "queued",
                        "in_progress",
                        "success",
                        "failure"
                      ],
                      "description": "更新状态。"
                    },
                    "summary": {
                      "type": "string",
                      "description": "更新状态概览"
                    },
                    "logs": {
                      "type": "array",
                      "description": "一组日志。",
                      "items": {
                        "type": "string"
                      }
                    },
                    "subdomain": {
                      "type": "string",
                      "description": "正在更新的文档站点的子域。"
                    },
                    "screenshot": {
                      "type": "string",
                      "description": "文档截图。"
                    },
                    "screenshotLight": {
                      "type": "string",
                      "description": "文档截图。"
                    },
                    "screenshotDark": {
                      "type": "string",
                      "description": "文档在深色模式下的截图。"
                    },
                    "author": {
                      "type": "object",
                      "description": "此更新的作者。",
                      "nullable": true,
                      "properties": {
                        "name": {
                          "type": "string",
                          "description": "作者的名称。"
                        },
                        "avatarUrl": {
                          "type": "string",
                          "description": "作者头像的 URL。"
                        },
                        "githubUserId": {
                          "type": "number",
                          "description": "作者的 GitHub 用户 ID。"
                        }
                      }
                    },
                    "commit": {
                      "type": "object",
                      "description": "提交详情",
                      "properties": {
                        "sha": {
                          "type": "string",
                          "description": "提交的 SHA 哈希值。"
                        },
                        "ref": {
                          "type": "string",
                          "description": "该提交的 ref。"
                        },
                        "message": {
                          "type": "string",
                          "description": "提交信息。"
                        },
                        "filesChanged": {
                          "type": "object",
                          "description": "更改文件的详细信息。",
                          "properties": {
                            "added": {
                              "type": "array",
                              "description": "已添加新文件。",
                              "items": {
                                "type": "string"
                              }
                            },
                            "modified": {
                              "type": "array",
                              "description": "已被修改的现有文件。",
                              "items": {
                                "type": "string"
                              }
                            },
                            "removed": {
                              "type": "array",
                              "description": "已删除的文件。",
                              "items": {
                                "type": "string"
                              }
                            }
                          }
                        }
                      }
                    },
                    "source": {
                      "type": "string",
                      "description": "更新触发器的来源。",
                      "enum": [
                        "internal",
                        "github-app-installation",
                        "api",
                        "github",
                        "dashboard",
                        "gitlab",
                        "onboarding"
                      ]
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/project/preview/{projectId}": {
      "post": {
        "summary": "触发预览部署",
        "description": "为特定分支创建或更新预览部署。如果该分支已有预览，则会触发重新部署。返回用于跟踪进度的状态 ID 和预览 URL。",
        "parameters": [
          {
            "name": "projectId",
            "in": "path",
            "description": "项目 ID。可在控制台的 [API keys](https://dashboard.mintlify.com/settings/organization/api-keys) 页面中复制。",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["branch"],
                "properties": {
                  "branch": {
                    "type": "string",
                    "description": "要为其创建预览部署的 Git 分支名称。",
                    "minLength": 1
                  }
                }
              }
            }
          }
        },
        "responses": {
          "202": {
            "description": "预览部署已成功加入队列。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "statusId": {
                      "type": "string",
                      "description": "用于跟踪预览部署的状态 ID。可将其与 [Get deployment status](/zh/api/update/status) 端点配合使用。"
                    },
                    "previewUrl": {
                      "type": "string",
                      "description": "预览部署所托管的 URL。"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "无效请求。`branch` 字段为必填项。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "你当前的方案不支持预览部署。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "Authorization 请求头需要使用 Bearer token。请使用以 `mint_` 为前缀的管理员 API key。该 key 是仅供服务端使用的机密密钥。你可以在控制台的 [API keys 页面](https://dashboard.mintlify.com/settings/organization/api-keys) 中生成一个。"
      }
    }
  }
}