Back to Details

zentao-api

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

禅道 API v2.0

ZenTao API v2.0

配置

Configuration

优先级从高到低：
变量说明
ZENTAO_URL
服务器地址，如 
http://zentao.example.com
ZENTAO_TOKEN
直接指定 token，跳过登录和缓存（最高优先级），仍需提供服务器地址
ZENTAO_ACCOUNT
登录账号，有 token 时可选，但提供可更好回答与当前用户相关的问题
ZENTAO_PASSWORD
登录密码，有 token 时无需提供
首次登录后 
ZENTAO_URL
、
ZENTAO_TOKEN
、
ZENTAO_ACCOUNT
写入 
~/.zentao-token.json
，后续无需重复设置。
若必要变量缺失，提示用户并给出 
export
命令。用户直接提供服务器、账号和密码时直接使用，同时告知尽量设为环境变量。
Priority from highest to lowest:
VariableDescription
ZENTAO_URL
Server address, e.g. 
http://zentao.example.com
ZENTAO_TOKEN
Specify token directly, skip login and cache (highest priority), server address is still required
ZENTAO_ACCOUNT
Login account, optional when token is provided, but providing it can better answer questions related to the current user
ZENTAO_PASSWORD
Login password, no need to provide when token is available
After the first login, 
ZENTAO_URL
, 
ZENTAO_TOKEN
, 
ZENTAO_ACCOUNT
will be written to 
~/.zentao-token.json
, no need to set them repeatedly later.
If necessary variables are missing, prompt the user and provide the 
export
command. If the user directly provides the server, account and password, use them directly, and inform the user to set them as environment variables as much as possible.

认证流程

Authentication Process

所有业务 API 需在 Header 携带 
token
。运行 
scripts/get-token.sh
自动获取：
bash
eval "$(bash scripts/get-token.sh)"
All business APIs need to carry 
token
in the Header. Run 
scripts/get-token.sh
to get it automatically:
bash
eval "$(bash scripts/get-token.sh)"

执行后可直接使用 $ZENTAO_URL、$ZENTAO_TOKEN、$ZENTAO_ACCOUNT

After execution, you can directly use $ZENTAO_URL, $ZENTAO_TOKEN, $ZENTAO_ACCOUNT


脚本依赖：`curl`、`node`

后续所有请求 Header 携带：`token: $ZENTAO_TOKEN`

Script dependencies: `curl`, `node`

All subsequent request Headers carry: `token: $ZENTAO_TOKEN`

执行 API 调用的步骤

Steps to Execute API Calls

  1. 运行 
    eval "$(bash scripts/get-token.sh)"
    获取凭证（自动处理缓存；仍缺失时提示用户）
  2. 根据用户意图选择正确的 API 端点（参见 api-reference.md）
  3. 若为 PUT 编辑操作且用户未提供全部必填字段，先调用对应 GET 详情接口取回当前数据，再将用户指定的字段覆盖进去
  4. 构造请求（方法、URL、Header、Body）并向用户确认写操作内容
  5. 执行请求，解析响应
  6. 以清晰易读的格式向用户展示结果
  1. Run 
    eval "$(bash scripts/get-token.sh)"
    to obtain credentials (automatically handle cache; prompt the user if still missing)
  2. Select the correct API endpoint according to user intent (see api-reference.md)
  3. If it is a PUT edit operation and the user does not provide all required fields, first call the corresponding GET detail interface to retrieve the current data, then overwrite the fields specified by the user
  4. Construct the request (method, URL, Header, Body) and confirm the write operation content with the user
  5. Execute the request and parse the response
  6. Display the results to the user in a clear and readable format

模块总览

Module Overview

