> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify-mintlify-4a67096e.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 简介

> 使用 Mintlify REST API 触发部署、嵌入 AI 助手、导出 Analytics 数据，并以编程方式管理文档。

<Info>
  REST API 需要 [Pro 或 Enterprise 方案](https://mintlify.com/pricing?ref=api)。
</Info>

Mintlify 的 REST（Representational State Transfer）API 让你可以以编程方式与文档交互、触发更新、嵌入 AI 驱动的聊天体验，并导出 Analytics 数据。

<div id="endpoints">
  ## 端点
</div>

* [Trigger update](/zh/api/update/trigger)：在需要时触发您站点的更新。
* [Get update status](/zh/api/update/status)：获取某次更新的状态以及与您的文档相关的其他详细信息。
* [Trigger preview deployment](/zh/api/preview/trigger)：为特定分支创建或更新预览部署。
* [Trigger automation](/zh/api/automations/trigger)：按需运行已计划的自动化。
* [Create agent job](/zh/api/agent/v2/create-agent-job)：创建一个代理任务以自动编辑您的文档。
* [Get agent job](/zh/api/agent/v2/get-agent-job)：获取特定代理任务的详细信息和状态。
* [Send follow-up message](/zh/api/agent/v2/send-message)：向已有的代理任务发送后续消息。
* [Create assistant message](/zh/api/assistant/create-assistant-message-v2)：将基于您的文档训练的 AI 助手嵌入到任意您选择的应用中。
* [搜索文档](/zh/api/assistant/search)：搜索您的文档。
* [获取页面内容](/zh/api/assistant/get-page-content)：检索文档页面的完整文本内容。
* [获取用户反馈](/zh/api/analytics/feedback)：从您的文档中导出用户反馈。
* [获取 AI 助手会话](/zh/api/analytics/assistant-conversations)：导出 AI 助手的会话历史。
* [Get assistant caller stats](/zh/api/analytics/assistant-caller-stats)：获取按调用方类型划分的助手查询次数明细。

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

* **自动化部署**：使用 [Trigger update](/zh/api/update/trigger) 和 [Get update status](/zh/api/update/status)，在设定的时间间隔或当特定事件发生时触发站点更新。
* **CI/CD 集成**：在代码变更时，将文档更新作为部署流水线的一部分来执行，使用 [Trigger update](/zh/api/update/trigger)。
* **预览部署**：使用 [Trigger preview deployment](/zh/api/preview/trigger)，在 CI/CD 流水线中以编程方式创建或更新预览部署。
* **按需自动化**：使用 [Trigger automation](/zh/api/automations/trigger)，从 CI/CD 流水线、发布脚本或内部工具中按需运行计划自动化。
* **自定义集成**：使用 [Create assistant message](/zh/api/assistant/create-assistant-message-v2)、[Search documentation](/zh/api/assistant/search) 和 [Get page content](/zh/api/assistant/get-page-content)，将 AI 助手嵌入到你的产品、支持门户或内部工具中。
* **自动化编辑**：使用 agent 任务，以编程方式大规模更新文档，配合 [Create agent job](/zh/api/agent/v2/create-agent-job)、[Get agent job](/zh/api/agent/v2/get-agent-job) 和 [Send follow-up message](/zh/api/agent/v2/send-message)。
* **Analytics 导出**：使用 [Get user feedback](/zh/api/analytics/feedback)、[Get assistant conversations](/zh/api/analytics/assistant-conversations) 和 [Get assistant caller stats](/zh/api/analytics/assistant-caller-stats)，导出反馈、助手会话和调用方统计数据以进行外部分析。

<div id="base-url">
  ## 基础 URL
</div>

所有 Mintlify REST API 请求都使用以下基础 URL：

```
https://api.mintlify.com
```

<div id="authentication">
  ## 认证
</div>

在控制台的 [API keys 页面](https://dashboard.mintlify.com/settings/organization/api-keys)生成 API key。每个 API key 都属于一个组织，你可以在同一组织内的多个部署中使用这些 API key。

每个组织每小时最多可创建 10 个 API key。

<div id="admin-api-key">
  ### 管理员 API key
</div>

使用管理员 API key 对发送到 [Trigger update](/zh/api/update/trigger)、[Get update status](/zh/api/update/status)、[Trigger preview deployment](/zh/api/preview/trigger)、[Trigger automation](/zh/api/automations/trigger)、[Create agent job](/zh/api/agent/v2/create-agent-job)、[Get agent job](/zh/api/agent/v2/get-agent-job)、[Send follow-up message](/zh/api/agent/v2/send-message)、[Get user feedback](/zh/api/analytics/feedback)、[Get assistant conversations](/zh/api/analytics/assistant-conversations) 和 [Get assistant caller stats](/zh/api/analytics/assistant-caller-stats) 的请求进行身份验证。

管理员 API key 以 `mint_` 前缀开头。

管理员 API key 是一个服务器端密钥。不要在客户端代码中暴露它。

<div id="assistant-api-key">
  ### Assistant API key
</div>

使用 assistant API key 对发往 [Create assistant message](/zh/api/assistant/create-assistant-message-v2)、[Search documentation](/zh/api/assistant/search) 和 [Get page content](/zh/api/assistant/get-page-content) 端点的请求进行认证。

assistant API key 以 `mint_dsc_` 前缀开头。

<Note>
  使用 assistant API token 进行的调用可能会产生费用：可能会消耗你的助手额度，或产生超额费用。
</Note>

<div id="restrict-keys-by-ip-address">
  ### 按 IP 地址限制 key
</div>

你可以选择将 API key 限制为一组允许的 IP 地址或 CIDR 范围。当 key 设置了允许列表时，来自任何其他 IP 地址的请求都会以 `403` 响应被拒绝。管理员 API key 和 assistant API key 都支持允许列表。

在控制台的 [API keys 页面](https://dashboard.mintlify.com/settings/organization/api-keys) 创建 key 时设置允许列表。允许列表在 key 的生命周期内固定不变——要更改它，请删除该 key 并创建一个新的。如果不设置允许列表，key 会接受来自任何 IP 地址的请求。

允许列表条目支持：

* IPv4 和 IPv6 地址，例如 `203.0.113.5` 或 `2001:db8::1`。
* CIDR 范围，例如 `198.51.100.0/24` 或 `2001:db8::/48`。

不允许使用 `0.0.0.0/0` 和 `::/0` 等通配条目。

当你的 API key 从一组固定的出口 IP 调用时，请使用 IP 允许列表——例如 CI/CD 运行器、静态 NAT 网关或你的后端服务器。对于从开发者笔记本电脑或其他 IP 会变化的环境使用的 key，请避免使用允许列表。

<div id="restrict-admin-keys-by-scope">
  ### 按 scope 限制管理员 key
</div>

你可以选择将管理员 API key 限制为 `read` 或 `write` scope。scope 仅适用于管理员 API key；assistant API key 不受影响。

在控制台的 [API keys 页面](https://dashboard.mintlify.com/settings/organization/api-keys) 创建 key 时设置 scope。scope 在 key 的生命周期内固定不变——要更改它们，请删除该 key 并创建一个新的。如果不设置任何 scope，该 key 可以调用所有管理员端点（现有 key 保持不变）。

Mintlify 根据请求的 HTTP 方法推导所需的 scope：

| HTTP 方法      | 所需 scope |
| ------------ | -------- |
| `GET`、`HEAD` | `read`   |
| 其他所有方法       | `write`  |

拥有 `write` 的 key 也满足 `read`，因此 `["read", "write"]` 和 `["write"]` 都允许调用所有端点。需要某个 key 未拥有的 scope 的请求会以 `403` 响应被拒绝。

仅接受 `read` 和 `write`。创建 key 时使用任何其他值都会返回 `400` 响应。

<div id="set-an-expiration-date">
  ### 设置过期日期
</div>

你可以在创建任何 API key 时选择性地设置过期日期。过期时间戳过后，使用该 key 的请求将被拒绝。管理员 API key 和 assistant API key 都支持过期设置。

在控制台的 [API keys 页面](https://dashboard.mintlify.com/settings/organization/api-keys) 设置过期时间。过期时间在 key 的生命周期内固定不变——要更改它，请删除该 key 并创建一个新的。如果不设置过期时间，该 key 永不过期。

过期时间必须是未来的 ISO 8601 时间戳。过去或无效的时间戳在创建 key 时会返回 `400` 响应。列出 key 时会以 `expiresAt` 返回过期时间；没有过期时间的 key 返回 `null`。

将过期时间用于短期凭据，例如 CI/CD 令牌、外部合作者或一次性脚本。对于长期使用的 key，可通过创建替代 key、更新集成、然后删除旧 key 的方式进行轮换。