> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.manicule.dev/zh/llms.txt
> Use this file to discover all available pages before exploring further.
> For every page in one file, fetch https://mintlify.manicule.dev/zh/llms-full.txt (large).
> To search and read these docs as tools, connect the MCP server at https://mintlify.manicule.dev/api/mcp.
> Every agent surface: https://mintlify.manicule.dev/.well-known/llms-manifest.json

# 触发预览部署 (/zh/api/preview/trigger)

<!-- agent-signals: reading_time_min: 1 · est_tokens: 706 · updated: 2026-07-31 -->
Related: [触发部署](/zh/api/update/trigger.md), [触发自动化](/zh/api/automations/trigger.md)

使用此端点以编程方式为 Git 分支创建或更新预览部署。如果指定分支已存在预览，该端点将触发重新部署，而不会创建重复项。

响应中包含一个 `statusId`，你可以将其传递给 [Get deployment status](/zh/api/update/status) 以跟踪部署进度。

<div id="use-cases">
  ## 用例
</div>

* **CI/CD 流水线**：在拉取请求被打开或更新时自动创建预览部署。
* **定时预览**：按计划为长期运行的功能分支生成预览。
* **自定义工具**：将预览创建集成到内部工作流或 Slack 机器人中。

<div id="rate-limits">
  ## 速率限制
</div>

此端点允许每个组织每分钟最多 5 个请求。

`POST /project/preview/{projectId}`

> 为特定分支创建或更新预览部署。如果该分支已有预览，则会触发重新部署。返回用于跟踪进度的状态 ID 和预览 URL。
>
> 使用管理员 API 密钥进行身份验证。

Base URL: `https://api.mintlify.com/v1`

## OpenAPI

```json
{
  "servers": [
    {
      "url": "https://api.mintlify.com/v1"
    }
  ],
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "securitySchemes": {
    "bearerAuth": {
      "type": "http",
      "scheme": "bearer",
      "description": "Authorization 请求头需要使用 Bearer 令牌。请使用管理员 API 密钥。这是仅供服务端使用的机密密钥。你可以在控制台的 [API 密钥页面](https://dashboard.mintlify.com/settings/organization/api-keys) 中生成一个。"
    }
  },
  "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"
              }
            }
          }
        }
      }
    }
  }
}
```