简介
使用 Mintlify REST API 触发部署、嵌入 AI 助手、导出 Analytics 数据，并以编程方式管理文档。
REST API 需要 Pro 或 Enterprise 方案。
Mintlify 的 REST（Representational State Transfer）API 让你可以以编程方式与文档交互、触发更新、嵌入 AI 驱动的聊天体验，并导出 Analytics 数据。
- Trigger update：在需要时触发您站点的更新。
- Get update status：获取某次更新的状态以及与您的文档相关的其他详细信息。
- Trigger preview deployment：为特定分支创建或更新预览部署。
- Trigger automation：按需运行已计划的自动化。
- Detect AI-sounding prose：分析页面中由 AI 生成的文字，并获取人工风格的改写建议。
- Create agent job：创建一个代理任务以自动编辑您的文档。
- Get agent job：获取特定代理任务的详细信息和状态。
- Send follow-up message：向已有的代理任务发送后续消息。
- Create assistant message：将基于您的文档训练的 AI 助手嵌入到任意您选择的应用中。
- 搜索文档：搜索您的文档。
- 获取页面内容：检索文档页面的完整文本内容。
- 获取用户反馈：从您的文档中导出用户反馈。
- 获取 AI 助手会话：导出 AI 助手的会话历史。
- Get assistant caller stats：获取按调用方类型划分的助手查询次数明细。
- 自动化部署：使用 Trigger update 和 Get update status，在设定的时间间隔或当特定事件发生时触发站点更新。
- CI/CD 集成：在代码变更时，将文档更新作为部署流水线的一部分来执行，使用 Trigger update。
- 预览部署：使用 Trigger preview deployment，在 CI/CD 流水线中以编程方式创建或更新预览部署。
- 按需自动化：使用 Trigger automation，从 CI/CD 流水线、发布脚本或内部工具中按需运行计划自动化。
- 助手集成：使用 Create assistant message，将 AI 助手嵌入到你的产品、支持门户或内部工具中。
- 文档检索：使用 Search documentation 和 Get page content，为自定义搜索体验查找和检索文档。
- 自动化编辑：使用 agent 任务，以编程方式大规模更新文档，配合 Create agent job、Get agent job 和 Send follow-up message。
- Analytics 导出：使用 Get user feedback、Get assistant conversations 和 Get assistant caller stats，导出反馈、助手会话和调用方统计数据以进行外部分析。
所有 Mintlify REST API 请求都使用以下基础 URL：
https://api.mintlify.com在控制台的 API keys 页面生成 API key。每个 API key 都属于一个组织，你可以在同一组织内的多个部署中使用这些 API key。
每个组织每小时最多可创建 10 个 API key。
创建 API key 时，你可以将其设置为在 7、30、60 或 90 天后过期，或选择永不过期。新的 API key 默认在 90 天后过期。API keys 页面会为将在 7 天内过期的 API key 显示将在 … 后过期徽章，为已过期的 API key 显示已过期徽章。已过期的 API key 将停止工作，请在过期日期之前轮换或更换它们。
使用管理员 API key 对发送到 Trigger update、Get update status、Trigger preview deployment、Trigger automation、Detect AI-sounding prose、Create agent job、Get agent job、Send follow-up message、Get user feedback、Get assistant conversations 和 Get assistant caller stats 的请求进行身份验证。
管理员 API key 以 mint_ 前缀开头。
管理员 API key 是一个服务器端密钥。不要在客户端代码中暴露它。
使用 assistant API key 对发往 Create assistant message、Search documentation 和 Get page content 端点的请求进行认证。
assistant API key 以 mint_dsc_ 前缀开头。
Search documentation 和 Get page content 请求不消耗额度。Create assistant message 请求会消耗额度，并可能产生超额费用。
你可以选择将 API key 限制为一组允许的 IP 地址或 CIDR 范围。当 key 设置了允许列表时，来自任何其他 IP 地址的请求都会以 403 响应被拒绝。管理员 API key 和 assistant API key 都支持允许列表。
在控制台的 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，请避免使用允许列表。
你可以选择将管理员 API key 限制为 read 或 write scope。scope 仅适用于管理员 API key；assistant API key 不受影响。
在控制台的 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 响应。
你可以在创建任何 API key 时选择性地设置过期日期。过期时间戳过后，使用该 key 的请求将被拒绝。管理员 API key 和 assistant API key 都支持过期设置。
在控制台的 API keys 页面 设置过期时间。过期时间在 key 的生命周期内固定不变——要更改它，请删除该 key 并创建一个新的。如果不设置过期时间，该 key 永不过期。
过期时间必须是未来的 ISO 8601 时间戳。过去或无效的时间戳在创建 key 时会返回 400 响应。列出 key 时会以 expiresAt 返回过期时间；没有过期时间的 key 返回 null。
将过期时间用于短期凭据，例如 CI/CD 令牌、外部合作者或一次性脚本。对于长期使用的 key，可通过创建替代 key、更新集成、然后删除旧 key 的方式进行轮换。