All Products
Document Center

Topic APIs

Last Updated: Oct 08, 2019



This API is used to create a new topic.

A topic name is a string of no more than 256 characters, including letters, numbers, and hyphens (-). It must start with a letter or number.


A request mainly includes the following parts:

  • Request line

    PUT /topics/$TopicName HTTP/1.1

  • Special Request Header

    None. For details, refer to Call method/Public parameters.

  • Request Body

    The request body is in XML format and contains the created topic attributes.

Parameter name Description Parameter value Required/Optional
MaximumMessageSize Maximum body length of a message sent to the topic, in the unit of bytes An integer in the range of 1,024 (1 KB) to 65, 536 (64 KB); default value: 65,536 (64 KB) Optional
LoggingEnabled Whether to enable log management. “True” indicates that log management is enabled, whereas “False” indicates that log management is disabled. True/False; default value: False Optional


The returned message includes three parts: return status line, HTTP header, and message body.

  • HTTP Status Code

    HTTP/1.1 201 Created

    Duplicate topic names are not allowed for the same owner in the same region. If the created topic has the same name and attributes as an existing topic, Status Code 204 (No Content) is returned; if only the names are the same but the attributes are different, Status Code 409 (Conflict) is returned.

  • Special Response Header

Parameter name Description
Location URL of the created topic, in the following format: http://$AccountId.mns.<Region>$TopicName

For the other response headers, refer to Call Method/Public Parameters.

  • Response Body


Special error

Error code Error message Status code
TopicAlreadyExist The topic you want to create is already exists. 409
TopicNameLengthError Topic name length is out of range, should be between 1 and 256. 400

Request example:

  1. PUT /topics/$TopicName HTTP/1.1
  2. Host: $
  3. Date: Tue, 08 Dec 2015 05:57:57 GMT
  4. x-mns-version: 2015-06-06
  5. Authorization:MNS 15B4D3461F177624206A:eCtaUwfGS0oEfznzJEhWFxpf2yk=
  6. <?xml version="1.0" encoding="utf-8"?>
  7. <Topic xmlns="">
  8. <MaximumMessageSize>10240</MaximumMessageSize>
  9. <LoggingEnabled>True</LoggingEnabled>
  10. </Topic>

Response example:

  1. HTTP/1.1 201 Created
  2. x-mns-request-id:56667165B2B71C9C16000013
  3. x-mns-version: 2015-06-06
  4. Location: http://$$TopicName