UpdateProject,更新项目-Alibaba Cloud DevOps(Alibaba Cloud DevOps)-阿里云帮助中心

The OpenAPI request body is a JSON object that maps field IDs to string values. Omitted fields remain unchanged. You can submit status together with other fields.

Basic fields

The following fields can be submitted directly by field name without calling GetProjectFieldConfig.

Field ID	Value type	Description and constraints	Example
name	string	The project name. It must be non-empty and contain fewer than 128 characters.	`"Release project"`
description	string	The project description. It can contain up to 10,000 characters. An empty string clears the value.	`"Release plan for this quarter"`
customCode	string	The project code prefix. It must contain 4 to 6 uppercase letters and be unique within the organization. It cannot be cleared with an empty string.	`"DEMO"`
scope	string	The visibility scope. Valid values are `public` or `private`	`"private"`
status	string	The target business status ID. Do not specify a status name, stage ID, or archived flag. The value cannot be empty and must conform to the project workflow. You cannot change the status of an archived project.	`"<target status ID>"`

Omit fields that you do not want to change. Do not pass null. logicalStatus, statusIdentifier, creator, gmtCreate and other response fields are not updatable fields for this operation. Status and archiving are different concepts. The status field of this operation does not archive or activate a project.

Custom fields

Call GetProjectFieldConfig: use the following endpoint under the same version prefix: GET /projects/{id}/fields. This operation returns the custom fields configured for the project and excludes the five basic fields in the preceding table. If no fields are configured, it returns an empty array without affecting basic field updates. It returns field configurations, not current field values. Call GetProject to query current values. Each field includes id, name, className, format, required and options. Use the field id as the key in the UpdateProject request body. Do not use the field name.

Rules for custom field values

All values remain JSON strings. The following rules are consistent with current UpdateProject validation:

className / configuration	Value format	Example
date	yyyy-MM-dd	`"2026-10-01"`
dateTime	yyyy-MM-dd HH:mm:ss	`"2026-10-01 09:00:00"`
user	A user ID. Separate multiple users with commas. All IDs must be valid.	`"<user ID 1>,<user ID 2>"`
int	An integer string	`"3"`
float	A numeric string	`"1.5"`
Other types with non-empty options	An exact match for `options.value`, not options.id or displayValue	`"high"`
Other types without options	A string that follows the field constraints	`"Description text"`

If required=true for a configured field, you cannot submit a blank value. For an optional field, submit an empty string to clear it. format=multiList does not mean that this operation accepts a JSON array or comma-separated regular options. Current option validation accepts only one options.value. The comma-separated rule applies separately to user fields. This change does not extend the write protocol for regular multi-select options. If both the project start date startDate_proj and end date endDate_proj are specified, the start date cannot be later than the end date. The fields must exist in the project configuration.

Examples

Update only the name and visibility scope:

{"name":"Release project","scope":"private"}

Assume that the field query returns id=priority-field, its options contain value=high, and the date field ID is startDate_proj:

{"priority-field":"high","startDate_proj":"2026-10-01"}

Obtain the target status: Call ListProjectNextStatuses under the same version prefix: GET /projects/{id}/statuses:next. It returns the statuses to which the current status can transition, including id, name. For an archived project, an empty list is returned. Select a returned ID and update the project:

{"status":"<target status ID>"}

Obtain the current status from status.id returned by GetProject. Resubmitting the current status follows the existing transition logic and does not generate duplicate status events. The workflow may change between query and update. Validation at update time takes precedence.

Update the name, a configured field, and the status together. Replace the field and status IDs with actual query results:

{"name":"Release project","priority-field":"high","status":"<target status ID>"}

For a mixed request, the operation first validates field values and the target status, and then updates basic fields, configured fields, and the status in sequence. The workflow is checked again when the status is updated. Field persistence spans services, so atomic rollback of the entire request is not guaranteed. A service failure during execution or a concurrent workflow change may result in a partial update. If the request fails, call GetProject to read the current fields and status before deciding whether to retry.

Common failure causes

You do not have permission to manage project basic settings, or the token does not have write permission for Project Collaboration.
The field ID is not in the supported list or the target project configuration.
A required configured field is empty, a date or number has an invalid format, a user ID is invalid, or an option value does not match.
status is empty, does not exist, is not a currently available transition, or the project is archived.

Applicable editions

Central edition, Region edition

Endpoints and authorization information

Get the endpoint: Replace {domain} in the API request syntax.
Obtain a personal access token。
Obtain an organization ID:Required only for the Central edition. Go to theorganization management consoleand obtain the organization ID from thebasic informationpage.

Product	Resource	Required permission
Project Collaboration	Project	Read/write

Request syntax

Central edition

PUT https://{domain}/oapi/v1/projex/organizations/{organizationId}/projects/{id}

Region edition

PUT https://{domain}/oapi/v1/projex/projects/{id}

Request headers

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

Request parameters

Parameter	Type	Location	Required	Description	Example value
id	string	path	Yes	Unique project identifier.	589c53d622cc8521793e08****
organizationId	string	path	Yes: Central edition No: Region edition	Organization ID.
-	object	body	No	Update by field ID. Query configured fields by calling GetProjectFieldConfig. All values are strings. You can submit status together with other fields.
customCode	string	body	No	The project code prefix. It must contain 4 to 6 uppercase letters, be unique within the organization, and cannot be cleared.	DEMO
description	string	body	No	The project description. It can contain up to 10,000 characters. An empty string clears it.	Release plan
name	string	body	No	The project name. It must be non-empty and contain fewer than 128 characters.	Release project
scope	string	body	No	The project visibility scope. Valid values: public and private.	private
status	string	body	No	The target status ID, obtained by calling ListProjectNextStatuses. A status name or stage ID is not accepted. The value cannot be empty. Archived projects cannot be modified.	<target status ID>

Request examples

Central edition

curl -X 'PUT' \
  'https://{domain}/oapi/v1/projex/organizations/{organizationId}/projects/589c53d622cc8521793e08****' \
  -H 'Content-Type: application/json' \
  -H 'x-yunxiao-token: pt-0fh3****0fbG_35af****0484' \
  --data '
    {
        "customCode": "DEMO",
        "description": "Release plan",
        "name": "Release project",
        "scope": "private",
        "status": "<target status ID>"
    }'

Region edition

curl -X 'PUT' \
  'https://{domain}/oapi/v1/projex/projects/589c53d622cc8521793e08****' \
  -H 'Content-Type: application/json' \
  -H 'x-yunxiao-token: pt-0fh3****0fbG_35af****0484' \
  --data '
    {
        "customCode": "DEMO",
        "description": "Release plan",
        "name": "Release project",
        "scope": "private",
        "status": "<target status ID>"
    }'

Response parameters

None

Error codes

Visit the Error Code Center to view API error codes.