Help Center/ Distributed Message Service for Kafka/ API Reference/ APIs V2 (Recommended)/ Lifecycle Management/ Modifying Instance Information
Updated on 2026-03-16 GMT+08:00
View PDF

Modifying Instance Information

Function

This API is used to modify the instance information.

Calling Method

For details, see Calling APIs.

URI

PUT /v2/{project_id}/instances/{instance_id}

Table 1 Path Parameters

Parameter

Mandatory

Type

Description

project_id

Yes

String

Project ID. For details about how to obtain it, see Obtaining a Project ID.

instance_id

Yes

String

Instance ID.

Request Parameters

Table 2 Request body parameters

Parameter

Mandatory

Type

Description

name

No

String

Instance name.

An instance name starts with a letter, consists of 4 to 64 characters, and can contain only letters, digits, underscores (_), and hyphens (-).

description

No

String

Description of an instance.

The description supports up to 1024 characters.

NOTE:
The backslash (\) and quotation mark (") are special characters for JSON messages. When using these characters in a parameter value, add the escape character (\) before the characters, for example, \ and ".

maintain_begin

No

String

Time at which the maintenance window starts. The format is HH:mm:ss.

maintain_end

No

String

Time at which the maintenance window ends. The format is HH:mm:ss.

security_group_id

No

String

Security group ID.

To obtain the security group ID, call the API for querying the security group list by referring to Virtual Private Cloud API Reference.

retention_policy

No

String

Capacity threshold policy.

Options:

  • produce_reject: New messages cannot be created.

  • time_base: The earliest messages are deleted.

enterprise_project_id

No

String

Enterprise project.

Response Parameters

Status code: 204

The instance information is modified successfully.

None

Example Requests

  • Modifying the name and description of an instance.

    PUT https://{endpoint}/v2/{project_id}/instances/{instance_id}

{
  "name" : "kafka001",
  "description" : "kafka description"
}

  • Modifying the name, description, and maintenance time window of an instance.

    PUT https://{endpoint}/v2/{project_id}/instances/{instance_id}

{
  "name" : "dms002",
  "description" : "instance description",
  "maintain_begin" : "02:00:00",
  "maintain_end" : "06:00:00"
}

  • Changing the capacity threshold policy.

    PUT https://{endpoint}/v2/{project_id}/instances/{instance_id}

{
  "retention_policy" : "time_base"
}

Example Responses

None

Status Codes

Status Code

Description

204

The instance information is modified successfully.

Error Codes

See Error Codes.

Parent Topic: Lifecycle Management