zentao-api

ZenTao API v2.0

Configuration

Priority from high to low:

Variable	Description
ZENTAO_URL	Server address, e.g. http://zentao.example.com
ZENTAO_TOKEN	Specify the token directly, skipping login and cache (highest priority); the server address is still required
ZENTAO_ACCOUNT	Login account; optional when a token is available, but providing it helps better answer questions related to the current user
ZENTAO_PASSWORD	Login password; not required when a token is available

After the first login, ZENTAO_URL、ZENTAO_TOKEN、ZENTAO_ACCOUNT writes to ~/.zentao-token.json, no need to set it again subsequently。

If necessary variables are missing, prompt the user and provide the export command. When the user directly provides the server, account, and password, use them directly, and at the same time tell them to set them as environment variables as much as possible.

Authentication flow

All business APIs need to carry tokenin the Header. Run scripts/get-token.sh to obtain automatically:

eval "$(bash scripts/get-token.sh)"
# 执行后可直接使用 $ZENTAO_URL、$ZENTAO_TOKEN、$ZENTAO_ACCOUNT

Script dependencies:curl、node

All subsequent request Headers carry:token: $ZENTAO_TOKEN

Steps for executing API calls

1. Run eval "$(bash scripts/get-token.sh)" to obtain credentials (cache is handled automatically; if still missing, prompt the user)
2. Select the correct API endpoint according to the user's intent (see api-reference.md）
3. If it is a PUT edit operation and the user has not provided all required fields, first call the corresponding GET detail interface to retrieve the current data, then overwrite it with 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. Present the result to the user in a clear and readable format

Module overview

API base path:$ZENTAO_URL/api.php/v2

Module	Resource path	Supported 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
Business requirement Epic	/epics	CRUD + change/close/activate
User requirement Requirement	/requirements	CRUD + change/close/activate
Bug	/bugs	CRUD + resolve/close/activate
Task	/tasks	CRUD + start/finish/close/activate
Test case Testcase	/testcases	CRUD
Product plan Productplan	/productplans	CUD + list by product
Build	/builds	CUD + list by project/execution
Release	/releases	CUD + list by product
Test task Testtask	/testtasks	CUD + list by product/project/execution
Feedback	/feedbacks	CRUD + close/activate
Ticket	/tickets	CRUD + close/activate
Application System	/systems	CU + list by product
User	/users	CRUD
File	/files	Edit name + delete

CRUD = Create (POST) + Read (GET) + Update (PUT) + Delete (DELETE); CUD = no separate global list endpoint

Pagination and Filtering

All list endpoints support unified query parameters:

Parameter	Description
browseType or status	Filter by status, such as all, doing, unclosed, undone etc. (parameter names and available values differ by module; see api-reference.md）
orderBy	Sort, format 字段_asc or 字段_desc, such as id_desc, title_asc
recPerPage	Number per page, maximum 1000
pageID	Page number, starting from 1

Inconsistent filter parameter names: Program list, Execution global list, and Task list use status, the rest use browseType。

Common Operation Examples

Get in-progress projects and their executions

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"

Create a requirement (required: productID, title)

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

Create a business requirement (Epic)

curl -s -X POST "$ZENTAO_URL/api.php/v2/epics" \
  -H "token: $ZENTAO_TOKEN" -H "Content-Type: application/json" \
  -d '{"productID": 1, "title": "业务需求标题", "grade": 1, "pri": 3, "reviewer": ["admin"]}'

Create a user requirement (Requirement)

curl -s -X POST "$ZENTAO_URL/api.php/v2/requirements" \
  -H "token: $ZENTAO_TOKEN" -H "Content-Type: application/json" \
  -d '{"productID": 1, "title": "用户需求标题", "parent": 1001, "grade": 1, "pri": 3, "reviewer": ["admin"]}'

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

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"}'

Resolve a Bug (required: resolution)

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

Create a task (required: name, executionID)

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}'

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

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"}'

Close a requirement (required: closedReason)

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 Values Quick Reference

Field	Available 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 close 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
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 close 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

User Intent Keyword	Corresponding Operation
In-progress executions/iterations/Sprints	GET /projects?browseType=doing → GET /projects/{id}/executions
Get all products/projects/programs	GET /products, /projects, /programs
Bugs of a product/project/execution	GET /products/{id}/bugs, /projects/{id}/bugs, /executions/{id}/bugs
Create/add Bug	POST /bugs (required: productID, title, openedBuild)
Update/modify Bug	PUT /bugs/{id}
Resolve Bug	PUT /bugs/{id}/resolve (required: resolution)
Close Bug	PUT /bugs/{id}/close
Activate Bug	PUT /bugs/{id}/activate
Create requirement	POST /stories (required: productID, title)
Close/activate/change requirement	PUT /stories/{id}/close, /activate, /change
Business requirement	/epics (same structure as stories)
User requirement	/requirements (same structure as stories)
Create task	POST /tasks (required: name, executionID)
Start task	PUT /tasks/{id}/start (required: realStarted)
Finish task	PUT /tasks/{id}/finish (required: currentConsumed, realStarted, finishedDate)
Close task	PUT /tasks/{id}/close
Test case	/testcases（CRUD）
Test task	/testtasks (CUD + list by product/project/execution)
Product Plans	/productplans (CUD + list by product)
Builds	/builds (CUD + list by project/execution)
Releases	/releases (CUD + list by product)
Feedback	/feedbacks（CRUD + close/activate）
Tickets	/tickets（CRUD + close/activate）
Applications/Systems	/systems (CU + list by product)
Get user list	GET /users

Notes

• The {id} in the URL must be replaced with the actual ID; if you don't know the ID, first call the list API to get it
• When creating Epic / Requirement / Story, it is recommended to always explicitly pass grade, do not rely on the API default value. Some users have reported that some ZenTao instances, when grade is not passed, write the requirement level as 0, causing abnormal display of BR / UR / SR labels in the interface.
• PUT edit API: first GET the details to obtain the current complete data, then overwrite the fields modified by the user and submit them together
• Status transition operations (resolve/close/activate/start/finish/change) usually have independent required fields and do not need to GET the details first
• Confirm with the user before write operations; if the user explicitly requests no confirmation, execute directly
• A 401 response indicates the token has expired; execute rm ~/.zentao-token.json to clear the cache and then run again
• Note on inconsistent field names: POST builds uses executionID, PUT builds uses execution; the module field of PUT testcases is moudule(the spelling in the specification)

Complete API Reference

For the detailed endpoint list, required/optional fields, enum values, and query parameters, see api-reference.md。

Alternative Resources

• ZenTao API 2.0 official documentation:https://www.zentao.net/book/api/2309.html
• 1.0 API documentation (alternative):https://www.zentao.net/book/api/1397.html