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>
400 lines
14 KiB
JSON
400 lines
14 KiB
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，用于跟踪更新进度。更新将从你配置的部署用分支触发。\n\n使用管理员 API 密钥进行身份验证。",
|
||
"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 获取更新状态\n\n使用管理员 API 密钥进行身份验证。",
|
||
"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。\n\n使用管理员 API 密钥进行身份验证。",
|
||
"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"
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"/workflow/{projectId}/{workflowSchemaId}/trigger": {
|
||
"post": {
|
||
"summary": "触发自动化",
|
||
"description": "立即触发计划自动化运行，而无需等待其下一次预定时间。适合从 CI/CD 流水线中运行自动化，例如在每次合并到默认分支时运行的 GitHub Action。仅支持触发计划（自定义计划）自动化。该次运行会处理自上次完成运行以来的变更，与常规计划运行完全相同。\n\n使用管理员 API 密钥进行身份验证。",
|
||
"parameters": [
|
||
{
|
||
"name": "projectId",
|
||
"in": "path",
|
||
"description": "你的项目 ID。可在控制台的 [API keys](https://app.mintlify.com/settings/organization/api-keys) 页面中复制。",
|
||
"required": true,
|
||
"schema": {
|
||
"type": "string"
|
||
}
|
||
},
|
||
{
|
||
"name": "workflowSchemaId",
|
||
"in": "path",
|
||
"description": "要触发的自动化的 ID。可在控制台的 [Automations](https://app.mintlify.com/products/automations) 页面，从自动化的设置面板中复制。",
|
||
"required": true,
|
||
"schema": {
|
||
"type": "string"
|
||
}
|
||
}
|
||
],
|
||
"responses": {
|
||
"202": {
|
||
"description": "自动化运行已成功加入队列。",
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"type": "object",
|
||
"properties": {
|
||
"schemaId": {
|
||
"type": "string",
|
||
"description": "被触发的自动化的 ID。"
|
||
},
|
||
"instanceId": {
|
||
"type": "string",
|
||
"description": "已入队自动化运行的 ID。会出现在 [Automation Runs](https://app.mintlify.com/products/automations) 页面的运行历史中。"
|
||
},
|
||
"jobId": {
|
||
"type": "string",
|
||
"description": "处理此次运行的后台任务 ID。"
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"400": {
|
||
"description": "无效请求。自动化 ID 格式错误、自动化未激活，或该自动化未配置为使用自定义计划。",
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"type": "object",
|
||
"properties": {
|
||
"error": {
|
||
"type": "string"
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"404": {
|
||
"description": "未找到该自动化，或该自动化不属于此项目。",
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"type": "object",
|
||
"properties": {
|
||
"error": {
|
||
"type": "string"
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"components": {
|
||
"securitySchemes": {
|
||
"bearerAuth": {
|
||
"type": "http",
|
||
"scheme": "bearer",
|
||
"description": "Authorization 请求头需要使用 Bearer 令牌。请使用管理员 API 密钥。这是仅供服务端使用的机密密钥。你可以在控制台的 [API 密钥页面](https://dashboard.mintlify.com/settings/organization/api-keys) 中生成一个。"
|
||
}
|
||
}
|
||
}
|
||
}
|