REST API 需要 Pro 或 Enterprise 方案。
端点
- Trigger update：在需要时触发您站点的更新。
- Get update status：获取某次更新的状态以及与您的文档相关的其他详细信息。
- Trigger preview deployment：为特定分支创建或更新预览部署。
- Trigger automation：按需运行已计划的自动化。
- 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、Search documentation 和 Get page content，将 AI 助手嵌入到你的产品、支持门户或内部工具中。
- 自动化编辑：使用 agent 任务，以编程方式大规模更新文档，配合 Create agent job、Get agent job 和 Send follow-up message。
- Analytics 导出：使用 Get user feedback、Get assistant conversations 和 Get assistant caller stats，导出反馈、助手会话和调用方统计数据以进行外部分析。
基础 URL
认证
管理员 API key
mint_ 前缀开头。
管理员 API key 是一个服务器端密钥。不要在客户端代码中暴露它。
Assistant API key
mint_dsc_ 前缀开头。
使用 assistant API token 进行的调用可能会产生费用：可能会消耗你的助手额度，或产生超额费用。
按 IP 地址限制 key
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，请避免使用允许列表。
按 scope 限制管理员 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 响应。
设置过期日期
400 响应。列出 key 时会以 expiresAt 返回过期时间；没有过期时间的 key 返回 null。
将过期时间用于短期凭据，例如 CI/CD 令牌、外部合作者或一次性脚本。对于长期使用的 key，可通过创建替代 key、更新集成、然后删除旧 key 的方式进行轮换。