mintlify__docs/zh/static-export-openapi.json

{
  "openapi": "3.0.1",
  "info": {
    "title": "Mintlify 静态导出 API",
    "description": "以编程方式生成自包含的文档静态导出，并将其作为单个软件包下载。仅适用于 Enterprise 套餐。",
    "version": "1.0.0"
  },
  "servers": [
    {
      "url": "https://api.mintlify.com/v1"
    }
  ],
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "paths": {
    "/static-export/{projectId}/jobs": {
      "post": {
        "summary": "启动静态导出任务",
        "description": "为部署启动一个静态导出任务。该任务会将你的文档预渲染为一组自包含的静态 HTML、RSC 及资源文件，然后将结果打包为单个可下载的归档文件。\n\n每个部署同一时间只能有一个处于活动状态的静态导出任务。当已有任务处于 `queued` 或 `running` 状态时启动新任务，将返回 `409`。速率限制为每个组织每小时最多启动 10 个任务。\n\n静态导出仅适用于 Enterprise 套餐。\n\n使用管理员 API 密钥进行身份验证。",
        "operationId": "startStaticExportJob",
        "parameters": [
          {
            "$ref": "#/components/parameters/projectId"
          }
        ],
        "responses": {
          "202": {
            "description": "导出任务已被接受并加入队列。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/StaticExportJob"
                }
              }
            }
          },
          "401": {
            "description": "身份验证失败。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "该部署未启用静态导出。请联系 sales@mintlify.com 进行升级。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "该部署已存在正在进行的静态导出任务。请等待当前任务完成后再启动新任务。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "已超出速率限制。静态导出 API 允许每个组织每小时最多启动 10 个任务。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/static-export/{projectId}/jobs/{jobId}": {
      "get": {
        "summary": "获取静态导出任务状态",
        "description": "获取静态导出任务的当前状态。启动任务后，可以轮询此端点，直到 `status` 变为 `completed`（或 `failed`）。\n\n任务完成后，响应中会包含 `bundleUrl`、`sizeBytes` 和 `expiresAt`。`bundleUrl` 是一个有时限的预签名 S3 链接。请在 `expiresAt` 时间戳之前下载该软件包。可再次调用此端点获取新的链接，底层的导出文件仍可复用。\n\n静态导出仅适用于 Enterprise 套餐。\n\n使用管理员 API 密钥进行身份验证。",
        "operationId": "getStaticExportJob",
        "parameters": [
          {
            "$ref": "#/components/parameters/projectId"
          },
          {
            "name": "jobId",
            "in": "path",
            "description": "由 `Start static export job` 返回的静态导出任务的 ID。",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "导出任务的当前状态。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/StaticExportJob"
                }
              }
            }
          },
          "401": {
            "description": "身份验证失败。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "该部署未启用静态导出。请联系 sales@mintlify.com 进行升级。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "该部署下不存在使用所提供 ID 的任务。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "Authorization 请求头需要使用 Bearer 令牌。请使用管理员 API 密钥。这是仅供服务端使用的机密密钥。你可以在控制台的 [API 密钥页面](https://app.mintlify.com/settings/organization/api-keys) 中生成一个。"
      }
    },
    "parameters": {
      "projectId": {
        "schema": {
          "type": "string",
          "description": "你的项目 ID。可以从控制台的 [API 密钥](https://app.mintlify.com/settings/organization/api-keys) 页面复制。"
        },
        "required": true,
        "name": "projectId",
        "in": "path"
      }
    },
    "schemas": {
      "StaticExportJob": {
        "type": "object",
        "required": ["jobId", "status", "createdAt", "updatedAt"],
        "properties": {
          "jobId": {
            "type": "string",
            "description": "静态导出任务的唯一标识符。",
            "example": "6520f3a1c9b1a20012ab34cd"
          },
          "status": {
            "type": "string",
            "description": "任务的当前状态。",
            "enum": ["queued", "running", "completed", "failed"],
            "example": "completed"
          },
          "createdAt": {
            "type": "string",
            "format": "date-time",
            "description": "任务的创建时间。"
          },
          "updatedAt": {
            "type": "string",
            "format": "date-time",
            "description": "任务上次状态变更的时间。"
          },
          "error": {
            "type": "string",
            "description": "人类可读的错误消息。仅当 `status` 为 `failed` 时才会出现，否则为 `null`。",
            "nullable": true
          },
          "bundleUrl": {
            "type": "string",
            "format": "uri",
            "description": "指向静态导出软件包归档的有时限预签名 S3 链接。仅当 `status` 为 `completed` 时才会出现。请在 `expiresAt` 之前下载该软件包。可再次调用此端点获取新的链接。",
            "example": "https://mintlify-static-exports.s3.amazonaws.com/6520f3a1c9b1a20012ab34cd/export.zip?X-Amz-Signature=..."
          },
          "sizeBytes": {
            "type": "integer",
            "description": "软件包大小（字节）。仅当 `status` 为 `completed` 时才会出现。",
            "example": 18432000
          },
          "expiresAt": {
            "type": "string",
            "format": "date-time",
            "description": "当前 `bundleUrl` 的过期时间。仅当 `status` 为 `completed` 时才会出现。"
          }
        }
      },
      "Error": {
        "type": "object",
        "properties": {
          "error": {
            "type": "string",
            "description": "人类可读的错误描述。"
          }
        }
      }
    }
  }
}