Upload a file

POST https://hulk.zulipchat.com/api/v1/user_uploads

Upload a single file and get the corresponding URL.

Initially, only you will be able to access the link. To share the uploaded file, you'll need to send a message containing the resulting link. Users who can already access the link can reshare it with other users by sending additional Zulip messages containing the link.

For uploading larger files, /api/v1/tus is an endpoint implementing the tus protocol for resumable uploads. Clients which send authenticated credentials (either via browser-based cookies, or API key via Authorization header) may use this endpoint to create uploads.

Usage examples

#!/usr/bin/env python3

import zulip

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

# Upload a file.
with open(path_to_file, "rb") as fp:
    result = client.upload_file(fp)
# Share the file by including it in a message.
client.send_message(
    {
        "type": "stream",
        "to": "Denmark",
        "topic": "Castle",
        "content": "Check out [this picture]({}) of my castle!".format(result["url"]),
    }
)
print(result)

curl -sSX POST https://hulk.zulipchat.com/api/v1/user_uploads \
    -u BOT_EMAIL_ADDRESS:BOT_API_KEY \
    -F filename=@/path/to/file

Parameters

As described above, the file to upload must be provided in the request's body.

Maximum file size

The maximum file size for uploads can be configured by the administrator of the Zulip server by setting MAX_FILE_UPLOAD_SIZE in the server's settings. MAX_FILE_UPLOAD_SIZE defaults to 100MB.

Response

Return values

• uri: string

  The URL of the uploaded file. Alias of url.

  Changes: Deprecated in Zulip 9.0 (feature level 272). The term "URI" is deprecated in web standards.

• url: string

  The URL of the uploaded file.

  Changes: New in Zulip 9.0 (feature level 272). Previously, this property was only available under the legacy uri name.

• filename: string

  The filename that Zulip stored the upload as. This usually differs from the basename of the URL when HTML escaping is required to generate a valid URL.

  Clients generating a Markdown link to a newly uploaded file should do so by combining the url and filename fields in the response as follows: [{filename}]({url}), with care taken to clean filename of [ and ] characters that might break Markdown rendering.

  Changes: New in Zulip 10.0 (feature level 285).

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:

{
    "filename": "zulip.txt",
    "msg": "",
    "result": "success",
    "uri": "/user_uploads/1/4e/m2A3MSqFnWRLUf9SaPzQ0Up_/zulip.txt",
    "url": "/user_uploads/1/4e/m2A3MSqFnWRLUf9SaPzQ0Up_/zulip.txt"
}