Delete a topic

POST https://cs-a1111-2023s.zulip.aalto.fi/api/v1/streams/{stream_id}/delete_topic

Delete all messages in a topic.

Topics are a field on messages (not an independent data structure), so deleting all the messages in the topic deletes the topic from Zulip.

Because this endpoint deletes messages in batches, it is possible for the request to time out after only deleting some messages in the topic. When this happens, the complete boolean field in the success response will be false. Clients should repeat the request when handling such a response. If all messages in the topic were deleted, then the success response will return "complete": true.

Changes: Before Zulip 8.0 (feature level 211), if the server's processing was interrupted by a timeout, but some messages in the topic were deleted, then it would return "result": "partially_completed", along with a code field for an error string, in the success response to indicate that there was a timeout and that the client should repeat the request.

As of Zulip 6.0 (feature level 154), instead of returning an error response when a request times out after successfully deleting some of the messages in the topic, a success response is returned with "result": "partially_completed" to indicate that some messages were deleted.

Before Zulip 6.0 (feature level 147), this request did a single atomic operation, which could time out for very large topics. As of this feature level, messages are deleted in batches, starting with the newest messages, so that progress is made even if the request times out and returns an error.

Usage examples

#!/usr/bin/env python

import zulip

# The user for this zuliprc file must be an organization administrator
client = zulip.Client(config_file="~/zuliprc-admin")

# Delete a topic given its stream_id
request = {
    "topic_name": topic,
}
result = client.call_endpoint(
    url=f"/streams/{stream_id}/delete_topic", method="POST", request=request
)
print(result)

curl -sSX POST https://cs-a1111-2023s.zulip.aalto.fi/api/v1/streams/1/delete_topic \
    -u BOT_EMAIL_ADDRESS:BOT_API_KEY \
    --data-urlencode 'topic_name=new coffee machine'

Parameters

Response

Return values

• complete: boolean

  Whether all unread messages were marked as read.

  Will be false if the request successfully marked some, but not all, messages as read.

Example response(s)

Changes: As of Zulip 7.0 (feature level 167), if any parameters sent in the request are not supported by this endpoint, a successful JSON response will include an ignored_parameters_unsupported array.

A typical successful JSON response may look like:

{
    "complete": true,
    "msg": "",
    "result": "success"
}

Error when the user does not have permission to delete topics in this organization:

{
    "code": "UNAUTHORIZED_PRINCIPAL",
    "msg": "Must be an organization administrator",
    "result": "error"
}