ZenTao API v2.0

Configuration

Priority from highest to lowest:

Variable	Description
`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

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)"
# After execution, you can directly use $ZENTAO_URL, $ZENTAO_TOKEN, $ZENTAO_ACCOUNT

Script dependencies:

curl

node

All subsequent request Headers carry:

token: $ZENTAO_TOKEN

Steps to Execute API Calls

Run
```
eval "$(bash scripts/get-token.sh)"
```
to obtain credentials (automatically handle cache; prompt the user if still missing)
Select the correct API endpoint according to user intent (see api-reference.md)
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
Construct the request (method, URL, Header, Body) and confirm the write operation content with the user
Execute the request and parse the response
Display the results 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
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

All list interfaces support unified query parameters:

Parameter	Description
`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"

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": "Requirement title", "pri": 3, "assignedTo": "admin", "spec": "Requirement description"}'

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 title", "openedBuild": ["trunk"], "severity": 2, "type": "codeerror"}'

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

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": "Task name", "type": "devel", "assignedTo": "admin", "estimate": 4}'

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

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

Common Enumeration Value Quick Reference

Field	Optional 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

User intent keywords	Corresponding operation
Ongoing execution/iteration/Sprint	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
Epic	/epics (same structure as stories)
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 + 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 list	GET /users

Notes

```
{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)

Complete API Reference

For detailed endpoint lists, required/optional fields, enumeration values and query parameters, see api-reference.md.

Backup Resources

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

zentao-api

NPX Install

Tags

SKILL.md Content (Chinese)

ZenTao API v2.0

Configuration

Authentication Process

Steps to Execute API Calls

Module Overview

Pagination and Filtering

Common Operation Examples

Get ongoing projects and their executions

Create a requirement (Required: productID, title)

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

Resolve a Bug (Required: resolution)

Create a task (Required: name, executionID)

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

Close a requirement (Required: closedReason)

Common Enumeration Value Quick Reference

Intent Recognition Rules

Notes

Complete API Reference

Backup Resources