API 基础路径：
$ZENTAO_URL/api.php/v2
模块资源路径支持操作
项目集 Program
/programs
CRUD + 关联产品/项目列表
产品 Product
/products
CRUD + 关联需求/Bug/用例/计划/发布/反馈/工单/测试单/应用
项目 Project
/projects
CUD + 关联执行/需求/Bug/用例/版本/测试单
执行 Execution
/executions
CRUD + 关联需求/任务/Bug/用例/版本/测试单
需求 Story
/stories
CRUD + change/close/activate
业务需求 Epic
/epics
CRUD + change/close/activate
用户需求 Requirement
/requirements
CRUD + change/close/activate
Bug
/bugs
CRUD + resolve/close/activate
任务 Task
/tasks
CRUD + start/finish/close/activate
测试用例 Testcase
/testcases
CRUD
产品计划 Productplan
/productplans
CUD + 按产品查列表
版本 Build
/builds
CUD + 按项目/执行查列表
发布 Release
/releases
CUD + 按产品查列表
测试单 Testtask
/testtasks
CUD + 按产品/项目/执行查列表
反馈 Feedback
/feedbacks
CRUD + close/activate
工单 Ticket
/tickets
CRUD + close/activate
应用 System
/systems
CU + 按产品查列表
用户 User
/users
CRUD
文件 File
/files
编辑名称 + 删除
CRUD = 创建(POST) + 读取(GET) + 更新(PUT) + 删除(DELETE)；CUD = 无独立全局列表接口
API base path: 
$ZENTAO_URL/api.php/v2
ModuleResource PathSupported Operations
Program
/programs
CRUD + associated product/project list
Product
/products
CRUD + associated requirements/Bugs/test cases/plans/releases/feedback/tickets/test tasks/applications
Project
/projects
CUD + associated executions/requirements/Bugs/test cases/builds/test tasks
Execution
/executions
CRUD + associated requirements/tasks/Bugs/test cases/builds/test tasks
Story
/stories
CRUD + change/close/activate
Epic
/epics
CRUD + change/close/activate
Requirement
/requirements
CRUD + change/close/activate
Bug
/bugs
CRUD + resolve/close/activate
Task
/tasks
CRUD + start/finish/close/activate
Testcase
/testcases
CRUD
Productplan
/productplans
CUD + query list by product
Build
/builds
CUD + query list by project/execution
Release
/releases
CUD + query list by product
Testtask
/testtasks
CUD + query list by product/project/execution
Feedback
/feedbacks
CRUD + close/activate
Ticket
/tickets
CRUD + close/activate
System
/systems
CU + query list by product
User
/users
CRUD
File
/files
Edit name + Delete
CRUD = Create(POST) + Read(GET) + Update(PUT) + Delete(DELETE); CUD = No independent global list interface

分页与筛选

Pagination and Filtering

所有列表接口支持统一的查询参数：
参数说明
browseType
或 
status
筛选状态，如 
all
, 
doing
, 
unclosed
, 
undone
等（不同模块参数名和可选值不同，详见 api-reference.md）
orderBy
排序，格式 
字段_asc
或 
字段_desc
，如 
id_desc
, 
title_asc
recPerPage
每页数量，最大 1000
pageID
页码，从 1 开始
筛选参数名不一致：Program 列表、Execution 全局列表、Task 列表用 
status
，其余用 
browseType
。
All list interfaces support unified query parameters:
ParameterDescription
browseType
or 
status
Filter status, e.g. 
all
, 
doing
, 
unclosed
, 
undone
, etc. (Parameter names and optional values vary for different modules, see api-reference.md for details)
orderBy
Sort, format 
field_asc
or 
field_desc
, e.g. 
id_desc
, 
title_asc
recPerPage
Number of items per page, maximum 1000
pageID
Page number, starting from 1
Inconsistent filter parameter names: Program list, Execution global list, Task list use 
status
, others use 
browseType
.

常用操作示例

Common Operation Examples

获取进行中的项目及其执行

Get ongoing projects and their executions

bash
curl -s "$ZENTAO_URL/api.php/v2/projects?browseType=doing&recPerPage=100" -H "token: $ZENTAO_TOKEN"
curl -s "$ZENTAO_URL/api.php/v2/projects/{projectID}/executions?browseType=doing" -H "token: $ZENTAO_TOKEN"
bash
curl -s "$ZENTAO_URL/api.php/v2/projects?browseType=doing&recPerPage=100" -H "token: $ZENTAO_TOKEN"
curl -s "$ZENTAO_URL/api.php/v2/projects/{projectID}/executions?browseType=doing" -H "token: $ZENTAO_TOKEN"

