Delete a topic
This endpoint is only available to organization administrators.
POST https://pcmi22.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://pcmi22.zulipchat.com/api/v1/streams/1/delete_topic \
-u BOT_EMAIL_ADDRESS:BOT_API_KEY \
--data-urlencode 'topic_name=new coffee machine'
Parameters
stream_id integer required in path
Example: 1
The ID of the channel to access.
topic_name string required
Example: "new coffee machine"
The name of the topic to delete.
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"
}