tapd-openapi

TAPD OpenAPI

Environment variables (already preset)

• TAPD_API_ENDPOINT - API address, if TAPD_API_ENDPOINT is configured, then preferentially use TAPD_API_ENDPOINT the replacement in the documentation for ${TAPD_API_ENDPOINT}
• TAPD_WORKSPACE_IDS - Project ID list, comma-separated,takes priority over TAPD_WORKSPACE_ID
• TAPD_WORKSPACE_ID - Single project ID (compatible with old configuration)
• TAPD_TOKEN - Authentication Token (Bearer method)

Workspace handling rules

Before calling, you must first determine the actual list of workspaces to use:

# 优先取 TAPD_WORKSPACE_IDS，回退到 TAPD_WORKSPACE_ID
if [ -n "$TAPD_WORKSPACE_IDS" ]; then
  WS_LIST=$(echo "$TAPD_WORKSPACE_IDS" | tr ',' ' ')
else
  WS_LIST="$TAPD_WORKSPACE_ID"
fi

• If WS_LIST has only one ID, make a normal request as a single workspace
• If there are multiple IDs, you need to call the API separately for each ID, then aggregate the results (sum, merge lists, etc., depending on the user's intent)
• Note that when using curl, workspace_id should be comma-separated. For example, if $TAPD_WORKSPACE_IDS is "31372104,68119668", then when using curl you need to call workspace_id=31372104 and workspace_id=68119668

Request template

# GET
curl -s -H "Authorization: Bearer $TAPD_TOKEN" \
  "${TAPD_API_ENDPOINT}/${path}?workspace_id=${ws_id}"

# POST
curl -s -X POST -H "Authorization: Bearer $TAPD_TOKEN" \
  -H "Content-Type: application/json" \
  "${TAPD_API_ENDPOINT}/${path}" \
  -d '{"workspace_id":"'"${ws_id}"'","key":"value"}'

Query API documentation

API documentation is located in the ~/.codebuddy/skills/tapd-openapi/references/ directory.

1. List all services：

ls ~/.codebuddy/skills/tapd-openapi/references/

2. List APIs under a service：

ls ~/.codebuddy/skills/tapd-openapi/references/stories/

3. View API details：

cat ~/.codebuddy/skills/tapd-openapi/references/stories/liststories.md

Common services

Service	Description	Common API files
stories	Requirement management	liststories, countstories, addstory, updatestory, getrelatedbugs, getstoryfieldsinfo
bugs	Defect management	listbugs, countbugs, addbug, updatebug, getbugfieldsinfo
iterations	Iteration management	listiterations
tasks	Task management	listtasks, counttasks, addtask, updatetask
comments	Comment management	listcomments, countcomments, addcomment
wikis	Wiki management	listwikis, countwikis, addwiki, updatewiki, searchwiki(see below)
timesheets	Timesheet effort	listtimesheets, counttimesheets, addtimesheet, updatetimesheet
attachments	Attachment management	listattachments, downloadattachment, getimage, downloaddocument
users	User information	getuserinfo, listworkspaces

Call flow

1. Determine the service: choose from common services based on the requirement, or use ls to view all
2. Find the API: use ls ~/.codebuddy/skills/tapd-openapi/references/{服务}/ to find the specific operation
3. Get details: use cat to read the API documentation and obtain the request method, path, and parameters
4. Execute the request: construct the curl command according to the template,workspace_id is required

Wiki search

TAPD API does not support Wiki full-text search; this is implemented through a local script. See:

cat ~/.codebuddy/skills/tapd-openapi/references/wikis/searchwiki.md