创建需求（必填：productID, title）

Create a requirement (Required: productID, title)

bash
curl -s -X POST "$ZENTAO_URL/api.php/v2/stories" \
  -H "token: $ZENTAO_TOKEN" -H "Content-Type: application/json" \
  -d '{"productID": 1, "title": "需求标题", "pri": 3, "assignedTo": "admin", "spec": "需求描述"}'
bash
curl -s -X POST "$ZENTAO_URL/api.php/v2/stories" \
  -H "token: $ZENTAO_TOKEN" -H "Content-Type: application/json" \
  -d '{"productID": 1, "title": "Requirement title", "pri": 3, "assignedTo": "admin", "spec": "Requirement description"}'

创建 Bug（必填：productID, title, openedBuild）

Create a Bug (Required: productID, title, openedBuild)

bash
curl -s -X POST "$ZENTAO_URL/api.php/v2/bugs" \
  -H "token: $ZENTAO_TOKEN" -H "Content-Type: application/json" \
  -d '{"productID": 1, "title": "Bug标题", "openedBuild": ["trunk"], "severity": 2, "type": "codeerror"}'
bash
curl -s -X POST "$ZENTAO_URL/api.php/v2/bugs" \
  -H "token: $ZENTAO_TOKEN" -H "Content-Type: application/json" \
  -d '{"productID": 1, "title": "Bug title", "openedBuild": ["trunk"], "severity": 2, "type": "codeerror"}'

解决 Bug（必填：resolution）

Resolve a Bug (Required: resolution)

bash
curl -s -X PUT "$ZENTAO_URL/api.php/v2/bugs/{bugID}/resolve" \
  -H "token: $ZENTAO_TOKEN" -H "Content-Type: application/json" \
  -d '{"resolution": "fixed"}'
bash
curl -s -X PUT "$ZENTAO_URL/api.php/v2/bugs/{bugID}/resolve" \
  -H "token: $ZENTAO_TOKEN" -H "Content-Type: application/json" \
  -d '{"resolution": "fixed"}'

创建任务（必填：name, executionID）

Create a task (Required: name, executionID)

bash
curl -s -X POST "$ZENTAO_URL/api.php/v2/tasks" \
  -H "token: $ZENTAO_TOKEN" -H "Content-Type: application/json" \
  -d '{"executionID": 1, "name": "任务名", "type": "devel", "assignedTo": "admin", "estimate": 4}'
bash
curl -s -X POST "$ZENTAO_URL/api.php/v2/tasks" \
  -H "token: $ZENTAO_TOKEN" -H "Content-Type: application/json" \
  -d '{"executionID": 1, "name": "Task name", "type": "devel", "assignedTo": "admin", "estimate": 4}'

完成任务（必填：currentConsumed, realStarted, finishedDate）

Finish a task (Required: currentConsumed, realStarted, finishedDate)

bash
curl -s -X PUT "$ZENTAO_URL/api.php/v2/tasks/{taskID}/finish" \
  -H "token: $ZENTAO_TOKEN" -H "Content-Type: application/json" \
  -d '{"currentConsumed": 4, "realStarted": "2026-03-25", "finishedDate": "2026-03-25"}'
bash
curl -s -X PUT "$ZENTAO_URL/api.php/v2/tasks/{taskID}/finish" \
  -H "token: $ZENTAO_TOKEN" -H "Content-Type: application/json" \
  -d '{"currentConsumed": 4, "realStarted": "2026-03-25", "finishedDate": "2026-03-25"}'

关闭需求（必填：closedReason）

Close a requirement (Required: closedReason)

bash
curl -s -X PUT "$ZENTAO_URL/api.php/v2/stories/{storyID}/close" \
  -H "token: $ZENTAO_TOKEN" -H "Content-Type: application/json" \
  -d '{"closedReason": "done"}'
