Help Center/ Distributed Message Service for RocketMQ/ API Reference/ APIs V2 (Recommended)/ Topic Management/ Modifying a Topic
Updated on 2026-04-30 GMT+08:00
View PDF

Modifying a Topic

Function

This API is used to modify a topic.

URI

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

Table 1 Path Parameters

Parameter

Mandatory

Type

Description

project_id

Yes

String

Definition

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

Constraints

N/A

Range

N/A

Default Value

N/A

instance_id

Yes

String

Definition

Instance ID. You can call the API for querying all instances to obtain the instance ID. The instance ID is in the response body.

Constraints

N/A

Range

N/A

Default Value

N/A

topic

Yes

String

Definition

Topic name.

Constraints

N/A

Range

N/A

Default Value

N/A

Request Parameters

Table 2 Request body parameters

Parameter

Mandatory

Type

Description

read_queue_num

No

Number

Definition

Total number of read queues.

Constraints

This parameter can be modified only for version 4.8.0 instances. This parameter is valid only when parameter queues is left blank.

Range

The value must be greater than or equal to the number of brokers associated with the topic.

Default Value

3

write_queue_num

No

Number

Definition

Total number of write queues.

Constraints

This parameter can be modified only for version 4.8.0 instances. This parameter is valid only when parameter queues is left blank.

Range

The value must be greater than or equal to the number of brokers associated with the topic.

Default Value

3

permission

No

String

Definition

Permission.

Constraints

This parameter can be modified only for v4.8.0 instances.

Range

N/A

Default Value

N/A

queues

No

Array of UpdateTopicQueueEntity objects

Definition

Queue.

Constraints

This parameter can be modified only for v4.8.0 instances.

Range

N/A

Default Value

N/A

topic_desc

No

String

Definition:

Topic description.

Constraints:

N/A

Range:

N/A

Default Value:

N/A
Table 3 UpdateTopicQueueEntity

Parameter

Mandatory

Type

Description

broker

No

String

Definition:

Broker name.

Constraints:

N/A

Range:

N/A

Default Value:

N/A

read_queue_num

No

Number

Definition

Number of read queues.

Constraints

N/A

Range

≥ 0

Default Value

3

write_queue_num

No

Number

Definition

Number of write queues.

Constraints

N/A

Range

≥ 0

Default Value

3

Response Parameters

Status code: 204

The topic is modified.

None

Example Requests

Changing a specified topic's total read queues to 3 and total write queues to 3

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

{
  "permission" : "all",
  "queues" : [ {
    "broker" : "broker-0",
    "read_queue_num" : 3,
    "write_queue_num" : 3
  } ],
  "topic_desc" : "topic_description"
}

Example Responses

None

Status Codes

Status Code

Description

204

The topic is modified.

Error Codes

See Error Codes.

Parent Topic: Topic Management