CreateWorkitem,Create work item-Alibaba Cloud DevOps(Alibaba Cloud DevOps)-阿里云帮助中心

This API creates work items in a project, such as requirements, defects, tasks, risks, and epics. To determine the required fields for a specific work item type, call the ListWorkitemTypes and ListWorkitemTypeFields operations.

Applicable editions

Central edition, Region edition

Service endpoint and authorization

Obtain the service endpoint: Replace {domain} in the request syntax.
Obtain a personal access token.
Obtain the organization ID: Required only for Central edition. Go to the Organization Management console and find the organization ID on the Basic Information page.

Product	Resource	Required permissions
Project Collaboration	work item	Read and write

Request syntax

Central edition

POST https://{domain}/oapi/v1/projex/organizations/{organizationId}/workitems

Region edition

POST https://{domain}/oapi/v1/projex/workitems

Request headers

Parameter	Type	Required	Description	Example
x-yunxiao-token	string	Yes	Your personal access token.	pt-0fh3**0fbG_35af**0484

Request parameters

Parameter	Type	In	Required	Description	Example
organizationId	string	path	Required for Central edition Not required for Region edition	The ID of the organization.	6f2b4899c614451d8b943262e84d****
-	object	body	Yes	The request body.
assignedTo	string	body	Yes	The user ID of the assignee.	674d96abd497cd558d68****
customFieldValues	object	body	No	A key-value map for custom fields. Use the format `{"fieldId":"value"}`. For fields that accept multiple values, separate the values with a comma, such as `{"fieldId": "value1,value2"}`. The `fieldId` corresponds to `SystemCustomField` or `CustomField` types and can be retrieved from the `ListWorkitemTypeFields` operation. The `value` is the content to assign to the field. For example: `{"priority":"888853d622cc8eae793e085e27"}`.	{"priority":"888853d622cc8eae793e085e27"}
description	string	body	No	The description of the work item.	Description test
formatType	string	body	No	The format of the description. Valid values: `RICHTEXT` (rich text, default) and `MARKDOWN`.	RICHTEXT
labels	array[string]	body	No	An array of associated label IDs.	f2f52de5cac7656371fba2****
operatorId	string	body	No	This parameter is ignored when authenticating with a personal access token.	674d96abd497cd558d68****
parentId	string	body	No	The ID of the parent work item.	beda1775d1c3eca7dbdff5****
participants	array[string]	body	No	An array of user IDs for the participants.	674d96abd497cd558d68****
spaceId	string	body	Yes	The ID of the space. If the work item belongs to a project, this is the project ID.	bfbb5f44f3aaab11460cd1****
sprint	string	body	No	The ID of the associated sprint.	1c0d8bc0115fdf76bc33ac****
subject	string	body	Yes	The title of the work item.	Subject test
trackers	array[string]	body	No	An array of user IDs for the followers.	674d96abd497cd558d68****
verifier	string	body	No	The user ID of the verifier.	674d96abd497cd558d68****
versions	array[string]	body	No	An array of associated version IDs.	bfbb5f44f3aaab11460cd1****
workitemTypeId	string	body	Yes	The ID of the work item type. You can get this ID from the `ListWorkitemTypes` operation.	bca48ee2a0976d38f48****

Request examples

Central edition

curl -X 'POST' \
  'https://{domain}/oapi/v1/projex/organizations/{organizationId}/workitems' \
  -H 'Content-Type: application/json' \
  -H 'x-yunxiao-token: pt-0fh3****0fbG_35af****0484' \
  --data '
    {
        "assignedTo": "674d96abd497cd558d68****",
        "customFieldValues": {
            "priority": "888853d622cc8eae793e085e27"
        },
        "description": "Description test",
        "formatType": "RICHTEXT",
        "labels": ["f2f52de5cac7656371fba2****"],
        "operatorId": "674d96abd497cd558d68****",
        "parentId": "beda1775d1c3eca7dbdff5****",
        "participants": ["674d96abd497cd558d68****"],
        "spaceId": "bfbb5f44f3aaab11460cd1****",
        "sprint": "1c0d8bc0115fdf76bc33ac****",
        "subject": "Subject test",
        "trackers": ["674d96abd497cd558d68****"],
        "verifier": "674d96abd497cd558d68****",
        "versions": ["bfbb5f44f3aaab11460cd1****"],
        "workitemTypeId": "bca48ee2a0976d38f48****"
    }'

Region edition

curl -X 'POST' \
  'https://{domain}/oapi/v1/projex/workitems' \
  -H 'Content-Type: application/json' \
  -H 'x-yunxiao-token: pt-0fh3****0fbG_35af****0484' \
  --data '
    {
        "assignedTo": "674d96abd497cd558d68****",
        "customFieldValues": {
            "priority": "888853d622cc8eae793e085e27"
        },
        "description": "Description test",
        "formatType": "RICHTEXT",
        "labels": ["f2f52de5cac7656371fba2****"],
        "operatorId": "674d96abd497cd558d68****",
        "parentId": "beda1775d1c3eca7dbdff5****",
        "participants": ["674d96abd497cd558d68****"],
        "spaceId": "bfbb5f44f3aaab11460cd1****",
        "sprint": "1c0d8bc0115fdf76bc33ac****",
        "subject": "Subject test",
        "trackers": ["674d96abd497cd558d68****"],
        "verifier": "674d96abd497cd558d68****",
        "versions": ["bfbb5f44f3aaab11460cd1****"],
        "workitemTypeId": "bca48ee2a0976d38f48****"
    }'

Response parameters

Parameter	Type	Description	Example
-	object	The response body.
id	string	The ID of the work item.	id-xxx

Response example

{
    "id": "id-xxx"
}

Error codes

For a list of API error codes, see the Error Code Center.