bash
curl -s -X PUT "$ZENTAO_URL/api.php/v2/stories/{storyID}/close" \
  -H "token: $ZENTAO_TOKEN" -H "Content-Type: application/json" \
  -d '{"closedReason": "done"}'

常用枚举值速查

Common Enumeration Value Quick Reference

字段可选值
项目模式 
model
scrum
, 
waterfall
, 
kanban
, 
agileplus
, 
waterfallplus
Bug 类型 
type
codeerror
, 
config
, 
install
, 
security
, 
performance
, 
standard
, 
automation
, 
designdefect
, 
others
Bug 解决方案 
resolution
fixed
, 
notrepro
, 
bydesign
, 
duplicate
, 
external
, 
postponed
, 
willnotfix
, 
tostory
需求关闭原因 
closedReason
done
, 
subdivided
, 
duplicate
, 
postponed
, 
willnotdo
, 
cancel
, 
bydesign
需求来源 
source
customer
, 
user
, 
po
, 
market
, 
service
, 
operation
, 
support
, 
competitor
, 
partner
, 
dev
, 
tester
, 
bug
, 
forum
, 
other
需求类别 
category
feature
, 
interface
, 
performance
, 
safe
, 
experience
, 
improve
, 
other
用例类型 
type
unit
, 
interface
, 
feature
, 
install
, 
config
, 
performance
, 
security
, 
other
测试单类型 
type
integrate
, 
system
, 
acceptance
, 
performance
, 
safety
发布状态 
status
wait
, 
normal
, 
fail
, 
terminate
反馈关闭原因 
closedReason
commented
, 
repeat
, 
refuse
工单类型 
type
code
, 
data
, 
stuck
, 
security
, 
affair
产品类型 
type
normal
, 
branch
, 
platform
产品访问控制 
acl
open
, 
private
执行类型 
lifetime
short
, 
long
, 
ops
FieldOptional Values
Project mode 
model
scrum
, 
waterfall
, 
kanban
, 
agileplus
, 
waterfallplus
Bug type 
type
codeerror
, 
config
, 
install
, 
security
, 
performance
, 
standard
, 
automation
, 
designdefect
, 
others
Bug resolution 
resolution
fixed
, 
notrepro
, 
bydesign
, 
duplicate
, 
external
, 
postponed
, 
willnotfix
, 
tostory
Requirement closing reason 
closedReason
done
, 
subdivided
, 
duplicate
, 
postponed
, 
willnotdo
, 
cancel
, 
bydesign
Requirement source 
source
customer
, 
user
, 
po
, 
market
, 
service
, 
operation
, 
support
, 
competitor
, 
partner
, 
dev
, 
tester
, 
bug
, 
forum
, 
other
Requirement category 
category
feature
, 
interface
, 
performance
, 
safe
, 
experience
, 
improve
, 
other
Test case type 
type
unit
, 
interface
, 
feature
, 
install
, 
config
, 
performance
, 
security
, 
other
Test task type 
type
integrate
, 
system
, 
acceptance
, 
performance
, 
safety
Release status 
status
wait
, 
normal
, 
fail
, 
terminate
Feedback closing reason 
closedReason
commented
, 
repeat
, 
refuse
Ticket type 
type
code
, 
data
, 
stuck
, 
security
, 
affair
Product type 
type
normal
, 
branch
, 
platform
Product access control 
acl
open
, 
private
Execution type 
lifetime
short
, 
long
, 
ops

意图识别规则

Intent Recognition Rules

