Delete a topic

POST https://connect.xfel.eu/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.

Changes: Before Zulip 6.0 (feature level 147), this request did a single atomic operation, which could time out for very large topics. It now deletes messages in batches, starting with the newest messages, so that progress will be made even if the request times out.

As of feature level 154, in case of timeout, a success response with "partially_completed" result will now be returned.

Usage examples

#!/usr/bin/env python3

import zulip

# Pass the path to your zuliprc file here.
client = zulip.Client(config_file="~/zuliprc")

# 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://connect.xfel.eu/api/v1/streams/1/delete_topic \
    -u BOT_EMAIL_ADDRESS:BOT_API_KEY \
    --data-urlencode 'topic_name=new coffee machine'

Parameters

Response

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:

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

If the request exceeds its processing time limit after having successfully marked some messages as read, response code 200 with result "partially_completed" and code "REQUEST_TIMEOUT" will be returned like this:

{
    "code": "REQUEST_TIMEOUT",
    "msg": "",
    "result": "partially_completed"
}

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"
}