创建 GanttFather API 令牌，安全调用 v1 REST API，处理配额和幂等性，并在 REST 和 MCP 之间进行选择。
GanttFather REST API 公开脚本和集成的版本化项目、任务、依赖项、成员和资源操作。使用 GanttFather 令牌进行身份验证，发送非空 User-Agent 标头，从读取调用开始，并在创建可重试的任务或资源时使用幂等密钥。
API 行为已于 2026 年 8 月 7 日验证。 实时 API 参考 作为端点级合同。
您可以使用 GanttFather API 实现什么自动化？
v1 API 支持常见的计划集成工作流程：
- 列出可访问的项目并检查一个项目
- 列出并读取任务、成员、资源和依赖项
- 创建、部分更新、重新排序和删除任务
- 添加或删除任务依赖项
- 创建、更新和删除资源
- 附加您自己的外部记录和 GanttFather id 之间的映射
公共 API 与浏览器的内部 API 不是同一个表面。仅使用记录的 v1 端点和响应字段。
如何创建和使用 API 代币？
打开 GanttFather，转到 设置 → AI Agents & API，并创建具有最小有用范围和权限的令牌。当显示原始令牌时复制它并将其存储在秘密管理器中； GanttFather 不存储原始值以供以后显示。
然后按照以下顺序操作：
每个请求都必须包含承载令牌和标识客户端的非空用户代理。在正常端点处理之前，丢失的用户代理将被拒绝。
哪些安全规则对于写入很重要？
仅对您的集成拥有的字段使用部分更新。在更改之前读取当前状态，记录稳定的 ID 和跟踪信息，并且不要将每个外部字段都变成无条件覆盖。
对于任务和资源创建，当超时或网络故障可能导致重试时，发送幂等密钥。对相同请求重复使用密钥会返回之前的结果；与不同的请求重用它会产生冲突。更新和删除具有其记录的语义，并且不接受仅创建密钥作为通用重复数据删除机制。
依赖关系和层次结构是不同的问题。重新排序是改变家长安置的认可方式；依赖端点对前驱关系进行建模。验证两者而不是从另一个派生一个。
费率和每日配额限制是多少？
默认保护为 每个经过身份验证的令牌每分钟 60 个请求 和 每个令牌每天 5,000 个请求。有限响应使用 HTTP 429 并提供重试信息。检查当前 速率限制和配额文件 在规划生产工作负载之前，因为操作限制可能会发生变化。
通过正确分页、批量读取、缓存稳定 ID 以及发送一个部分更新而不是一系列每个字段更新来减少请求量。重试循环应遵循 Retry-After 并使用带抖动的有界指数退避。
什么时候应该使用 REST 而不是 MCP？
当确定性应用程序代码需要版本化 HTTP 资源、显式错误响应和受控重试行为时，请使用 REST。使用 MCP 服务器 当 AI 客户端（例如 Claude）应通过 Model Context Protocol 调用更高级别的项目工具时。
两者都可以使用 GanttFather 的代币通道，但它们的操作和幂等性输入不可互换。 API 集成应遵循 REST 参考；代理应遵循 MCP 工具说明。
什么是安全第一集成模式？
从每个字段的一个方向和一个所有者开始：
| 步骤 | 推荐行为 |
|---|---|
| 发现 | 列出项目并记录所选项目 id |
| 阅读 | 翻阅当前任务并构建 id 映射 |
| 比较 | 无需编写即可计算变更集 |
| 评论 | 记录预期的创建、更新和删除 |
| 写 | 应用最小支持的突变 |
| 验证 | 读取结果并记录返回的id |
在定义冲突所有权、删除规则、重试和恢复之前，请勿声明“同步”。
什么时候应该在 GanttFather API 上构建？
当表单、部署管道、客户门户或内部系统需要重复访问您的团队在 GanttFather 中看到的相同项目数据时，请使用 API。最可靠的第一个用例是狭窄的——例如，在部署后创建一个发布里程碑——然后在观察实际故障和重试后进行扩展。
API 不会决定哪个系统拥有字段或使多系统工作流程无冲突。您的集成必须定义这些规则。
创建 GanttFather 项目，发出最低权限令牌，并在连接生产记录之前对一次性数据进行测试。
常见问题
免费套餐中是否包含 API 访问权限？
目前可在 GanttFather 计划中使用 API 访问权限。容量和保护限制仍然适用；验证 定价页面 以及当前条款的 API 配额文档。
GanttFather API 令牌是什么样的？
令牌使用 GanttFather 令牌格式并作为承载凭证呈现。切勿将令牌提交到源代码管理或将其包含在公共日志中。
用户代理是可选的吗？
对于正常的 v1 请求，否。发送标识您的集成的非空值，例如产品名称和版本。
每个请求都应该包含幂等密钥吗？
否。当可以重试相同的请求时，将其用于记录的创建操作。它不是通用版本或并发标头。
API 可以配置 Azure DevOps 集成源吗？
公共 v1 项目数据 API 和产品的 Azure DevOps 集成是单独的表面。不要假设存在未记录的集成端点。
OpenAPI 文档在哪里？
从 GanttFather API 介绍 并按照身份验证、端点、架构和错误的参考链接进行操作。
