Delete a topic

POST https://hacspec.zulipchat.com/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 9.0 (feature level 256), the server never sent stream op: update events with an updated first_message_id for a channel when the oldest message that had been sent to it changed.

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 in a channel, given the channel's 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://hacspec.zulipchat.com/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"
}