用户意图关键词对应操作
进行中的执行/迭代/SprintGET /projects?browseType=doing → GET /projects/{id}/executions
获取所有产品/项目/项目集GET /products, /projects, /programs
某产品/项目/执行的 BugGET /products/{id}/bugs, /projects/{id}/bugs, /executions/{id}/bugs
创建/新增 BugPOST /bugs（必填：productID, title, openedBuild）
更新/修改 BugPUT /bugs/{id}
解决 BugPUT /bugs/{id}/resolve（必填：resolution）
关闭 BugPUT /bugs/{id}/close
激活 BugPUT /bugs/{id}/activate
创建需求POST /stories（必填：productID, title）
关闭/激活/变更需求PUT /stories/{id}/close, /activate, /change
业务需求/epics（同 stories 结构）
用户需求/requirements（同 stories 结构）
创建任务POST /tasks（必填：name, executionID）
启动任务PUT /tasks/{id}/start（必填：realStarted）
完成任务PUT /tasks/{id}/finish（必填：currentConsumed, realStarted, finishedDate）
关闭任务PUT /tasks/{id}/close
测试用例/testcases（CRUD）
测试单/testtasks（CUD + 按产品/项目/执行查列表）
产品计划/productplans（CUD + 按产品查列表）
版本/Build/builds（CUD + 按项目/执行查列表）
发布/releases（CUD + 按产品查列表）
反馈/feedbacks（CRUD + close/activate）
工单/tickets（CRUD + close/activate）
应用/系统/systems（CU + 按产品查列表）
获取用户列表GET /users
User intent keywordsCorresponding operation
Ongoing execution/iteration/SprintGET /projects?browseType=doing → GET /projects/{id}/executions
Get all products/projects/programsGET /products, /projects, /programs
Bugs of a product/project/executionGET /products/{id}/bugs, /projects/{id}/bugs, /executions/{id}/bugs
Create/add BugPOST /bugs (Required: productID, title, openedBuild)
Update/modify BugPUT /bugs/{id}
Resolve BugPUT /bugs/{id}/resolve (Required: resolution)
Close BugPUT /bugs/{id}/close
Activate BugPUT /bugs/{id}/activate
Create requirementPOST /stories (Required: productID, title)
Close/activate/change requirementPUT /stories/{id}/close, /activate, /change
Epic/epics (same structure as stories)
Requirement/requirements (same structure as stories)
Create taskPOST /tasks (Required: name, executionID)
Start taskPUT /tasks/{id}/start (Required: realStarted)
Finish taskPUT /tasks/{id}/finish (Required: currentConsumed, realStarted, finishedDate)
Close taskPUT /tasks/{id}/close
Test case/testcases (CRUD)
Test task/testtasks (CUD + query list by product/project/execution)
Product plan/productplans (CUD + query list by product)
Build/builds (CUD + query list by project/execution)
Release/releases (CUD + query list by product)
Feedback/feedbacks (CRUD + close/activate)
Ticket/tickets (CRUD + close/activate)
Application/system/systems (CU + query list by product)
Get user listGET /users

注意事项

Notes

  • URL 中的 
    {id}
    需替换为实际 ID；不知道 ID 时先调列表接口获取
  • PUT 编辑接口：先 GET 详情获取当前完整数据，再将用户修改的字段覆盖进去一并提交
  • 状态流转操作 (resolve/close/activate/start/finish/change) 通常有独立的必填字段，不需要先 GET 详情
  • 写操作前向用户确认，用户明确要求不确认则直接执行
  • 401 响应表示 token 已失效，执行 
    rm ~/.zentao-token.json
    清除缓存后重新运行
  • 字段名不一致注意：POST builds 用 
    executionID
    ，PUT builds 用 
    execution
    ；PUT testcases 的模块字段为 
    moudule
    （规范中的拼写）
  • {id}
    in the URL needs to be replaced with the actual ID; if you don't know the ID, call the list interface first to get it
  • PUT edit interface: First GET the details to get the current complete data, then overwrite the fields modified by the user and submit together
  • Status flow operations (resolve/close/activate/start/finish/change) usually have independent required fields, no need to GET details first
  • Confirm with the user before write operations, execute directly if the user explicitly requests no confirmation
  • 401 response indicates that the token has expired, execute 
    rm ~/.zentao-token.json
    to clear the cache and run again
  • Note on inconsistent field names: POST builds use 
    executionID
    , PUT builds use 
    execution
    ; the module field of PUT testcases is 
    moudule
    (spelling in the specification)

完整 API 参考

Complete API Reference

详细的端点列表、必填/可选字段、枚举值和查询参数见 api-reference.md。
For detailed endpoint lists, required/optional fields, enumeration values and query parameters, see api-reference.md.

备用资源

Backup Resources