External API 概述

External API 使用项目 API Key 认证，适合从外部系统（脚本、CI/CD、第三方服务）调用 TaskFlow。

Base URL

http://your-server:8000/external/v1

认证

在每个请求的 Authorization Header 中传入 API Key：

Authorization: Bearer tf_b1af5033_3a7f2e1d9c...

API Key 在「项目设置 → API Keys」页面创建，创建后只显示一次，请妥善保存。

格式： tf_{project_id前8位}_{32位随机字符串}

错误响应

所有错误统一返回 JSON：

{
  "error": "invalid_api_key",
  "message": "API key is invalid or expired"
}

常见状态码：

状态码	说明
400	请求参数错误或业务逻辑错误
401	API Key 无效或已过期
403	API Key 不属于请求的项目
404	资源不存在

路径参数

所有端点路径中的 {project_id} 为项目 UUID，必须与 API Key 对应的项目匹配。