skills/mintlify__docs
1
0
Fork 0
mirror of https://github.com/mintlify/docs.git synced 2026-09-14 13:35:46 +08:00
Code Issues Packages Projects Releases Wiki Activity
Files
main
mintlify__docs/zh/api/introduction.mdx
T
mintlify[bot] 41af0c5388 Update from code changes: remove retired mint deslop command (#7005) 
* docs: remove retired mint deslop CLI command

* docs: remove retired deslop API endpoint and references

---------

Co-authored-by: mintlify[bot] <109931778+mintlify[bot]@users.noreply.github.com>
2026-08-18 09:27:39 -07:00

153 lines
9.8 KiB
Plaintext
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
---
title: "简介"
description: "使用 Mintlify REST API 触发部署、嵌入 AI 助手、导出 Analytics 数据，并以编程方式管理文档。"
keywords: ["REST API", "endpoints", "API keys"]
boost: 3
---
<Info>
平台 REST API 需要 [Pro 或 Enterprise 方案](https://mintlify.com/pricing?ref=api)。
[Mintlify Index REST API](/zh/api/search-index/introduction) 使用单独的 API key 和基础 URL。
</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)，将 AI 助手嵌入到你的产品、支持门户或内部工具中。
* **文档检索**：使用 [Search documentation](/zh/api/assistant/search) 和 [Get page content](/zh/api/assistant/get-page-content)，为自定义搜索体验查找和检索文档。
* **自动化编辑**：使用 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。管理员和 Index API key 属于组织。你可以在同一组织内的多个部署中使用相同的 key。Assistant API key 属于创建它的部署。
每个组织每小时最多可创建 10 个 API key。
创建 API key 时，你可以将其设置为在 7、30、60 或 90 天后过期，或选择**永不过期**。新的 API key 默认在 90 天后过期。API keys 页面会为将在 7 天内过期的 API key 显示**将在 … 后过期**徽章，为已过期的 API key 显示**已过期**徽章。已过期的 API key 将停止工作，请在过期日期之前轮换或更换它们。
Mintlify 使用三种 API key，每种 key 对应不同的端点集合：
| key 类型 | 前缀 | 用途 |
| ----------------- | ----------- | -------------------------------------------------------- |
| 管理员 API key | `mint_` | 更新、代理任务和 Analytics 导出。仅限服务器端。 |
| Assistant API key | `mint_dsc_` | 助手消息、文档搜索和页面内容。生产环境使用代理。 |
| Index API key | `mint_us_` | Index 搜索、上下文组装和内容检索。仅限服务器端。 |
<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>
Search documentation 和 Get page content 请求不消耗额度。Create assistant message 请求会消耗额度，并可能产生超额费用。
</Note>
<div id="index-api-key">
### Index API key
</div>
使用 Index API key 对 [Mintlify Index REST API](/zh/search-index) 的请求进行认证。Index API key 以 `mint_us_` 前缀开头。
Index API key 是一个服务器端密钥。不要在客户端代码中暴露它。
<div id="restrict-keys-by-ip-address">
### 按 IP 地址限制 key
</div>
你可以选择将 API key 限制为一组允许的 IP 地址或 CIDR 范围。当 key 设置了允许列表时，来自任何其他 IP 地址的请求都会以 `403` 响应被拒绝。管理员、Assistant 和 Index 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 的请求会以 `401` 响应被拒绝。所有 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 的方式进行轮换。
Reference in New Issue View Git Blame Copy Permalink