{ "opencollection": "1.0.0", "info": { "name": "Zulip REST API", "version": "1.0.0" }, "items": [ { "info": { "name": "authentication", "type": "folder" }, "items": [ { "info": { "name": "Fetch an API key (production)", "type": "http" }, "http": { "method": "POST", "url": "https://{subdomain}.zulipchat.com/api/v1/fetch_api_key", "body": { "type": "form-urlencoded", "data": [ { "name": "username", "value": "" }, { "name": "password", "value": "" } ] } }, "docs": "This API endpoint is used by clients such as the Zulip mobile and\nterminal apps to implement password-based authentication. Given the\nuser's Zulip login credentials, it returns a Zulip API key that the client\ncan use to make requests as the user.\n\nThis endpoint is only useful for Zulip servers/organizations with\nEmailAuthBackend or LDAPAuthBackend enabled.\n\nThe Zulip mobile apps also support SSO/social authentication (GitHub\nauth, Google auth, SAML, etc.) that does not use this endpoint. Instead" }, { "info": { "name": "Fetch an API key (JWT)", "type": "http" }, "http": { "method": "POST", "url": "https://{subdomain}.zulipchat.com/api/v1/jwt/fetch_api_key", "body": { "type": "form-urlencoded", "data": [ { "name": "token", "value": "" }, { "name": "include_profile", "value": "" } ] } }, "docs": "This API endpoint is used by clients to implement JSON Web Token\n(JWT) authentication. Given a JWT identifying a Zulip user, it\nreturns a Zulip API key that the client can use to make requests\nas the user.\n\n!!! warn \"\"\n\n **Note:** This endpoint is only useful for Zulip servers/organizations\n with [JSON web token authentication][prod-jwt-auth] enabled.\n\nSee the [API keys](/api/api-keys) documentation for more details\non how to manage API keys manually.\n\n**Changes**: New in Zulip 7.0 (featur" }, { "info": { "name": "Fetch an API key (development only)", "type": "http" }, "http": { "method": "POST", "url": "https://{subdomain}.zulipchat.com/api/v1/dev_fetch_api_key", "body": { "type": "form-urlencoded", "data": [ { "name": "username", "value": "" } ] } }, "docs": "For easy testing of mobile apps and other clients and against Zulip\ndevelopment servers, we support fetching a Zulip API key for any user\non the development server without authentication (so that they can\nimplement analogues of the one-click login process available for Zulip\ndevelopment servers on the web).\n\n!!! warn \"\"\n\n **Note:** This endpoint is only available on Zulip development\n servers; for obvious security reasons it will always return an error\n in a Zulip production server.\n" }, { "info": { "name": "List users (development only)", "type": "http" }, "http": { "method": "GET", "url": "https://{subdomain}.zulipchat.com/api/v1/dev_list_users" }, "docs": "Get a list of all, non-bot users in a [Zulip development\nserver](https://zulip.readthedocs.io/en/latest/development/overview.html).\nThis endpoint is used by mobile developers to fetch users for the\ndevelopment login flow.\n\n!!! warn \"\"\n\n **Note:** This endpoint is only available on Zulip development\n servers; for obvious security reasons it will always return an error\n in a Zulip production server.\n" } ] }, { "info": { "name": "real_time_events", "type": "folder" }, "items": [ { "info": { "name": "Get events from an event queue", "type": "http" }, "http": { "method": "GET", "url": "https://{subdomain}.zulipchat.com/api/v1/events", "params": [ { "name": "queue_id", "value": "fb67bf8a-c031-47cc-84cf-ed80accacda8", "type": "query", "description": "The ID of an event queue that was previously registered via\n`POST /api/v1/register` (see [Register a queue](/api/register-queue)).\n" }, { "name": "last_event_id", "value": "-1", "type": "query", "description": "The highest event ID in this queue that you've received and\nwish to acknowledge. See the [code for\n`call_on_each_event`](https://github.com/zulip/python-zulip-api/blob/main/zulip/zulip/__init__.py)\nin the [zulip Python\nmodule](https://github.com/zulip/python-zulip-api) for an\nexample implementation of correctly processing each event\nexactly once.\n" }, { "name": "dont_block", "value": "true", "type": "query", "description": "Set to `true` if the client is requesting a nonblocking reply. If not\nspecified, the request will block until either a new event is available\nor a few minutes have passed, in which case the server will send the\nclient a heartbeat event.\n" } ] }, "docs": "This endpoint allows you to receive new events from\n[a registered event queue](/api/register-queue).\n\nLong-lived clients should use the\n`event_queue_longpoll_timeout_seconds` property returned by\n`POST /register` as the client-side HTTP request timeout for\ncalls to this endpoint. It is guaranteed to be higher than\nheartbeat timeout and should be respected by clients to\navoid breaking when heartbeat timeout increases.\n" }, { "info": { "name": "Delete an event queue", "type": "http" }, "http": { "method": "DELETE", "url": "https://{subdomain}.zulipchat.com/api/v1/events", "body": { "type": "form-urlencoded", "data": [ { "name": "queue_id", "value": "" } ] } }, "docs": "Delete a previously registered queue.\n" }, { "info": { "name": "Register an event queue", "type": "http" }, "http": { "method": "POST", "url": "https://{subdomain}.zulipchat.com/api/v1/register", "body": { "type": "form-urlencoded", "data": [ { "name": "apply_markdown", "value": "" }, { "name": "client_gravatar", "value": "" }, { "name": "include_subscribers", "value": "" }, { "name": "slim_presence", "value": "" }, { "name": "presence_history_limit_days", "value": "" }, { "name": "event_types", "value": "" }, { "name": "all_public_streams", "value": "" }, { "name": "client_capabilities", "value": "" }, { "name": "fetch_event_types", "value": "" }, { "name": "narrow", "value": "" }, { "name": "idle_queue_timeout", "value": "" } ] } }, "docs": "This powerful endpoint can be used to register a Zulip \"event queue\"\n(subscribed to certain types of \"events\", or updates to the messages\nand other Zulip data the current user has access to), as well as to\nfetch the current state of that data.\n\n(`register` also powers the `call_on_each_event` Python API, and is\nintended primarily for complex applications for which the more convenient\n`call_on_each_event` API is insufficient).\n\nThis endpoint returns a `queue_id` and a `last_event_id`; these can b" }, { "info": { "name": "POST /real-time", "type": "http" }, "http": { "method": "POST", "url": "https://{subdomain}.zulipchat.com/api/v1/real-time", "body": { "type": "form-urlencoded", "data": [ { "name": "event_types", "value": "" }, { "name": "narrow", "value": "" }, { "name": "all_public_streams", "value": "" } ] } }, "docs": "(Ignored)\n" }, { "info": { "name": "Error handling", "type": "http" }, "http": { "method": "POST", "url": "https://{subdomain}.zulipchat.com/api/v1/rest-error-handling" }, "docs": "Common error to many endpoints\n" } ] }, { "info": { "name": "channels", "type": "folder" }, "items": [ { "info": { "name": "Get channel ID", "type": "http" }, "http": { "method": "GET", "url": "https://{subdomain}.zulipchat.com/api/v1/get_stream_id", "params": [ { "name": "stream", "value": "Denmark", "type": "query", "description": "The name of the channel to access.\n" } ] }, "docs": "Get the unique ID of a given channel.\n" }, { "info": { "name": "Add a default channel", "type": "http" }, "http": { "method": "POST", "url": "https://{subdomain}.zulipchat.com/api/v1/default_streams", "body": { "type": "form-urlencoded", "data": [ { "name": "stream_id", "value": "" } ] } }, "docs": "Add a channel to the set of [default channels][default-channels]\nfor new users joining the organization.\n\n[default-channels]: /help/set-default-channels-for-new-users\n" }, { "info": { "name": "Remove a default channel", "type": "http" }, "http": { "method": "DELETE", "url": "https://{subdomain}.zulipchat.com/api/v1/default_streams", "body": { "type": "form-urlencoded", "data": [ { "name": "stream_id", "value": "" } ] } }, "docs": "Remove a channel from the set of [default channels][default-channels]\nfor new users joining the organization.\n\n[default-channels]: /help/set-default-channels-for-new-users\n" }, { "info": { "name": "Get topics in a channel", "type": "http" }, "http": { "method": "GET", "url": "https://{subdomain}.zulipchat.com/api/v1/users/me/:stream_id/topics", "params": [ { "name": "stream_id", "value": "1", "type": "path", "description": "The ID of the channel to access.\n" }, { "name": "allow_empty_topic_name", "value": "true", "type": "query", "description": "Whether the client supports processing the empty string as\na topic name in the returned data.\n\nIf `false`, the value of `realm_empty_topic_display_name`\nfound in the [`POST /register`](/api/register-queue) response is\nreturned replacing the empty string as the topic name.\n\n**Changes**: New in Zulip 10.0 (feature level 334). Previously,\nthe empty string was not a valid topic.\n" } ] }, "docs": "Get all topics the user has access to in a specific channel.\n\nNote that for [private channels with\nprotected history](/help/channel-permissions#private-channels),\nthe user will only have access to topics of messages sent after they\n[subscribed to](/api/subscribe) the channel. Similarly, a user's\n[bot](/help/bots-overview#bot-type) will only have access to messages\nsent after the bot was subscribed to the channel, instead of when the\nuser subscribed.\n\n**Changes**: Before Zulip 12.0 (feature level" }, { "info": { "name": "Get subscribed channels", "type": "http" }, "http": { "method": "GET", "url": "https://{subdomain}.zulipchat.com/api/v1/users/me/subscriptions", "params": [ { "name": "include_subscribers", "value": "true", "type": "query", "description": "Whether each returned channel object should include a `subscribers`\nfield containing a list of the user IDs of its subscribers.\n\nClient apps supporting organizations with many thousands of users\nshould not pass `true`, because the full subscriber matrix may be\nseveral megabytes of data. The `partial` value, combined with the\n`subscriber_count` and fetching subscribers for individual channels as\nneeded, is recommended to support client app features where\nchannel subscriber data is useful.\n\nIf a client passes `partial` for this parameter, the server may,\nfor some channels, return a subset of the channel's subscribers\nin the `partial_subscribers` field instead of the `subscribers` field,\nwhich always contains the complete set of subscribers.\n\nThe server guarantees that it will always return a `subscribers`\nfield for channels with fewer than 250 total subscribers. When\nreturning a `partial_subscribers` field, the server guarantees\nthat all bot users and users active within the last 14 days will\nbe included. For other cases, the server may use its discretion\nto determine which channels and users to include, balancing between\npayload size and usefulness of the data provided to the client.\n\n**Changes**: The `partial` value is new in Zulip 11.0 (feature level 412).\n\nNew in Zulip 2.1.0.\n" } ] }, "docs": "Get all channels that the user is subscribed to.\n" }, { "info": { "name": "Subscribe to a channel", "type": "http" }, "http": { "method": "POST", "url": "https://{subdomain}.zulipchat.com/api/v1/users/me/subscriptions", "body": { "type": "form-urlencoded", "data": [ { "name": "subscriptions", "value": "" }, { "name": "principals", "value": "" }, { "name": "authorization_errors_fatal", "value": "" }, { "name": "announce", "value": "" }, { "name": "invite_only", "value": "" }, { "name": "is_web_public", "value": "" }, { "name": "is_default_stream", "value": "" }, { "name": "history_public_to_subscribers", "value": "" }, { "name": "message_retention_days", "value": "" }, { "name": "topics_policy", "value": "" }, { "name": "can_add_subscribers_group", "value": "" }, { "name": "can_remove_subscribers_group", "value": "" }, { "name": "can_administer_channel_group", "value": "" }, { "name": "can_delete_any_message_group", "value": "" }, { "name": "can_delete_own_message_group", "value": "" }, { "name": "can_move_messages_out_of_channel_group", "value": "" }, { "name": "can_move_messages_within_channel_group", "value": "" }, { "name": "can_send_message_group", "value": "" }, { "name": "can_subscribe_group", "value": "" }, { "name": "can_resolve_topics_group", "value": "" }, { "name": "can_create_topic_group", "value": "" }, { "name": "folder_id", "value": "" }, { "name": "send_new_subscription_messages", "value": "" } ] } }, "docs": "Subscribe one or more users to one or more channels.\n\nIf any of the specified channels do not exist, they are automatically\ncreated. The initial [channel settings](/api/update-stream) will be determined\nby the optional parameters, like `invite_only`, detailed below.\n\nNote that the ability to subscribe oneself and/or other users\nto a specified channel depends on the [channel's permissions\nsettings](/help/channel-permissions).\n\n**Changes**: Before Zulip 10.0 (feature level 362),\nsubscriptions in a" }, { "info": { "name": "Update subscriptions", "type": "http" }, "http": { "method": "PATCH", "url": "https://{subdomain}.zulipchat.com/api/v1/users/me/subscriptions", "body": { "type": "form-urlencoded", "data": [ { "name": "delete", "value": "" }, { "name": "add", "value": "" } ] } }, "docs": "Update which channels you are subscribed to.\n\n**Changes**: Before Zulip 10.0 (feature level 362),\nsubscriptions in archived channels could not be modified.\n" }, { "info": { "name": "Unsubscribe from a channel", "type": "http" }, "http": { "method": "DELETE", "url": "https://{subdomain}.zulipchat.com/api/v1/users/me/subscriptions", "body": { "type": "form-urlencoded", "data": [ { "name": "subscriptions", "value": "" }, { "name": "principals", "value": "" } ] } }, "docs": "Unsubscribe yourself or other users from one or more channels.\n\nIn addition to managing the current user's subscriptions, this\nendpoint can be used to remove other users from channels. This\nis possible in 3 situations:\n\n- Organization administrators can remove any user from any\n channel.\n- Users can remove a bot that they own from any channel that\n the user [can access](/help/channel-permissions).\n- Users can unsubscribe any user from a channel if they [have\n access](/help/channel-permissions" }, { "info": { "name": "Topic muting", "type": "http" }, "http": { "method": "PATCH", "url": "https://{subdomain}.zulipchat.com/api/v1/users/me/subscriptions/muted_topics", "body": { "type": "form-urlencoded", "data": [ { "name": "stream_id", "value": "" }, { "name": "stream", "value": "" }, { "name": "topic", "value": "" }, { "name": "op", "value": "" } ] } }, "docs": "[Mute or unmute a topic](/help/mute-a-topic) within a channel that\nthe current user is subscribed to.\n\n**Changes**: Deprecated in Zulip 7.0 (feature level 170). Clients connecting\nto newer servers should use the [POST /user_topics](/api/update-user-topic)\nendpoint, as this endpoint may be removed in a future release.\n\nBefore Zulip 7.0 (feature level 169), this endpoint\nreturned an error if asked to mute a topic that was already muted\nor asked to unmute a topic that had not previously been muted." }, { "info": { "name": "Update personal preferences for a topic", "type": "http" }, "http": { "method": "POST", "url": "https://{subdomain}.zulipchat.com/api/v1/user_topics", "body": { "type": "form-urlencoded", "data": [ { "name": "stream_id", "value": "" }, { "name": "topic", "value": "" }, { "name": "visibility_policy", "value": "" } ] } }, "docs": "This endpoint is used to update the personal preferences for a topic,\nsuch as the topic's visibility policy, which is used to implement\n[mute a topic](/help/mute-a-topic) and related features.\n\nThis endpoint can be used to update the visibility policy for the single\nchannel and topic pair indicated by the parameters for a user.\n\n**Changes**: New in Zulip 7.0 (feature level 170). Previously,\ntoggling whether a topic was muted or unmuted was managed by the\n[PATCH /users/me/subscriptions/muted_topi" }, { "info": { "name": "Get subscription status", "type": "http" }, "http": { "method": "GET", "url": "https://{subdomain}.zulipchat.com/api/v1/users/:user_id/subscriptions/:stream_id", "params": [ { "name": "user_id", "value": "12", "type": "path", "description": "The target user's ID.\n" }, { "name": "stream_id", "value": "1", "type": "path", "description": "The ID of the channel to access.\n" } ] }, "docs": "Check whether a user is subscribed to a channel.\n\n**Changes**: Prior to Zulip 12.0 (feature level 458), this endpoint\ndid not support querying subscriptions of bot users.\n\nNew in Zulip 3.0 (feature level 12).\n" }, { "info": { "name": "Get a user's subscribed channels", "type": "http" }, "http": { "method": "GET", "url": "https://{subdomain}.zulipchat.com/api/v1/users/:user_id/channels", "params": [ { "name": "user_id", "value": "12", "type": "path", "description": "The target user's ID.\n" } ] }, "docs": "Gets the list of channels that the target user is subscribed to.\n\nThe [channel security model](/help/channel-permissions) means only those\nsubscribed channels to which the acting user has metadata access are\nreturned.\n\nFor organization administrators, this is guaranteed to be all channels\nthe target user is subscribed to, since organization administrators\nimplicitly have metadata access to all channels.\n\n**Changes**: Prior to Zulip 12.0 (feature level 458), target users that\nwere bots resulted i" }, { "info": { "name": "Bulk update subscription settings", "type": "http" }, "http": { "method": "POST", "url": "https://{subdomain}.zulipchat.com/api/v1/users/me/subscriptions/properties", "body": { "type": "form-urlencoded", "data": [ { "name": "subscription_data", "value": "" } ] } }, "docs": "Update the current user's personal settings for channels they are\nsubscribed to. These settings include [color](/help/change-the-color-of-a-channel),\n[muting](/help/mute-a-channel), [pinning](/help/pin-a-channel)\nand [per-channel notification settings](/help/channel-notifications).\n\nThere is a single channel alternative to this bulk endpoint:\n[`POST /users/me/subscriptions/{stream_id}`](/api/update-subscription-property).\n\n**Changes**: Prior to Zulip 5.0 (feature level 111), the response object\n" }, { "info": { "name": "Update a subscription setting", "type": "http" }, "http": { "method": "PATCH", "url": "https://{subdomain}.zulipchat.com/api/v1/users/me/subscriptions/:stream_id", "params": [ { "name": "stream_id", "value": "1", "type": "path", "description": "The ID of the channel to access.\n" } ], "body": { "type": "form-urlencoded", "data": [ { "name": "property", "value": "" }, { "name": "value", "value": "" } ] } }, "docs": "Update the current user's personal settings for a specific channel they\nare subscribed to. These settings include [color](/help/change-the-color-of-a-channel),\n[muting](/help/mute-a-channel), [pinning](/help/pin-a-channel)\nand [per-channel notification settings](/help/channel-notifications).\n\nThis is a single channel alternative to the bulk endpoint:\n[`POST /users/me/subscriptions/properties`](/api/update-subscription-settings).\n" }, { "info": { "name": "Get channel subscribers", "type": "http" }, "http": { "method": "GET", "url": "https://{subdomain}.zulipchat.com/api/v1/streams/:stream_id/members", "params": [ { "name": "stream_id", "value": "1", "type": "path", "description": "The ID of the channel to access.\n" } ] }, "docs": "Get all users subscribed to a channel.\n\n**Changes**: Before Zulip 12.0 (feature level 480), this\nendpoint was not supported for archived channels.\n" }, { "info": { "name": "Get all channels", "type": "http" }, "http": { "method": "GET", "url": "https://{subdomain}.zulipchat.com/api/v1/streams", "params": [ { "name": "include_public", "value": "false", "type": "query", "description": "Include all public channels.\n" }, { "name": "include_web_public", "value": "true", "type": "query", "description": "Include all web-public channels.\n" }, { "name": "include_subscribed", "value": "false", "type": "query", "description": "Include all channels that the user is subscribed to.\n" }, { "name": "exclude_archived", "value": "true", "type": "query", "description": "Whether to exclude archived streams from the results.\n\n**Changes**: New in Zulip 10.0 (feature level 315).\n" }, { "name": "include_all_active", "value": "true", "type": "query", "description": "Deprecated parameter to include all channels. The user must\nhave administrative privileges to use this parameter.\n\n**Changes**: Deprecated in Zulip 10.0 (feature level\n356). Clients interacting with newer servers should use\nthe equivalent `include_all` parameter, which does not\nincorrectly hint that this parameter, and not\n`exclude_archived`, controls whether archived channels\nappear in the response.\n" }, { "name": "include_all", "value": "true", "type": "query", "description": "Include all channels that the user has metadata access to.\n\nFor organization administrators, this will be all channels\nin the organization, since organization administrators\nimplicitly have metadata access to all channels.\n\n**Changes**: New in Zulip 10.0 (feature level 356). On older\nversions, use `include_all_active`, which this replaces.\n" }, { "name": "include_default", "value": "true", "type": "query", "description": "Include all default channels for the user's realm.\n" }, { "name": "include_owner_subscribed", "value": "true", "type": "query", "description": "If the user is a bot, include all channels that the bot's owner is\nsubscribed to.\n" }, { "name": "include_can_access_content", "value": "true", "type": "query", "description": "Include all the channels that the user has content access to.\n\n**Changes**: New in Zulip 10.0 (feature level 356).\n" } ] }, "docs": "Get all channels that the user [has access to](/help/channel-permissions).\n" }, { "info": { "name": "Get a channel by ID", "type": "http" }, "http": { "method": "GET", "url": "https://{subdomain}.zulipchat.com/api/v1/streams/:stream_id", "params": [ { "name": "stream_id", "value": "1", "type": "path", "description": "The ID of the channel to access.\n" } ] }, "docs": "Fetch details for the channel with the ID `stream_id`.\n\n**Changes**: Before Zulip 12.0 (feature level 480), this\nendpoint was not supported for archived channels.\n\nNew in Zulip 6.0 (feature level 132).\n" }, { "info": { "name": "Update a channel", "type": "http" }, "http": { "method": "PATCH", "url": "https://{subdomain}.zulipchat.com/api/v1/streams/:stream_id", "params": [ { "name": "stream_id", "value": "1", "type": "path", "description": "The ID of the channel to access.\n" } ], "body": { "type": "form-urlencoded", "data": [ { "name": "description", "value": "" }, { "name": "new_name", "value": "" }, { "name": "is_private", "value": "" }, { "name": "is_web_public", "value": "" }, { "name": "history_public_to_subscribers", "value": "" }, { "name": "is_default_stream", "value": "" }, { "name": "message_retention_days", "value": "" }, { "name": "is_archived", "value": "" }, { "name": "folder_id", "value": "" }, { "name": "topics_policy", "value": "" }, { "name": "can_add_subscribers_group", "value": "" }, { "name": "can_remove_subscribers_group", "value": "" }, { "name": "can_administer_channel_group", "value": "" }, { "name": "can_delete_any_message_group", "value": "" }, { "name": "can_delete_own_message_group", "value": "" }, { "name": "can_move_messages_out_of_channel_group", "value": "" }, { "name": "can_move_messages_within_channel_group", "value": "" }, { "name": "can_send_message_group", "value": "" }, { "name": "can_subscribe_group", "value": "" }, { "name": "can_resolve_topics_group", "value": "" }, { "name": "can_create_topic_group", "value": "" } ] } }, "docs": "Configure the channel with the ID `stream_id`. This endpoint supports\nan organization administrator editing any property of a channel,\nincluding:\n\n- Channel [name](/help/rename-a-channel) and [description](/help/change-the-channel-description)\n- Channel [permissions](/help/channel-permissions), including\n [privacy](/help/change-the-privacy-of-a-channel) and [who can\n send](/help/channel-posting-policy).\n\nNote that an organization administrator's ability to change a\n[private channel's permissio" }, { "info": { "name": "Archive a channel", "type": "http" }, "http": { "method": "DELETE", "url": "https://{subdomain}.zulipchat.com/api/v1/streams/:stream_id", "params": [ { "name": "stream_id", "value": "1", "type": "path", "description": "The ID of the channel to access.\n" } ] }, "docs": "[Archive the channel](/help/archive-a-channel) with the ID `stream_id`.\n" }, { "info": { "name": "Get channel's email address", "type": "http" }, "http": { "method": "GET", "url": "https://{subdomain}.zulipchat.com/api/v1/streams/:stream_id/email_address", "params": [ { "name": "stream_id", "value": "1", "type": "path", "description": "The ID of the channel to access.\n" }, { "name": "sender_id", "value": "1", "type": "query", "description": "The ID of a user or bot which should appear as the sender when messages\nare sent to the channel using the returned channel email address.\n\n`sender_id` can be:\n\n- ID of the current user.\n- ID of the Email gateway bot. (Default value)\n- ID of a bot owned by the current user.\n\n**Changes**: New in Zulip 10.0 (feature level 335).\n\nPreviously, the sender was always Email gateway bot.\n" } ] }, "docs": "Get email address of a channel.\n\nNote that only users with permission to post messages in the channel\ncan access the channel's email address.\n\n**Changes**: Prior to Zulip 12.0 (feature level 448), users without\npermission to post messages in the channel could access the channel's email\nif they had metadata access.\n\nNew in Zulip 8.0 (feature level 226).\n" }, { "info": { "name": "Delete a topic", "type": "http" }, "http": { "method": "POST", "url": "https://{subdomain}.zulipchat.com/api/v1/streams/:stream_id/delete_topic", "params": [ { "name": "stream_id", "value": "1", "type": "path", "description": "The ID of the channel to access.\n" } ], "body": { "type": "form-urlencoded", "data": [ { "name": "topic_name", "value": "" } ] } }, "docs": "Delete all messages in a topic.\n\nTopics are a field on messages (not an independent data structure), so\ndeleting all the messages in the topic deletes the topic from Zulip.\n\nBecause this endpoint deletes messages in batches, it is possible for\nthe request to time out after only deleting some messages in the topic.\nWhen this happens, the `complete` boolean field in the success response\nwill be `false`. Clients should repeat the request when handling such a\nresponse. If all messages in the topic w" }, { "info": { "name": "Create a channel", "type": "http" }, "http": { "method": "POST", "url": "https://{subdomain}.zulipchat.com/api/v1/channels/create", "body": { "type": "form-urlencoded", "data": [ { "name": "name", "value": "" }, { "name": "description", "value": "" }, { "name": "subscribers", "value": "" }, { "name": "announce", "value": "" }, { "name": "invite_only", "value": "" }, { "name": "is_web_public", "value": "" }, { "name": "is_default_stream", "value": "" }, { "name": "folder_id", "value": "" }, { "name": "topics_policy", "value": "" }, { "name": "history_public_to_subscribers", "value": "" }, { "name": "message_retention_days", "value": "" }, { "name": "can_add_subscribers_group", "value": "" }, { "name": "can_create_topic_group", "value": "" }, { "name": "can_delete_any_message_group", "value": "" }, { "name": "can_delete_own_message_group", "value": "" }, { "name": "can_remove_subscribers_group", "value": "" }, { "name": "can_administer_channel_group", "value": "" }, { "name": "can_move_messages_out_of_channel_group", "value": "" }, { "name": "can_move_messages_within_channel_group", "value": "" }, { "name": "can_send_message_group", "value": "" }, { "name": "can_subscribe_group", "value": "" }, { "name": "can_resolve_topics_group", "value": "" } ] } }, "docs": "Create a new [channel](/help/create-channels), and optionally subscribe\nusers to the newly created channel.\n\nThe initial [channel settings](/api/update-stream) will be determined\nby the optional parameters, like `invite_only`, detailed below.\n\n**Changes**: New in Zulip 11.0 (feature level 417). Previously, this was\nonly possible via the [`POST /api/subscribe`](/api/subscribe) endpoint,\nwhich handles both channel subscription and creation.\n" }, { "info": { "name": "Create a channel folder", "type": "http" }, "http": { "method": "POST", "url": "https://{subdomain}.zulipchat.com/api/v1/channel_folders/create", "body": { "type": "form-urlencoded", "data": [ { "name": "name", "value": "" }, { "name": "description", "value": "" } ] } }, "docs": "Create a new [channel folder](/help/channel-folders).\n\n**Changes**: New in Zulip 11.0 (feature level 389).\n" }, { "info": { "name": "Get channel folders", "type": "http" }, "http": { "method": "GET", "url": "https://{subdomain}.zulipchat.com/api/v1/channel_folders", "body": { "type": "form-urlencoded", "data": [ { "name": "include_archived", "value": "" } ] } }, "docs": "Fetches all of the [channel folders](/help/channel-folders) in the\norganization, sorted by the `order` field.\n\n**Changes**: Before Zulip 11.0 (feature level 414), the list of channel\nfolders was sorted by ID as the `order` field didn't exist.\n\nNew in Zulip 11.0 (feature level 389).\n" }, { "info": { "name": "Reorder channel folders", "type": "http" }, "http": { "method": "PATCH", "url": "https://{subdomain}.zulipchat.com/api/v1/channel_folders", "body": { "type": "form-urlencoded", "data": [ { "name": "order", "value": "" } ] } }, "docs": "Reorder the [channel folders](/help/channel-folders) in the user's\norganization.\n\nChannel folders are displayed in Zulip UI in order; this endpoint allows\nadministrative settings UI to change the ordering of channel folders.\n\nThis endpoint is used to implement the dragging feature described in the\n[manage channel folders documentation](/help/manage-channel-folders).\n\n**Changes**: New in Zulip 11.0 (feature level 414).\n" }, { "info": { "name": "Update a channel folder", "type": "http" }, "http": { "method": "PATCH", "url": "https://{subdomain}.zulipchat.com/api/v1/channel_folders/:channel_folder_id", "params": [ { "name": "channel_folder_id", "value": "1", "type": "path", "description": "The ID of the target channel folder.\n" } ], "body": { "type": "form-urlencoded", "data": [ { "name": "name", "value": "" }, { "name": "description", "value": "" }, { "name": "is_archived", "value": "" } ] } }, "docs": "Update the name or description of a [channel folder](/help/channel-folders)\nwith the specified ID.\n\nThis endpoint is also used to archive or unarchive the specified channel\nfolder.\n\n**Changes**: New in Zulip 11.0 (feature level 389).\n" }, { "info": { "name": "Create BigBlueButton video call", "type": "http" }, "http": { "method": "GET", "url": "https://{subdomain}.zulipchat.com/api/v1/calls/bigbluebutton/create", "params": [ { "name": "meeting_name", "value": "test_channel meeting", "type": "query", "description": "Meeting name for the BigBlueButton video call.\n" }, { "name": "voice_only", "value": "true", "type": "query", "description": "Configures whether the call is voice-only; if true,\ndisables cameras for all users. Only the call\ncreator/moderator can edit this configuration.\n\n**Changes**: New in Zulip 10.0 (feature level 337).\n" } ] }, "docs": "Create a video call URL for a BigBlueButton video call.\nRequires [BigBlueButton 2.4+](/integrations/big-blue-button)\nto be configured on the Zulip server.\n\nThe acting user will be given the moderator role on the call.\n\n**Changes**: Prior to Zulip 10.0 (feature level 337), every\nuser was given the moderator role on BigBlueButton calls, via\nencoding a moderator password in the generated URLs.\n" }, { "info": { "name": "Create Nextcloud Talk video call", "type": "http" }, "http": { "method": "POST", "url": "https://{subdomain}.zulipchat.com/api/v1/calls/nextcloud_talk/create", "body": { "type": "form-urlencoded", "data": [ { "name": "room_name", "value": "" } ] } }, "docs": "Create a video call URL for a Nextcloud Talk video call. Requires\n[Nextcloud Talk](/integrations/nextcloud-talk) to be configured on the\nZulip server.\n\n**Changes**: New in Zulip 12.0 (feature level 465).\n" }, { "info": { "name": "Create Webex video call", "type": "http" }, "http": { "method": "POST", "url": "https://{subdomain}.zulipchat.com/api/v1/calls/webex/create" }, "docs": "Create a video call URL for a Webex video call.\n\nRequires [Webex integration](/integrations/webex) to be configured\non the Zulip server.\n\nClients should confirm that the user has completed the OAuth process\nwith Webex and has a Webex token before attempting to create a video\ncall URL. See the `has_webex_token` field in the [`POST /register`\nresponse](/api/register-queue), as well as the [`has_webex_token`\nevent type](/api/get-events#has_webex_token).\n\n**Changes**: New in Zulip 12.0 (feature leve" }, { "info": { "name": "Create Constructor Groups video call", "type": "http" }, "http": { "method": "POST", "url": "https://{subdomain}.zulipchat.com/api/v1/calls/constructorgroups/create" }, "docs": "Create a video call URL for a Constructor Groups video call.\nRequires [Constructor Groups](/integrations/constructor-groups)\nto be configured on the Zulip server.\n\n**Changes**: New in Zulip 12.0 (feature level 460).\n" } ] }, { "info": { "name": "messages", "type": "folder" }, "items": [ { "info": { "name": "Mark all messages as read", "type": "http" }, "http": { "method": "POST", "url": "https://{subdomain}.zulipchat.com/api/v1/mark_all_as_read" }, "docs": "Marks all of the current user's unread messages as read.\n\nBecause this endpoint marks messages as read in batches, it is possible\nfor the request to time out after only marking some messages as read.\nWhen this happens, the `complete` boolean field in the success response\nwill be `false`. Clients should repeat the request when handling such a\nresponse. If all messages were marked as read, then the success response\nwill return `\"complete\": true`.\n\n**Changes**: Deprecated; clients should use the [u" }, { "info": { "name": "Mark messages in a channel as read", "type": "http" }, "http": { "method": "POST", "url": "https://{subdomain}.zulipchat.com/api/v1/mark_stream_as_read", "body": { "type": "form-urlencoded", "data": [ { "name": "stream_id", "value": "" } ] } }, "docs": "Mark all the unread messages in a channel as read.\n\n**Changes**: Deprecated; clients should use the [update personal message\nflags for narrow](/api/update-message-flags-for-narrow) endpoint instead\nas this endpoint will be removed in a future release.\n" }, { "info": { "name": "Mark messages in a topic as read", "type": "http" }, "http": { "method": "POST", "url": "https://{subdomain}.zulipchat.com/api/v1/mark_topic_as_read", "body": { "type": "form-urlencoded", "data": [ { "name": "stream_id", "value": "" }, { "name": "topic_name", "value": "" } ] } }, "docs": "Mark all the unread messages in a topic as read.\n\n**Changes**: Deprecated; clients should use the [update personal message\nflags for narrow](/api/update-message-flags-for-narrow) endpoint instead\nas this endpoint will be removed in a future release.\n" }, { "info": { "name": "Get messages", "type": "http" }, "http": { "method": "GET", "url": "https://{subdomain}.zulipchat.com/api/v1/messages", "params": [ { "name": "anchor", "value": "43", "type": "query", "description": "Integer message ID to anchor fetching of new messages. Supports special\nstring values for when the client wants the server to compute the anchor\nto use:\n\n- `newest`: The most recent message.\n- `oldest`: The oldest message.\n- `first_unread`: The oldest unread message matching the\n query, if any; otherwise, the most recent message.\n- `date`: The first message on or after the datetime indicated by the\n [`anchor_date`](#parameter-anchor_date), if any; otherwise, the most\n recent message.\n\n**Changes**: The `date` value is new in Zulip 12.0 (feature level 445).\n\nString values are new in Zulip 3.0 (feature level 1). The\n`first_unread` functionality was supported in Zulip 2.1.x\nand older by not sending `anchor` and using `use_first_unread_anchor`.\n\nIn Zulip 2.1.x and older, `oldest` can be emulated with\n`\"anchor\": 0`, and `newest` with `\"anchor\": 10000000000000000`\n(that specific large value works around a bug in Zulip\n2.1.x and older in the `found_newest` return value).\n" }, { "name": "include_anchor", "value": "false", "type": "query", "description": "Whether a message with the specified ID matching the narrow\nshould be included.\n\n**Changes**: New in Zulip 6.0 (feature level 155).\n" }, { "name": "anchor_date", "value": "2005-04-18T12:34:56Z", "type": "query", "description": "The date or datetime to use for finding the anchor message when `anchor` is\n`date`. Accepted formats include ISO 8601 date-only strings\n(e.g. `2005-04-18`) as well as full datetime strings\n(e.g. `2005-04-18T12:34:56Z`). If only a date is provided, the datetime is set to\nmidnight (00:00) on that day in UTC. If no timezone is provided, UTC is\nassumed.\n\n**Changes**: New in Zulip 12.0 (feature level 445).\n" }, { "name": "num_before", "value": "4", "type": "query", "description": "The number of messages with IDs less than the anchor to retrieve.\nRequired if `message_ids` is not provided.\n" }, { "name": "num_after", "value": "8", "type": "query", "description": "The number of messages with IDs greater than the anchor to retrieve.\nRequired if `message_ids` is not provided.\n" }, { "name": "narrow", "value": "", "type": "query", "description": "The narrow where you want to fetch the messages from. See how to\n[construct a narrow](/api/construct-narrow).\n\nNote that many narrows, including all that lack a `channel`, `channels`,\n`stream`, or `streams` operator, search the user's personal message\nhistory. See [searching shared\nhistory](/help/search-for-messages#search-shared-history)\nfor details.\n\nFor example, if you would like to fetch messages from all public channels instead\nof only the user's message history, then a specific narrow for\nmessages sent to all public channels can be used:\n`{\"operator\": \"channels\", \"operand\": \"public\"}`.\n\nNewly created bot users are not usually subscribed to any\nchannels, so bots using this API should either be\nsubscribed to appropriate channels or use a shared history\nsearch narrow with this endpoint.\n\n**Changes**: See [changes section](/api/construct-narrow#changes)\nof search/narrow filter documentation.\n" }, { "name": "client_gravatar", "value": "false", "type": "query", "description": "Whether the client supports computing gravatars URLs. If\nenabled, `avatar_url` will be included in the response only\nif there is a Zulip avatar, and will be `null` for users who\nare using gravatar as their avatar. This option\nsignificantly reduces the compressed size of user data,\nsince gravatar URLs are long, random strings and thus do not\ncompress well. The `client_gravatar` field is set to `true` if\nclients can compute their own gravatars.\n\n**Changes**: The default value of this parameter was `false`\nprior to Zulip 5.0 (feature level 92).\n" }, { "name": "apply_markdown", "value": "false", "type": "query", "description": "If `true`, message content is returned in the rendered HTML\nformat. If `false`, message content is returned in the raw\nMarkdown-format text that user entered.\n\nSee [Markdown message formatting](/api/message-formatting) for details on Zulip's HTML format.\n" }, { "name": "use_first_unread_anchor", "value": "true", "type": "query", "description": "Legacy way to specify `\"anchor\": \"first_unread\"` in Zulip 2.1.x and older.\n\nWhether to use the (computed by the server) first unread message\nmatching the narrow as the `anchor`. Mutually exclusive with `anchor`.\n\n**Changes**: Deprecated in Zulip 3.0 (feature level 1) and replaced by\n`\"anchor\": \"first_unread\"`.\n" }, { "name": "message_ids", "value": "", "type": "query", "description": "A list of message IDs to fetch. The server will return messages corresponding to the\nsubset of the requested message IDs that exist and the current user has access to,\npotentially filtered by the narrow (if that parameter is provided).\n\nIt is an error to pass this parameter as well as any of the parameters involved in\nspecifying a range of messages: `anchor`, `include_anchor`, `use_first_unread_anchor`,\n`num_before`, and `num_after`.\n\n**Changes**: New in Zulip 10.0 (feature level 300). Previously, there was\nno way to request a specific set of messages IDs.\n" }, { "name": "allow_empty_topic_name", "value": "true", "type": "query", "description": "Whether the client supports processing the empty string as a topic in the\ntopic name fields in the returned data, including in returned edit_history data.\n\nIf `false`, the server will use the value of `realm_empty_topic_display_name`\nfound in the [`POST /register`](/api/register-queue) response instead of empty string\nto represent the empty string topic in its response.\n\n**Changes**: New in Zulip 10.0 (feature level 334). Previously, the empty string\nwas not a valid topic.\n" } ] }, "docs": "This endpoint is the primary way to fetch a messages. It is used by all official\nZulip clients (e.g. the web, desktop, mobile, and terminal clients) as well as\nmany bots, API clients, backup scripts, etc.\n\nMost queries will specify a [narrow filter](/api/get-messages#parameter-narrow),\nto fetch the messages matching any supported [search\nquery](/help/search-for-messages). If not specified, it will return messages\ncorresponding to the user's [combined feed](/help/combined-feed). There are two\nway" }, { "info": { "name": "Send a message", "type": "http" }, "http": { "method": "POST", "url": "https://{subdomain}.zulipchat.com/api/v1/messages", "body": { "type": "form-urlencoded", "data": [ { "name": "type", "value": "" }, { "name": "to", "value": "" }, { "name": "content", "value": "" }, { "name": "topic", "value": "" }, { "name": "queue_id", "value": "" }, { "name": "local_id", "value": "" }, { "name": "read_by_sender", "value": "" } ] } }, "docs": "Send a [channel message](/help/introduction-to-topics) or a\n[direct message](/help/direct-messages).\n" }, { "info": { "name": "Get a message's edit history", "type": "http" }, "http": { "method": "GET", "url": "https://{subdomain}.zulipchat.com/api/v1/messages/:message_id/history", "params": [ { "name": "message_id", "value": "43", "type": "path", "description": "The target message's ID.\n" }, { "name": "allow_empty_topic_name", "value": "true", "type": "query", "description": "Whether the topic names i.e. `topic` and `prev_topic` fields in\nthe `message_history` objects returned can be empty string.\n\nIf `false`, the value of `realm_empty_topic_display_name`\nfound in the [`POST /register`](/api/register-queue) response is\nreturned replacing the empty string as the topic name.\n\n**Changes**: New in Zulip 10.0 (feature level 334).\n" } ] }, "docs": "Fetch the message edit history of a previously edited message.\n\nNote that edit history may be disabled in some organizations; see the\n[Zulip help center documentation on editing messages][edit-settings].\n\n[edit-settings]: /help/view-a-messages-edit-history\n" }, { "info": { "name": "Update personal message flags", "type": "http" }, "http": { "method": "POST", "url": "https://{subdomain}.zulipchat.com/api/v1/messages/flags", "body": { "type": "form-urlencoded", "data": [ { "name": "messages", "value": "" }, { "name": "op", "value": "" }, { "name": "flag", "value": "" } ] } }, "docs": "Add or remove personal message flags like `read` and `starred`\non a collection of message IDs.\n\nSee also the endpoint for [updating flags on a range of\nmessages within a narrow](/api/update-message-flags-for-narrow).\n" }, { "info": { "name": "Update personal message flags for narrow", "type": "http" }, "http": { "method": "POST", "url": "https://{subdomain}.zulipchat.com/api/v1/messages/flags/narrow", "body": { "type": "form-urlencoded", "data": [ { "name": "anchor", "value": "" }, { "name": "include_anchor", "value": "" }, { "name": "num_before", "value": "" }, { "name": "num_after", "value": "" }, { "name": "narrow", "value": "" }, { "name": "op", "value": "" }, { "name": "flag", "value": "" } ] } }, "docs": "Add or remove personal message flags like `read` and `starred`\non a range of messages within a narrow.\n\nSee also [the endpoint for updating flags on specific message\nIDs](/api/update-message-flags).\n\n**Changes**: New in Zulip 6.0 (feature level 155).\n" }, { "info": { "name": "Render a message", "type": "http" }, "http": { "method": "POST", "url": "https://{subdomain}.zulipchat.com/api/v1/messages/render", "body": { "type": "form-urlencoded", "data": [ { "name": "content", "value": "" } ] } }, "docs": "Render a message to HTML.\n" }, { "info": { "name": "Add an emoji reaction", "type": "http" }, "http": { "method": "POST", "url": "https://{subdomain}.zulipchat.com/api/v1/messages/:message_id/reactions", "params": [ { "name": "message_id", "value": "43", "type": "path", "description": "The target message's ID.\n" } ], "body": { "type": "form-urlencoded", "data": [ { "name": "emoji_name", "value": "" }, { "name": "emoji_code", "value": "" }, { "name": "reaction_type", "value": "" } ] } }, "docs": "Add an [emoji reaction](/help/emoji-reactions) to a message.\n" }, { "info": { "name": "Remove an emoji reaction", "type": "http" }, "http": { "method": "DELETE", "url": "https://{subdomain}.zulipchat.com/api/v1/messages/:message_id/reactions", "params": [ { "name": "message_id", "value": "43", "type": "path", "description": "The target message's ID.\n" } ], "body": { "type": "form-urlencoded", "data": [ { "name": "emoji_name", "value": "" }, { "name": "emoji_code", "value": "" }, { "name": "reaction_type", "value": "" } ] } }, "docs": "Remove an [emoji reaction](/help/emoji-reactions) from a message.\n" }, { "info": { "name": "Get a message's read receipts", "type": "http" }, "http": { "method": "GET", "url": "https://{subdomain}.zulipchat.com/api/v1/messages/:message_id/read_receipts", "params": [ { "name": "message_id", "value": "43", "type": "path", "description": "The target message's ID.\n" } ] }, "docs": "Returns a list containing the IDs for all users who have\nmarked the message as read (and whose privacy settings allow\nsharing that information).\n\nThe list of users IDs will include any bots who have marked\nthe message as read via the API (providing a way for bots to\nindicate whether they have processed a message successfully in\na way that can be easily inspected in a Zulip client). Bots\nfor which this behavior is not desired may disable the\n`send_read_receipts` setting via the API.\n\nIt will neve" }, { "info": { "name": "Check if messages match a narrow", "type": "http" }, "http": { "method": "GET", "url": "https://{subdomain}.zulipchat.com/api/v1/messages/matches_narrow", "params": [ { "name": "msg_ids", "value": "", "type": "query", "description": "List of IDs for the messages to check." }, { "name": "narrow", "value": "", "type": "query", "description": "A structure defining the narrow to check against. See how to\n[construct a narrow](/api/construct-narrow).\n\n**Changes**: See [changes section](/api/construct-narrow#changes)\nof search/narrow filter documentation.\n" } ] }, "docs": "Check whether a set of messages match a [narrow](/api/construct-narrow).\n\nFor many common narrows (e.g. a topic), clients can write an efficient\nclient-side check to determine whether a newly arrived message belongs\nin the view.\n\nThis endpoint is designed to allow clients to handle more complex narrows\nfor which the client does not (or in the case of full-text search, cannot)\nimplement this check.\n\nThe format of the `match_subject` and `match_content` objects is designed\nto match those returned " }, { "info": { "name": "Fetch a single message", "type": "http" }, "http": { "method": "GET", "url": "https://{subdomain}.zulipchat.com/api/v1/messages/:message_id", "params": [ { "name": "message_id", "value": "43", "type": "path", "description": "The target message's ID.\n" }, { "name": "apply_markdown", "value": "false", "type": "query", "description": "If `true`, message content is returned in the rendered HTML\nformat. If `false`, message content is returned in the raw\n[Zulip-flavored Markdown format](/help/format-your-message-using-markdown) text that user entered.\n\n**Changes**: New in Zulip 5.0 (feature level 120).\n" }, { "name": "allow_empty_topic_name", "value": "true", "type": "query", "description": "Whether the client supports processing the empty string as a topic in the\ntopic name fields in the returned data, including in returned edit_history data.\n\nIf `false`, the server will use the value of `realm_empty_topic_display_name`\nfound in the [`POST /register`](/api/register-queue) response instead of empty string\nto represent the empty string topic in its response.\n\n**Changes**: New in Zulip 10.0 (feature level 334). Previously, the empty string\nwas not a valid topic.\n" } ] }, "docs": "Given a message ID, return the message object.\n\nAdditionally, a `raw_content` field is included. This field is\nuseful for clients that primarily work with HTML-rendered\nmessages but might need to occasionally fetch the message's\nraw [Zulip-flavored Markdown](/help/format-your-message-using-markdown) (e.g. for [view\nsource](/help/view-the-markdown-source-of-a-message) or\nprefilling a message edit textarea).\n\n**Changes**: Before Zulip 5.0 (feature level 120), this\nendpoint only returned the `raw_c" }, { "info": { "name": "Edit a message", "type": "http" }, "http": { "method": "PATCH", "url": "https://{subdomain}.zulipchat.com/api/v1/messages/:message_id", "params": [ { "name": "message_id", "value": "43", "type": "path", "description": "The target message's ID.\n" } ], "body": { "type": "form-urlencoded", "data": [ { "name": "topic", "value": "" }, { "name": "propagate_mode", "value": "" }, { "name": "send_notification_to_old_thread", "value": "" }, { "name": "send_notification_to_new_thread", "value": "" }, { "name": "content", "value": "" }, { "name": "prev_content_sha256", "value": "" }, { "name": "stream_id", "value": "" } ] } }, "docs": "Update the content, topic, or channel of the message with the specified\nID.\n\nYou can [resolve topics](/help/resolve-a-topic) by editing the topic to\n`✔ {original_topic}` with the `propagate_mode` parameter set to\n`\"change_all\"`.\n\nSee [configuring message editing][config-message-editing] for detailed\ndocumentation on when users are allowed to edit message content, and\n[restricting moving messages][restrict-move-messages] for detailed\ndocumentation on when users are allowed to change a message's t" }, { "info": { "name": "Delete a message", "type": "http" }, "http": { "method": "DELETE", "url": "https://{subdomain}.zulipchat.com/api/v1/messages/:message_id", "params": [ { "name": "message_id", "value": "43", "type": "path", "description": "The target message's ID.\n" } ] }, "docs": "Permanently delete a message.\n\nThis API corresponds to the [delete a message completely][delete-completely]\nfeature documented in the Zulip help center.\n\nA user must be able to access the content of a message in order to delete it.\nSee [channel permissions](/help/channel-permissions) for more information\nabout content access for channel messages. For direct messages, the user\nmust have received or sent the direct message to have content access.\n\nSee [restricting message deletion](/help/restrict-" }, { "info": { "name": "Report a message", "type": "http" }, "http": { "method": "POST", "url": "https://{subdomain}.zulipchat.com/api/v1/messages/:message_id/report", "params": [ { "name": "message_id", "value": "43", "type": "path", "description": "The target message's ID.\n" } ], "body": { "type": "form-urlencoded", "data": [ { "name": "report_type", "value": "" }, { "name": "description", "value": "" } ] } }, "docs": "Sends a notification to the organization's [moderation request\nchannel](/help/enable-moderation-requests), if it is configured, that\nreports the targeted message for [review and moderation](/help/report-a-message).\n\nClients should check the `moderation_request_channel` realm setting to\ndecide whether to show the option to report messages in the UI.\n\nIf the `report_type` parameter value is `\"other\"`, the `description`\nparameter is required. Clients should also enforce and communicate this\nbehavio" }, { "info": { "name": "Upload a file", "type": "http" }, "http": { "method": "POST", "url": "https://{subdomain}.zulipchat.com/api/v1/user_uploads", "body": { "type": "multipart-form", "data": [ { "name": "filename", "type": "text", "value": "" } ] } }, "docs": "[Upload](/help/share-and-upload-files) a single file and get the corresponding URL.\n\nInitially, only you will be able to access the link. To share the\nuploaded file, you'll need to [send a message][send-message]\ncontaining the resulting link. Users who can already access the link\ncan reshare it with other users by sending additional Zulip messages\ncontaining the link.\n\nThe maximum allowed file size is available in the `max_file_upload_size_mib`\nfield in the [`POST /register`](/api/register-queue" }, { "info": { "name": "Check thumbnail status", "type": "http" }, "http": { "method": "GET", "url": "https://{subdomain}.zulipchat.com/api/v1/thumbnail/status/:realm_id_str/:filename", "params": [ { "name": "realm_id_str", "value": "1", "type": "path", "description": "The realm ID component of the file's `path_id`. If the `path_id` is\n`1/4e/m2A3MSqFnWRLUf9SaPzQ0Up_/zulip.txt`, the `realm_id_str` would be `1`.\n" }, { "name": "filename", "value": "4e/m2A3MSqFnWRLUf9SaPzQ0Up_/zulip.txt", "type": "path", "description": "The file path component of the file's `path_id` (everything\nafter the first `/`). If the `path_id` is\n`1/4e/m2A3MSqFnWRLUf9SaPzQ0Up_/zulip.txt`, the `filename`\nwould be `4e/m2A3MSqFnWRLUf9SaPzQ0Up_/zulip.txt`.\n" } ] }, "docs": "Check whether a thumbnail exists for a specific file uploaded by a user.\nThis endpoint is intended to be polled by clients to determine when\nthumbnail generation is complete.\n\n**Changes**: New in Zulip 12.0 (feature level 479).\n" }, { "info": { "name": "Get public temporary URL for an uploaded file", "type": "http" }, "http": { "method": "GET", "url": "https://{subdomain}.zulipchat.com/api/v1/user_uploads/:realm_id_str/:filename", "params": [ { "name": "realm_id_str", "value": "1", "type": "path", "description": "The realm ID component of the file's `path_id`. If the `path_id` is\n`1/4e/m2A3MSqFnWRLUf9SaPzQ0Up_/zulip.txt`, the `realm_id_str` would be `1`.\n" }, { "name": "filename", "value": "4e/m2A3MSqFnWRLUf9SaPzQ0Up_/zulip.txt", "type": "path", "description": "The file path component of the file's `path_id` (everything\nafter the first `/`). If the `path_id` is\n`1/4e/m2A3MSqFnWRLUf9SaPzQ0Up_/zulip.txt`, the `filename`\nwould be `4e/m2A3MSqFnWRLUf9SaPzQ0Up_/zulip.txt`.\n" } ] }, "docs": "Get a temporary URL for access to an [uploaded file](/api/upload-file)\nthat doesn't require authentication.\n\nThe `SIGNED_ACCESS_TOKEN_VALIDITY_IN_SECONDS` server setting controls\nthe valid length of time for temporary access, which generally is set\nto a default of 60 seconds. Consumers of this API are expected to\nimmediately request the URL that it returns, and should not store it\nin any way.\n\n**Changes**: New in Zulip 3.0 (feature level 1).\n" } ] }, { "info": { "name": "users", "type": "folder" }, "items": [ { "info": { "name": "Get attachments", "type": "http" }, "http": { "method": "GET", "url": "https://{subdomain}.zulipchat.com/api/v1/attachments" }, "docs": "Fetch metadata on files uploaded by the requesting user.\n" }, { "info": { "name": "Delete an attachment", "type": "http" }, "http": { "method": "DELETE", "url": "https://{subdomain}.zulipchat.com/api/v1/attachments/:attachment_id", "params": [ { "name": "attachment_id", "value": "1", "type": "path", "description": "The ID of the attachment to be deleted.\n" } ] }, "docs": "Delete an uploaded file given its attachment ID.\n\nNote that uploaded files that have been referenced in at least\none message are automatically deleted once the last message\ncontaining a link to them is deleted (whether directly or via\na [message retention policy](/help/message-retention-policy)).\n\nUploaded files that are never used in a message are\nautomatically deleted a few weeks after being uploaded.\n\nAttachment IDs can be contained from [GET /attachments](/api/get-attachments).\n" }, { "info": { "name": "Get users", "type": "http" }, "http": { "method": "GET", "url": "https://{subdomain}.zulipchat.com/api/v1/users", "params": [ { "name": "client_gravatar", "value": "false", "type": "query", "description": "Whether the client supports computing gravatars URLs. If\nenabled, `avatar_url` will be included in the response only\nif there is a Zulip avatar, and will be `null` for users who\nare using gravatar as their avatar. This option\nsignificantly reduces the compressed size of user data,\nsince gravatar URLs are long, random strings and thus do not\ncompress well. The `client_gravatar` field is set to `true` if\nclients can compute their own gravatars.\n\n**Changes**: The default value of this parameter was `false`\nprior to Zulip 5.0 (feature level 92).\n" }, { "name": "include_custom_profile_fields", "value": "true", "type": "query", "description": "Whether the client wants [custom profile field](/help/custom-profile-fields)\ndata to be included in the response.\n\n**Changes**: New in Zulip 2.1.0. Previous versions do not offer these\ndata via the API.\n" }, { "name": "user_ids", "value": "", "type": "query", "description": "Limits the results to the specified user IDs. If not\nprovided, the server will return all accessible users in\nthe organization.\n\n**Changes**: New in Zulip 11.0 (feature level 384).\n" } ] }, "docs": "Retrieve details on users in the organization.\n\nBy default, returns all accessible users in the organization.\nThe `user_ids` query parameter can be used to limit the\nresults to a specific set of user IDs.\n\nOptionally includes values of [custom profile fields](/help/custom-profile-fields).\n\nYou can also [fetch details on a single user](/api/get-user).\n\n**Changes**: In Zulip 12.0 (feature level 437), fixed a bug\ndating to feature level 232, which caused guest users to\nreceive fake backwards-compat" }, { "info": { "name": "Create a user", "type": "http" }, "http": { "method": "POST", "url": "https://{subdomain}.zulipchat.com/api/v1/users", "body": { "type": "form-urlencoded", "data": [ { "name": "email", "value": "" }, { "name": "password", "value": "" }, { "name": "full_name", "value": "" } ] } }, "docs": "Create a new user account via the API.\n\n!!! warn \"\"\n\n **Note**: On Zulip Cloud, this feature is available only for\n organizations on a [Zulip Cloud Standard](https://zulip.com/plans/)\n or [Zulip Cloud Plus](https://zulip.com/plans/) plan. Administrators\n can request the required `can_create_users` permission for a bot or\n user by contacting [Zulip Cloud support][support] with an\n explanation for why it is needed. Self-hosted installations can\n toggle `can_create_users` on an" }, { "info": { "name": "Reactivate a user", "type": "http" }, "http": { "method": "POST", "url": "https://{subdomain}.zulipchat.com/api/v1/users/:user_id/reactivate", "params": [ { "name": "user_id", "value": "12", "type": "path", "description": "The target user's ID.\n" } ] }, "docs": "[Reactivates a\nuser](https://zulip.com/help/deactivate-or-reactivate-a-user)\ngiven their user ID.\n" }, { "info": { "name": "Get a user's status", "type": "http" }, "http": { "method": "GET", "url": "https://{subdomain}.zulipchat.com/api/v1/users/:user_id/status", "params": [ { "name": "user_id", "value": "12", "type": "path", "description": "The target user's ID.\n" } ] }, "docs": "Get the [status](/help/status-and-availability) currently set by a\nuser in the organization.\n\n**Changes**: New in Zulip 9.0 (feature level 262). Previously,\nuser statuses could only be fetched via the [`POST\n/register`](/api/register-queue) endpoint.\n" }, { "info": { "name": "Update user status", "type": "http" }, "http": { "method": "POST", "url": "https://{subdomain}.zulipchat.com/api/v1/users/:user_id/status", "params": [ { "name": "user_id", "value": "12", "type": "path", "description": "The target user's ID.\n" } ], "body": { "type": "form-urlencoded", "data": [ { "name": "status_text", "value": "" }, { "name": "emoji_name", "value": "" }, { "name": "emoji_code", "value": "" }, { "name": "reaction_type", "value": "" } ] } }, "docs": "Administrator endpoint for changing the [status](/help/status-and-availability) of\nanother user.\n\n**Changes**: Prior to Zulip 12.0 (feature level 473), only\nbots could not access this API endpoint, regardless of the\nrole of the bot.\n\nNew in Zulip 11.0 (feature level 407).\n" }, { "info": { "name": "Get a user's presence", "type": "http" }, "http": { "method": "GET", "url": "https://{subdomain}.zulipchat.com/api/v1/users/:user_id_or_email/presence", "params": [ { "name": "user_id_or_email", "value": "iago@zulip.com", "type": "path", "description": "The ID or Zulip API email address of the user whose presence you want to fetch.\n\n**Changes**: New in Zulip 4.0 (feature level 43). Previous versions only supported\nidentifying the user by Zulip API email.\n" } ] }, "docs": "Get the presence status for a specific user.\n\nThis endpoint is most useful for embedding data about a user's\npresence status in other sites (e.g. an employee directory). Full\nZulip clients like mobile/desktop apps will want to use the [main\npresence endpoint](/api/get-presence), which returns data for all\nactive users in the organization, instead.\n" }, { "info": { "name": "Get own user", "type": "http" }, "http": { "method": "GET", "url": "https://{subdomain}.zulipchat.com/api/v1/users/me" }, "docs": "Get basic data about the user/bot that requests this endpoint.\n\n**Changes**: Removed `is_billing_admin` field in Zulip 10.0 (feature level 363), as it was\nreplaced by the `can_manage_billing_group` realm setting.\n" }, { "info": { "name": "Deactivate own user", "type": "http" }, "http": { "method": "DELETE", "url": "https://{subdomain}.zulipchat.com/api/v1/users/me" }, "docs": "Deactivates the current user's account. See also the administrative endpoint for\n[deactivating another user](/api/deactivate-user).\n\nThis endpoint is primarily useful to Zulip clients providing a user settings UI.\n" }, { "info": { "name": "Regenerate your API key", "type": "http" }, "http": { "method": "POST", "url": "https://{subdomain}.zulipchat.com/api/v1/users/me/api_key/regenerate" }, "docs": "!!! warn \"\"\n\n **Note**: Users should treat their Zulip API key as\n [carefully as they would their password](/help/protect-your-account).\n\nGenerate a new API key for the user making the request.\n\nChanging a user's API key will immediately log them out of Zulip\non devices registered for [mobile push notifications][mobile-push].\n\n**Changes**: Before Zulip 12.0 (feature level 492),\nregenerating a user's API key didn't remove all of the user's\n[E2EE push device registrations](/api/register-pu" }, { "info": { "name": "Get all alert words", "type": "http" }, "http": { "method": "GET", "url": "https://{subdomain}.zulipchat.com/api/v1/users/me/alert_words" }, "docs": "Get all of the user's configured [alert words][alert-words].\n\n[alert-words]: /help/dm-mention-alert-notifications#alert-words\n" }, { "info": { "name": "Add alert words", "type": "http" }, "http": { "method": "POST", "url": "https://{subdomain}.zulipchat.com/api/v1/users/me/alert_words", "body": { "type": "form-urlencoded", "data": [ { "name": "alert_words", "value": "" } ] } }, "docs": "Add words (or phrases) to the user's set of configured [alert words][alert-words].\n\n[alert-words]: /help/dm-mention-alert-notifications#alert-words\n" }, { "info": { "name": "Remove alert words", "type": "http" }, "http": { "method": "DELETE", "url": "https://{subdomain}.zulipchat.com/api/v1/users/me/alert_words", "body": { "type": "form-urlencoded", "data": [ { "name": "alert_words", "value": "" } ] } }, "docs": "Remove words (or phrases) from the user's set of configured [alert words][alert-words].\n\nAlert words are case insensitive.\n\n[alert-words]: /help/dm-mention-alert-notifications#alert-words\n" }, { "info": { "name": "Update your presence", "type": "http" }, "http": { "method": "POST", "url": "https://{subdomain}.zulipchat.com/api/v1/users/me/presence", "body": { "type": "form-urlencoded", "data": [ { "name": "last_update_id", "value": "" }, { "name": "history_limit_days", "value": "" }, { "name": "new_user_input", "value": "" }, { "name": "ping_only", "value": "" }, { "name": "slim_presence", "value": "" }, { "name": "status", "value": "" } ] } }, "docs": "Update the current user's [presence][availability] and fetch presence data\nof other users in the organization.\n\nThis endpoint is meant to be used by clients for both:\n\n- Reporting the current user's presence status (`\"active\"` or `\"idle\"`)\n to the server.\n\n- Obtaining the presence data of all other users in the organization via\n regular polling.\n\nAccurate user presence is one of the most expensive parts of any\nchat application (in terms of bandwidth and other resources). Therefore,\nit is impor" }, { "info": { "name": "Update your profile data", "type": "http" }, "http": { "method": "PATCH", "url": "https://{subdomain}.zulipchat.com/api/v1/users/me/profile_data", "body": { "type": "form-urlencoded", "data": [ { "name": "data", "value": "" } ] } }, "docs": "Update the current user's [profile data](/help/edit-your-profile) for\none or more of the [custom profile fields](/help/custom-profile-fields)\nconfigured in the organization.\n" }, { "info": { "name": "Remove your profile data", "type": "http" }, "http": { "method": "DELETE", "url": "https://{subdomain}.zulipchat.com/api/v1/users/me/profile_data", "body": { "type": "form-urlencoded", "data": [ { "name": "data", "value": "" } ] } }, "docs": "Remove the current user's [profile data](/help/edit-your-profile) for\none or more of the [custom profile fields](/help/custom-profile-fields)\nconfigured in the organization.\n" }, { "info": { "name": "Update your status", "type": "http" }, "http": { "method": "POST", "url": "https://{subdomain}.zulipchat.com/api/v1/users/me/status", "body": { "type": "form-urlencoded", "data": [ { "name": "status_text", "value": "" }, { "name": "away", "value": "" }, { "name": "emoji_name", "value": "" }, { "name": "emoji_code", "value": "" }, { "name": "reaction_type", "value": "" } ] } }, "docs": "Change your [status](/help/status-and-availability).\n\nA request to this endpoint will only change the parameters passed.\nFor example, passing just `status_text` requests a change in the status\ntext, but will leave the status emoji unchanged.\n\nClients that wish to set the user's status to a specific value should\npass all supported parameters.\n\n**Changes**: In Zulip 5.0 (feature level 86), added support for\n`emoji_name`, `emoji_code`, and `reaction_type` parameters.\n" }, { "info": { "name": "Mute a user", "type": "http" }, "http": { "method": "POST", "url": "https://{subdomain}.zulipchat.com/api/v1/users/me/muted_users/:muted_user_id", "params": [ { "name": "muted_user_id", "value": "10", "type": "path", "description": "The ID of the user to mute/unmute.\n\n**Changes**: Before Zulip 8.0 (feature level 188), bot users could not\nbe muted/unmuted, and specifying a bot user's ID returned an error response.\n" } ] }, "docs": "[Mute a user](/help/mute-a-user) from the perspective of the requesting\nuser. Messages sent by muted users will be automatically marked as read\nand hidden for the user who muted them.\n\nMuted users should be implemented by clients as follows:\n\n- The server will immediately mark all messages sent by the muted\n user as read. This will automatically clear any existing mobile\n push notifications related to the muted user.\n- The server will mark any new messages sent by the muted user as read\n for " }, { "info": { "name": "Unmute a user", "type": "http" }, "http": { "method": "DELETE", "url": "https://{subdomain}.zulipchat.com/api/v1/users/me/muted_users/:muted_user_id", "params": [ { "name": "muted_user_id", "value": "10", "type": "path", "description": "The ID of the user to mute/unmute.\n\n**Changes**: Before Zulip 8.0 (feature level 188), bot users could not\nbe muted/unmuted, and specifying a bot user's ID returned an error response.\n" } ] }, "docs": "[Unmute a user](/help/mute-a-user#see-your-list-of-muted-users)\nfrom the perspective of the requesting user.\n\n**Changes**: New in Zulip 4.0 (feature level 48).\n" }, { "info": { "name": "Add an APNs device token", "type": "http" }, "http": { "method": "POST", "url": "https://{subdomain}.zulipchat.com/api/v1/users/me/apns_device_token", "body": { "type": "form-urlencoded", "data": [ { "name": "token", "value": "" }, { "name": "appid", "value": "" } ] } }, "docs": "This endpoint adds an APNs device token to register for iOS push notifications.\n\n**Changes**: Deprecated in Zulip 11.0 (feature level 406). Clients connecting\nto newer servers and with E2EE push notifications support should use the\n[Register E2EE push device](/api/register-push-device) endpoint, as this\nendpoint will be removed in a future release.\n" }, { "info": { "name": "Remove an APNs device token", "type": "http" }, "http": { "method": "DELETE", "url": "https://{subdomain}.zulipchat.com/api/v1/users/me/apns_device_token", "body": { "type": "form-urlencoded", "data": [ { "name": "token", "value": "" } ] } }, "docs": "This endpoint removes an APNs device token for iOS push notifications.\n\n**Changes**: Deprecated in Zulip 11.0 (feature level 406) and will be\nremoved in a future release. Clients connecting to newer servers and\nwith E2EE push notifications support should delete the account record\nin their local accounts table that corresponds to the `push_account_id`\nsupplied when registering via the [Register E2EE push device](/api/register-push-device)\nendpoint, to stop displaying notifications for that regist" }, { "info": { "name": "Add an FCM registration token", "type": "http" }, "http": { "method": "POST", "url": "https://{subdomain}.zulipchat.com/api/v1/users/me/android_gcm_reg_id", "body": { "type": "form-urlencoded", "data": [ { "name": "token", "value": "" } ] } }, "docs": "This endpoint adds an FCM registration token for push notifications.\n\n**Changes**: Deprecated in Zulip 11.0 (feature level 406). Clients connecting\nto newer servers and with E2EE push notifications support should use the\n[Register E2EE push device](/api/register-push-device) endpoint, as this\nendpoint will be removed in a future release.\n" }, { "info": { "name": "Remove an FCM registration token", "type": "http" }, "http": { "method": "DELETE", "url": "https://{subdomain}.zulipchat.com/api/v1/users/me/android_gcm_reg_id", "body": { "type": "form-urlencoded", "data": [ { "name": "token", "value": "" } ] } }, "docs": "This endpoint removes an FCM registration token for push notifications.\n\n**Changes**: Deprecated in Zulip 11.0 (feature level 406) and will be\nremoved in a future release. Clients connecting to newer servers and\nwith E2EE push notifications support should delete the account record\nin their local accounts table that corresponds to the `push_account_id`\nsupplied when registering via the [Register E2EE push device](/api/register-push-device)\nendpoint, to stop displaying notifications for that regis" }, { "info": { "name": "Get a user by email", "type": "http" }, "http": { "method": "GET", "url": "https://{subdomain}.zulipchat.com/api/v1/users/:email", "params": [ { "name": "email", "value": "iago@zulip.com", "type": "path", "description": "The email address of the user to fetch. Two forms are supported:\n\n- The real email address of the user (`delivery_email`). The lookup will\n succeed if and only if the user exists and their email address visibility\n setting permits the client to see the email address.\n\n- The dummy Zulip API email address of the form `user{user_id}@{realm_host}`. This\n is identical to simply [getting user by ID](/api/get-user). If the server or\n realm change domains, the dummy email address used has to be adjustment to\n match the new realm domain. This is legacy behavior for\n backwards-compatibility, and will be removed in a future release.\n\n**Changes**: Starting with Zulip 10.0 (feature level 302), lookups by real email\naddress match the semantics of the target's email visibility setting and dummy\nemail addresses work for all users, independently of their email visibility\nsetting.\n\nPreviously, lookups were done only using the Zulip API email addresses.\n" }, { "name": "client_gravatar", "value": "false", "type": "query", "description": "Whether the client supports computing gravatars URLs. If\nenabled, `avatar_url` will be included in the response only\nif there is a Zulip avatar, and will be `null` for users who\nare using gravatar as their avatar. This option\nsignificantly reduces the compressed size of user data,\nsince gravatar URLs are long, random strings and thus do not\ncompress well. The `client_gravatar` field is set to `true` if\nclients can compute their own gravatars.\n\n**Changes**: The default value of this parameter was `false`\nprior to Zulip 5.0 (feature level 92).\n" }, { "name": "include_custom_profile_fields", "value": "true", "type": "query", "description": "Whether the client wants [custom profile field](/help/custom-profile-fields)\ndata to be included in the response.\n\n**Changes**: New in Zulip 2.1.0. Previous versions do not offer these\ndata via the API.\n" } ] }, "docs": "Fetch details for a single user in the organization given a Zulip\nAPI email address.\n\nYou can also fetch details on [all users in the organization](/api/get-users)\nor [by user ID](/api/get-user).\n\nFetching by user ID is generally recommended when possible,\nas a user might [change their email address](/help/change-your-email-address)\nor change their [email address visibility](/help/configure-email-visibility),\neither of which could change the client's ability to look them up by that\nemail address" }, { "info": { "name": "Update a user by email", "type": "http" }, "http": { "method": "PATCH", "url": "https://{subdomain}.zulipchat.com/api/v1/users/:email", "params": [ { "name": "email", "value": "hamlet@zulip.com", "type": "path", "description": "The email address of the user, specified following the same rules as\n[`GET /users/{email}`](/api/get-user-by-email).\n" } ], "body": { "type": "form-urlencoded", "data": [ { "name": "full_name", "value": "" }, { "name": "role", "value": "" }, { "name": "profile_data", "value": "" }, { "name": "new_email", "value": "" } ] } }, "docs": "Administrative endpoint to update the details of another user in the organization by their email address.\nWorks the same way as [`PATCH /users/{user_id}`](/api/update-user) but fetching the target user by their\nreal email address.\n\nThe requester needs to have permission to view the target user's real email address, subject to the\nuser's email address visibility setting. Otherwise, the dummy address of the format\n`user{id}@{realm.host}` needs be used. This follows the same rules as `GET /users/{e" }, { "info": { "name": "Get a user", "type": "http" }, "http": { "method": "GET", "url": "https://{subdomain}.zulipchat.com/api/v1/users/:user_id", "params": [ { "name": "user_id", "value": "12", "type": "path", "description": "The target user's ID.\n" }, { "name": "client_gravatar", "value": "false", "type": "query", "description": "Whether the client supports computing gravatars URLs. If\nenabled, `avatar_url` will be included in the response only\nif there is a Zulip avatar, and will be `null` for users who\nare using gravatar as their avatar. This option\nsignificantly reduces the compressed size of user data,\nsince gravatar URLs are long, random strings and thus do not\ncompress well. The `client_gravatar` field is set to `true` if\nclients can compute their own gravatars.\n\n**Changes**: The default value of this parameter was `false`\nprior to Zulip 5.0 (feature level 92).\n" }, { "name": "include_custom_profile_fields", "value": "true", "type": "query", "description": "Whether the client wants [custom profile field](/help/custom-profile-fields)\ndata to be included in the response.\n\n**Changes**: New in Zulip 2.1.0. Previous versions do not offer these\ndata via the API.\n" } ] }, "docs": "Fetch details for a single user in the organization.\n\nYou can also fetch details on [all users in the organization](/api/get-users)\nor [by a user's Zulip API email](/api/get-user-by-email).\n\n**Changes**: In Zulip 12.0 (feature level 437), fixed a bug\ndating to feature level 232, which caused guest users to\nreceive fake backwards-compatibility users in the format\nintended for clients using `POST /register` without the\n`user_list_incomplete` client capability.\n\nNew in Zulip 3.0 (feature level 1).\n" }, { "info": { "name": "Update a user", "type": "http" }, "http": { "method": "PATCH", "url": "https://{subdomain}.zulipchat.com/api/v1/users/:user_id", "params": [ { "name": "user_id", "value": "12", "type": "path", "description": "The target user's ID.\n" } ], "body": { "type": "form-urlencoded", "data": [ { "name": "full_name", "value": "" }, { "name": "role", "value": "" }, { "name": "profile_data", "value": "" }, { "name": "new_email", "value": "" } ] } }, "docs": "Administrative endpoint to update the details of another user in the organization.\n\nSupports everything an administrator can do to edit details of another\nuser's account, including editing full name,\n[role](/help/user-roles), and [custom profile\nfields](/help/custom-profile-fields).\n" }, { "info": { "name": "Deactivate a user", "type": "http" }, "http": { "method": "DELETE", "url": "https://{subdomain}.zulipchat.com/api/v1/users/:user_id", "params": [ { "name": "user_id", "value": "12", "type": "path", "description": "The target user's ID.\n" }, { "name": "actions", "value": "", "type": "query", "description": "Additional actions for the server to perform while deactivating the user.\n\nAs with the actual deactivation, actions are first applied\nto any bots controlled by the target user, and then to the\ntarget user.\n\n**Changes**: New in Zulip 12.0 (feature level 459).\n" } ], "body": { "type": "form-urlencoded", "data": [ { "name": "deactivation_notification_comment", "value": "" } ] } }, "docs": "[Deactivates a\nuser](https://zulip.com/help/deactivate-or-reactivate-a-user)\ngiven their user ID.\n\nNote that any bots controlled by the user will be deactivated\nbefore the user; clients that don't want this behavior are\nexpected to prompt the user to adjust the bot's owners before\nmaking this API request.\n" }, { "info": { "name": "Update settings", "type": "http" }, "http": { "method": "PATCH", "url": "https://{subdomain}.zulipchat.com/api/v1/settings", "body": { "type": "form-urlencoded", "data": [ { "name": "target_users", "value": "" }, { "name": "full_name", "value": "" }, { "name": "email", "value": "" }, { "name": "old_password", "value": "" }, { "name": "new_password", "value": "" }, { "name": "twenty_four_hour_time", "value": "" }, { "name": "web_mark_read_on_scroll_policy", "value": "" }, { "name": "web_channel_default_view", "value": "" }, { "name": "starred_message_counts", "value": "" }, { "name": "receives_typing_notifications", "value": "" }, { "name": "web_suggest_update_timezone", "value": "" }, { "name": "fluid_layout_width", "value": "" }, { "name": "high_contrast_mode", "value": "" }, { "name": "web_font_size_px", "value": "" }, { "name": "web_line_height_percent", "value": "" }, { "name": "color_scheme", "value": "" }, { "name": "enable_drafts_synchronization", "value": "" }, { "name": "translate_emoticons", "value": "" }, { "name": "display_emoji_reaction_users", "value": "" }, { "name": "default_language", "value": "" }, { "name": "web_home_view", "value": "" }, { "name": "web_escape_navigates_to_home_view", "value": "" }, { "name": "left_side_userlist", "value": "" }, { "name": "emojiset", "value": "" }, { "name": "demote_inactive_streams", "value": "" }, { "name": "user_list_style", "value": "" }, { "name": "web_animate_image_previews", "value": "" }, { "name": "web_stream_unreads_count_display_policy", "value": "" }, { "name": "hide_ai_features", "value": "" }, { "name": "web_inbox_show_channel_folders", "value": "" }, { "name": "web_left_sidebar_show_channel_folders", "value": "" }, { "name": "web_left_sidebar_unreads_count_summary", "value": "" }, { "name": "timezone", "value": "" }, { "name": "enable_stream_desktop_notifications", "value": "" }, { "name": "enable_stream_email_notifications", "value": "" }, { "name": "enable_stream_push_notifications", "value": "" }, { "name": "enable_stream_audible_notifications", "value": "" }, { "name": "notification_sound", "value": "" }, { "name": "enable_desktop_notifications", "value": "" }, { "name": "enable_sounds", "value": "" }, { "name": "email_notifications_batching_period_seconds", "value": "" }, { "name": "enable_offline_email_notifications", "value": "" }, { "name": "enable_offline_push_notifications", "value": "" }, { "name": "enable_online_push_notifications", "value": "" }, { "name": "enable_followed_topic_desktop_notifications", "value": "" }, { "name": "enable_followed_topic_email_notifications", "value": "" }, { "name": "enable_followed_topic_push_notifications", "value": "" }, { "name": "enable_followed_topic_audible_notifications", "value": "" }, { "name": "enable_digest_emails", "value": "" }, { "name": "enable_marketing_emails", "value": "" }, { "name": "enable_login_emails", "value": "" }, { "name": "message_content_in_email_notifications", "value": "" }, { "name": "pm_content_in_desktop_notifications", "value": "" }, { "name": "wildcard_mentions_notify", "value": "" }, { "name": "enable_followed_topic_wildcard_mentions_notify", "value": "" }, { "name": "desktop_icon_count_display", "value": "" }, { "name": "realm_name_in_email_notifications_policy", "value": "" }, { "name": "automatically_follow_topics_policy", "value": "" }, { "name": "automatically_unmute_topics_in_muted_streams_policy", "value": "" }, { "name": "automatically_follow_topics_where_mentioned", "value": "" }, { "name": "resolved_topic_notice_auto_read_policy", "value": "" }, { "name": "presence_enabled", "value": "" }, { "name": "enter_sends", "value": "" }, { "name": "send_private_typing_notifications", "value": "" }, { "name": "send_stream_typing_notifications", "value": "" }, { "name": "send_read_receipts", "value": "" }, { "name": "allow_private_data_export", "value": "" }, { "name": "email_address_visibility", "value": "" }, { "name": "web_navigate_to_sent_message", "value": "" } ] } }, "docs": "This endpoint is used to edit the current user's settings.\n\nWhen invoked by a realm admin, it supports bulk updates to\nsettings for specified users or members of user groups using\nthe `target_users` parameter.\n\n**Changes**: Removed `dense_mode` setting in Zulip 10.0 (feature level 364)\nas we now have `web_font_size_px` and `web_line_height_percent`\nsettings for more control.\n\nPrior to Zulip 5.0 (feature level 80), this endpoint only\nsupported the `full_name`, `email`, `old_password`, and\n`new_pa" }, { "info": { "name": "Set \"typing\" status", "type": "http" }, "http": { "method": "POST", "url": "https://{subdomain}.zulipchat.com/api/v1/typing", "body": { "type": "form-urlencoded", "data": [ { "name": "type", "value": "" }, { "name": "op", "value": "" }, { "name": "to", "value": "" }, { "name": "stream_id", "value": "" }, { "name": "topic", "value": "" } ] } }, "docs": "Notify other users whether the current user is\n[typing a message][help-typing].\n\nClients implementing Zulip's typing notifications\nprotocol should work as follows:\n\n- Send a request to this endpoint with `\"op\": \"start\"` when a user\n starts composing a message.\n- While the user continues to actively type or otherwise interact with\n the compose UI (e.g. interacting with the compose box emoji picker),\n send regular `\"op\": \"start\"` requests to this endpoint, using\n `server_typing_started_wait_pe" }, { "info": { "name": "Set \"typing\" status for message editing", "type": "http" }, "http": { "method": "POST", "url": "https://{subdomain}.zulipchat.com/api/v1/messages/:message_id/typing", "params": [ { "name": "message_id", "value": "47", "type": "path", "description": "The target message's ID.\n" } ], "body": { "type": "form-urlencoded", "data": [ { "name": "op", "value": "" } ] } }, "docs": "Notify other users whether the current user is editing a message.\n\nTyping notifications for editing messages follow the same protocol as\n[set-typing-status](/api/set-typing-status), see that endpoint for\ndetails.\n\n**Changes**: Before Zulip 10.0 (feature level 361), the endpoint was\nnamed `/message_edit_typing` with `message_id` a required parameter in\nthe request body. Clients are recommended to start using sending these\ntyping notifications starting from this feature level.\n\nNew in Zulip 10.0 (" }, { "info": { "name": "Create a user group", "type": "http" }, "http": { "method": "POST", "url": "https://{subdomain}.zulipchat.com/api/v1/user_groups/create", "body": { "type": "form-urlencoded", "data": [ { "name": "name", "value": "" }, { "name": "description", "value": "" }, { "name": "members", "value": "" }, { "name": "subgroups", "value": "" }, { "name": "can_add_members_group", "value": "" }, { "name": "can_join_group", "value": "" }, { "name": "can_leave_group", "value": "" }, { "name": "can_manage_group", "value": "" }, { "name": "can_mention_group", "value": "" }, { "name": "can_remove_members_group", "value": "" } ] } }, "docs": "Create a new [user group](/help/user-groups).\n\n**Changes**: Prior to Zulip 12.0 (feature level 496), bot\nusers were not permitted to call this endpoint.\n" }, { "info": { "name": "Get user group members", "type": "http" }, "http": { "method": "GET", "url": "https://{subdomain}.zulipchat.com/api/v1/user_groups/:user_group_id/members", "params": [ { "name": "user_group_id", "value": "38", "type": "path", "description": "The ID of the target user group.\n" }, { "name": "direct_member_only", "value": "false", "type": "query", "description": "Whether to consider only the direct members of user group and not members\nof its subgroups. Default is `false`.\n" } ] }, "docs": "Get the members of a [user group](/help/user-groups).\n\n**Changes**: Prior to Zulip 12.0 (feature level 496), bot\nusers were not permitted to call this endpoint.\n\nNew in Zulip 6.0 (feature level 127).\n" }, { "info": { "name": "Update user group members", "type": "http" }, "http": { "method": "POST", "url": "https://{subdomain}.zulipchat.com/api/v1/user_groups/:user_group_id/members", "params": [ { "name": "user_group_id", "value": "38", "type": "path", "description": "The ID of the target user group.\n" } ], "body": { "type": "form-urlencoded", "data": [ { "name": "delete", "value": "" }, { "name": "add", "value": "" }, { "name": "delete_subgroups", "value": "" }, { "name": "add_subgroups", "value": "" } ] } }, "docs": "Update the members of a [user group](/help/user-groups). The\nuser IDs must correspond to non-deactivated users.\n\n**Changes**: Prior to Zulip 12.0 (feature level 496), bot\nusers were not permitted to call this endpoint.\n\nPrior to Zulip 11.0 (feature level 391), members\ncould not be added or removed from a deactivated group.\n\n**Changes**: Prior to Zulip 10.0 (feature level 303), group memberships of\ndeactivated users were visible to the API and could be edited via this endpoint.\n" }, { "info": { "name": "Update a user group", "type": "http" }, "http": { "method": "PATCH", "url": "https://{subdomain}.zulipchat.com/api/v1/user_groups/:user_group_id", "params": [ { "name": "user_group_id", "value": "38", "type": "path", "description": "The ID of the target user group.\n" } ], "body": { "type": "form-urlencoded", "data": [ { "name": "name", "value": "" }, { "name": "description", "value": "" }, { "name": "can_add_members_group", "value": "" }, { "name": "can_join_group", "value": "" }, { "name": "can_leave_group", "value": "" }, { "name": "can_manage_group", "value": "" }, { "name": "can_mention_group", "value": "" }, { "name": "can_remove_members_group", "value": "" }, { "name": "deactivated", "value": "" } ] } }, "docs": "Update the name, description or any of the permission settings\nof a [user group](/help/user-groups).\n\nThis endpoint is also used to reactivate a user group.\n\nNote that while permissions settings of deactivated groups can\nbe edited by this API endpoint, and those permissions settings\ndo affect the ability to modify the deactivated group and its\nmembership, the deactivated group itself cannot be mentioned\nor used in the value of any permission without first being reactivated.\n\n**Changes**: Prior t" }, { "info": { "name": "Get user groups", "type": "http" }, "http": { "method": "GET", "url": "https://{subdomain}.zulipchat.com/api/v1/user_groups", "body": { "type": "form-urlencoded", "data": [ { "name": "include_deactivated_groups", "value": "" } ] } }, "docs": "Fetches all of the user groups in the organization.\n\n!!! warn \"\"\n\n **Note**: This endpoint is not available to\n [guest users](/help/user-roles).\n\n**Changes**: Prior to Zulip 12.0 (feature level 496), bot\nusers were not permitted to call this endpoint.\n" }, { "info": { "name": "Get subgroups of a user group", "type": "http" }, "http": { "method": "GET", "url": "https://{subdomain}.zulipchat.com/api/v1/user_groups/:user_group_id/subgroups", "params": [ { "name": "user_group_id", "value": "38", "type": "path", "description": "The ID of the target user group.\n" }, { "name": "direct_subgroup_only", "value": "true", "type": "query", "description": "Whether to consider only direct subgroups of the user group\nor subgroups of subgroups also.\n" } ] }, "docs": "Get the subgroups of a [user group](/help/user-groups).\n\n**Changes**: Prior to Zulip 12.0 (feature level 496), bot\nusers were not permitted to call this endpoint.\n\nNew in Zulip 6.0 (feature level 127).\n" }, { "info": { "name": "Update subgroups of a user group", "type": "http" }, "http": { "method": "POST", "url": "https://{subdomain}.zulipchat.com/api/v1/user_groups/:user_group_id/subgroups", "params": [ { "name": "user_group_id", "value": "38", "type": "path", "description": "The ID of the target user group.\n" } ], "body": { "type": "form-urlencoded", "data": [ { "name": "delete", "value": "" }, { "name": "add", "value": "" } ] } }, "docs": "Update the subgroups of a [user group](/help/user-groups).\n\n**Changes**: Prior to Zulip 12.0 (feature level 496), bot\nusers were not permitted to call this endpoint.\n\nPrior to Zulip 11.0 (feature level 391), subgroups\ncould not be added or removed from a deactivated group.\n\nNew in Zulip 6.0 (feature level 127).\n" }, { "info": { "name": "Get user group membership status", "type": "http" }, "http": { "method": "GET", "url": "https://{subdomain}.zulipchat.com/api/v1/user_groups/:user_group_id/members/:user_id", "params": [ { "name": "user_group_id", "value": "38", "type": "path", "description": "The ID of the target user group.\n" }, { "name": "user_id", "value": "12", "type": "path", "description": "The target user's ID.\n" }, { "name": "direct_member_only", "value": "false", "type": "query", "description": "Whether to consider only the direct members of user group and not members\nof its subgroups. Default is `false`.\n" } ] }, "docs": "Check whether a user is member of user group.\n\n**Changes**: Prior to Zulip 12.0 (feature level 496), bot\nusers were not permitted to call this endpoint.\n\nPrior to Zulip 12.0 (feature level 458), this endpoint\ndid not support querying group membership of bot users.\n\nPrior to Zulip 10.0 (feature level 303),\nthis would return true when passed a deactivated user\nwho was a member of the user group before being deactivated.\n\nNew in Zulip 6.0 (feature level 127).\n" }, { "info": { "name": "Deactivate a user group", "type": "http" }, "http": { "method": "POST", "url": "https://{subdomain}.zulipchat.com/api/v1/user_groups/:user_group_id/deactivate", "params": [ { "name": "user_group_id", "value": "38", "type": "path", "description": "The ID of the target user group.\n" } ] }, "docs": "Deactivate a user group. Deactivated user groups cannot be\nused for mentions, permissions, or any other purpose, but can\nbe reactivated or renamed.\n\nDeactivating user groups is preferable to deleting them from\nthe database, since the deactivation model allows audit logs\nof changes to sensitive group-valued permissions to be\nmaintained.\n\n**Changes**: New in Zulip 10.0 (feature level 290).\n" }, { "info": { "name": "Get a bot's API key", "type": "http" }, "http": { "method": "GET", "url": "https://{subdomain}.zulipchat.com/api/v1/bots/:bot_id/api_key", "params": [ { "name": "bot_id", "value": "17", "type": "path", "description": "The user ID of the target bot.\n" } ] }, "docs": "Fetch the API key for a bot user. Only the bot's owner and\norganization administrators have access to a bot's API key.\n\n**Changes**: New in Zulip 12.0 (feature level 463).\n" }, { "info": { "name": "Regenerate a bot's API key", "type": "http" }, "http": { "method": "POST", "url": "https://{subdomain}.zulipchat.com/api/v1/bots/:bot_id/api_key/regenerate", "params": [ { "name": "bot_id", "value": "17", "type": "path", "description": "The user ID of the target bot.\n" } ] }, "docs": "Generate a new API key for a bot user. Only the bot's owner and\norganization administrators have access to a bot's API key.\n" } ] }, { "info": { "name": "bots", "type": "folder" }, "items": [ { "info": { "name": "Get a bot's stored data", "type": "http" }, "http": { "method": "GET", "url": "https://{subdomain}.zulipchat.com/api/v1/bot_storage", "params": [ { "name": "keys", "value": "", "type": "query", "description": "A JSON-encoded list of keys for data in the bot's storage.\n\nIf not provided, then all data that's stored for the bot is\nreturned.\n" } ] }, "docs": "!!! warn \"\"\n\n **Note:** This endpoint is only available to [bot user](/help/bots-overview)\n accounts.\n\nRetrieve [data stored](/help/interactive-bots-api#bot_handlerstorage)\nfor a bot user.\n\n**Changes**: Prior to Zulip 12.0 (feature level 494), users who\nwere not bots could access this endpoint.\n" }, { "info": { "name": "Update a bot's stored data", "type": "http" }, "http": { "method": "PUT", "url": "https://{subdomain}.zulipchat.com/api/v1/bot_storage", "body": { "type": "form-urlencoded", "data": [ { "name": "storage", "value": "" } ] } }, "docs": "!!! warn \"\"\n\n **Note:** This endpoint is only available to [bot user](/help/bots-overview)\n accounts.\n\nAdd or update [data stored](/help/interactive-bots-api#bot_handlerstorage)\nfor a bot user.\n\nEach bot has a limited storage set by the server, which normally is a\ndefault of 10,000,000 characters.\n\n**Changes**: Prior to Zulip 12.0 (feature level 494), users who\nwere not bots could access this endpoint.\n" }, { "info": { "name": "Remove a bot's stored data", "type": "http" }, "http": { "method": "DELETE", "url": "https://{subdomain}.zulipchat.com/api/v1/bot_storage", "body": { "type": "form-urlencoded", "data": [ { "name": "keys", "value": "" } ] } }, "docs": "!!! warn \"\"\n\n **Note:** This endpoint is only available to [bot user](/help/bots-overview)\n accounts.\n\nDelete [data stored](/help/interactive-bots-api#bot_handlerstorage)\nfor a bot user.\n\n**Changes**: Prior to Zulip 12.0 (feature level 494), users who\nwere not bots could access this endpoint.\n" } ] }, { "info": { "name": "drafts", "type": "folder" }, "items": [ { "info": { "name": "Get drafts", "type": "http" }, "http": { "method": "GET", "url": "https://{subdomain}.zulipchat.com/api/v1/drafts" }, "docs": "Fetch all drafts for the current user.\n" }, { "info": { "name": "Create drafts", "type": "http" }, "http": { "method": "POST", "url": "https://{subdomain}.zulipchat.com/api/v1/drafts", "body": { "type": "form-urlencoded", "data": [ { "name": "drafts", "value": "" } ] } }, "docs": "Create one or more drafts on the server. These drafts will be automatically\nsynchronized to other clients via `drafts` events.\n" }, { "info": { "name": "Edit a draft", "type": "http" }, "http": { "method": "PATCH", "url": "https://{subdomain}.zulipchat.com/api/v1/drafts/:draft_id", "params": [ { "name": "draft_id", "value": "2", "type": "path", "description": "The ID of the draft to be edited.\n" } ], "body": { "type": "form-urlencoded", "data": [ { "name": "draft", "value": "" } ] } }, "docs": "Edit a draft on the server. The edit will be automatically\nsynchronized to other clients via `drafts` events.\n" }, { "info": { "name": "Delete a draft", "type": "http" }, "http": { "method": "DELETE", "url": "https://{subdomain}.zulipchat.com/api/v1/drafts/:draft_id", "params": [ { "name": "draft_id", "value": "1", "type": "path", "description": "The ID of the draft you want to delete.\n" } ] }, "docs": "Delete a single draft from the server. The deletion will be automatically\nsynchronized to other clients via a `drafts` event.\n" }, { "info": { "name": "Get all saved snippets", "type": "http" }, "http": { "method": "GET", "url": "https://{subdomain}.zulipchat.com/api/v1/saved_snippets" }, "docs": "Fetch all the saved snippets for the current user.\n\n**Changes**: New in Zulip 10.0 (feature level 297).\n" }, { "info": { "name": "Create a saved snippet", "type": "http" }, "http": { "method": "POST", "url": "https://{subdomain}.zulipchat.com/api/v1/saved_snippets", "body": { "type": "form-urlencoded", "data": [ { "name": "title", "value": "" }, { "name": "content", "value": "" } ] } }, "docs": "Create a new saved snippet for the current user.\n\n**Changes**: New in Zulip 10.0 (feature level 297).\n" }, { "info": { "name": "Edit a saved snippet", "type": "http" }, "http": { "method": "PATCH", "url": "https://{subdomain}.zulipchat.com/api/v1/saved_snippets/:saved_snippet_id", "params": [ { "name": "saved_snippet_id", "value": "3", "type": "path", "description": "The ID of the saved snippet to edit.\n" } ], "body": { "type": "form-urlencoded", "data": [ { "name": "title", "value": "" }, { "name": "content", "value": "" } ] } }, "docs": "Edit a saved snippet for the current user.\n\n**Changes**: New in Zulip 10.0 (feature level 368).\n" }, { "info": { "name": "Delete a saved snippet", "type": "http" }, "http": { "method": "DELETE", "url": "https://{subdomain}.zulipchat.com/api/v1/saved_snippets/:saved_snippet_id", "params": [ { "name": "saved_snippet_id", "value": "2", "type": "path", "description": "The ID of the saved snippet to delete.\n" } ] }, "docs": "Delete a saved snippet.\n\n**Changes**: New in Zulip 10.0 (feature level 297).\n" } ] }, { "info": { "name": "navigation_views", "type": "folder" }, "items": [ { "info": { "name": "Get all navigation views", "type": "http" }, "http": { "method": "GET", "url": "https://{subdomain}.zulipchat.com/api/v1/navigation_views" }, "docs": "Fetch all configured custom navigation views for the current user.\n\n**Changes**: New in Zulip 11.0 (feature level 390).\n" }, { "info": { "name": "Add a navigation view", "type": "http" }, "http": { "method": "POST", "url": "https://{subdomain}.zulipchat.com/api/v1/navigation_views", "body": { "type": "form-urlencoded", "data": [] } }, "docs": "Adds a new custom left sidebar navigation view configuration\nfor the current user.\n\nThis can be used both to configure built-in navigation views,\nor to add new navigation views.\n\n**Changes**: New in Zulip 11.0 (feature level 390).\n" }, { "info": { "name": "Update the navigation view", "type": "http" }, "http": { "method": "PATCH", "url": "https://{subdomain}.zulipchat.com/api/v1/navigation_views/:fragment", "params": [ { "name": "fragment", "value": "narrow/is/alerted", "type": "path", "description": "The unique URL hash of the navigation view to be updated.\n\nThis also serves as the identifier for the navigation view.\n" } ], "body": { "type": "form-urlencoded", "data": [ { "name": "is_pinned", "value": "" }, { "name": "name", "value": "" } ] } }, "docs": "Update the details of an existing configured navigation view,\nsuch as its name or whether it's pinned.\n\n**Changes**: New in Zulip 11.0 (feature level 390).\n" }, { "info": { "name": "Remove a navigation view", "type": "http" }, "http": { "method": "DELETE", "url": "https://{subdomain}.zulipchat.com/api/v1/navigation_views/:fragment", "params": [ { "name": "fragment", "value": "narrow/is/alerted", "type": "path", "description": "The unique URL hash of the navigation view to be removed.\n\nThis also serves as the identifier for the navigation view.\n" } ] }, "docs": "Remove a navigation view.\n\n**Changes**: New in Zulip 11.0 (feature level 390).\n" } ] }, { "info": { "name": "reminders", "type": "folder" }, "items": [ { "info": { "name": "Get reminders", "type": "http" }, "http": { "method": "GET", "url": "https://{subdomain}.zulipchat.com/api/v1/reminders" }, "docs": "Fetch all [reminders](/help/schedule-a-reminder) for the\ncurrent user.\n\nReminders are messages the user has scheduled to be sent in the\nfuture to themself.\n\n**Changes**: New in Zulip 11.0 (feature level 399).\n" }, { "info": { "name": "Create a message reminder", "type": "http" }, "http": { "method": "POST", "url": "https://{subdomain}.zulipchat.com/api/v1/reminders", "body": { "type": "form-urlencoded", "data": [ { "name": "message_id", "value": "" }, { "name": "scheduled_delivery_timestamp", "value": "" }, { "name": "note", "value": "" } ] } }, "docs": "Schedule a reminder to be sent to the current user at the specified time. The reminder will link the relevant message.\n\n**Changes**: New in Zulip 11.0 (feature level 381).\n" }, { "info": { "name": "Delete a reminder", "type": "http" }, "http": { "method": "DELETE", "url": "https://{subdomain}.zulipchat.com/api/v1/reminders/:reminder_id", "params": [ { "name": "reminder_id", "value": "1", "type": "path", "description": "The ID of the reminder to delete.\n\nThis is different from the unique ID that the message would have\nafter being sent.\n" } ] }, "docs": "Delete, and therefore cancel sending, a previously [scheduled\nreminder](/help/schedule-a-reminder).\n\n**Changes**: New in Zulip 11.0 (feature level 399).\n" } ] }, { "info": { "name": "scheduled_messages", "type": "folder" }, "items": [ { "info": { "name": "Get scheduled messages", "type": "http" }, "http": { "method": "GET", "url": "https://{subdomain}.zulipchat.com/api/v1/scheduled_messages" }, "docs": "Fetch all [scheduled messages](/help/schedule-a-message) for\nthe current user.\n\nScheduled messages are messages the user has scheduled to be\nsent in the future via the send later feature.\n\n**Changes**: New in Zulip 7.0 (feature level 173).\n" }, { "info": { "name": "Create a scheduled message", "type": "http" }, "http": { "method": "POST", "url": "https://{subdomain}.zulipchat.com/api/v1/scheduled_messages", "body": { "type": "form-urlencoded", "data": [ { "name": "type", "value": "" }, { "name": "to", "value": "" }, { "name": "content", "value": "" }, { "name": "topic", "value": "" }, { "name": "scheduled_delivery_timestamp", "value": "" }, { "name": "read_by_sender", "value": "" } ] } }, "docs": "Create a new [scheduled message](/help/schedule-a-message).\n\n**Changes**: In Zulip 7.0 (feature level 184), moved support for\n[editing a scheduled message](/api/update-scheduled-message) to a\nseparate API endpoint, which removed the `scheduled_message_id`\nparameter from this endpoint.\n\nNew in Zulip 7.0 (feature level 179).\n" }, { "info": { "name": "Edit a scheduled message", "type": "http" }, "http": { "method": "PATCH", "url": "https://{subdomain}.zulipchat.com/api/v1/scheduled_messages/:scheduled_message_id", "params": [ { "name": "scheduled_message_id", "value": "2", "type": "path", "description": "The ID of the scheduled message to update.\n\nThis is different from the unique ID that the message would have\nafter being sent.\n" } ], "body": { "type": "form-urlencoded", "data": [ { "name": "type", "value": "" }, { "name": "to", "value": "" }, { "name": "content", "value": "" }, { "name": "topic", "value": "" }, { "name": "scheduled_delivery_timestamp", "value": "" } ] } }, "docs": "Edit an existing [scheduled message](/help/schedule-a-message).\n\n**Changes**: New in Zulip 7.0 (feature level 184).\n" }, { "info": { "name": "Delete a scheduled message", "type": "http" }, "http": { "method": "DELETE", "url": "https://{subdomain}.zulipchat.com/api/v1/scheduled_messages/:scheduled_message_id", "params": [ { "name": "scheduled_message_id", "value": "1", "type": "path", "description": "The ID of the scheduled message to delete.\n\nThis is different from the unique ID that the message would have\nafter being sent.\n" } ] }, "docs": "Delete, and therefore cancel sending, a previously [scheduled\nmessage](/help/schedule-a-message).\n\n**Changes**: New in Zulip 7.0 (feature level 173).\n" } ] }, { "info": { "name": "mobile", "type": "folder" }, "items": [ { "info": { "name": "Send a test notification to mobile device(s)", "type": "http" }, "http": { "method": "POST", "url": "https://{subdomain}.zulipchat.com/api/v1/mobile_push/test_notification", "body": { "type": "form-urlencoded", "data": [ { "name": "token", "value": "" } ] } }, "docs": "Trigger sending a test push notification to the user's\nselected mobile device or all of their mobile devices.\n\n**Changes**: Deprecated in Zulip 11.0 (feature level 420).\nClients connecting to newer servers and with E2EE push\nnotifications support should use the\n[Send an E2EE test notification to mobile device(s)](/api/e2ee-test-notify)\nendpoint, as this endpoint will be removed in a future release.\n\nStarting with Zulip 8.0 (feature level 234), test\nnotifications sent via this endpoint use `test`" }, { "info": { "name": "Send an E2EE test notification to mobile device(s)", "type": "http" }, "http": { "method": "POST", "url": "https://{subdomain}.zulipchat.com/api/v1/mobile_push/e2ee/test_notification", "body": { "type": "form-urlencoded", "data": [ { "name": "device_id", "value": "" } ] } }, "docs": "Trigger sending an end-to-end encrypted (E2EE) test push notification\nto the user's selected mobile device or all of their mobile devices.\n\n**Changes**: New in Zulip 11.0 (feature level 420).\n" }, { "info": { "name": "Register E2EE push device", "type": "http" }, "http": { "method": "POST", "url": "https://{subdomain}.zulipchat.com/api/v1/mobile_push/register", "body": { "type": "form-urlencoded", "data": [ { "name": "device_id", "value": "" }, { "name": "push_key_id", "value": "" }, { "name": "push_key", "value": "" }, { "name": "token_kind", "value": "" }, { "name": "token_id", "value": "" }, { "name": "bouncer_public_key", "value": "" }, { "name": "encrypted_push_registration", "value": "" } ] } }, "docs": "Register a device to receive end-to-end encrypted mobile push notifications,\nor update such a registration.\n\nTo perform an initial registration, clients must provide both the\npush key fields (`push_key` and `push_key_id`) and the token fields\n(`token_kind`, `token_id`, `bouncer_public_key`, and `encrypted_push_registration`).\n\nOnce registered, clients should use this endpoint to rotate `push_key` or\nFCM/APNs provided token:\n\n- **Rotate push key**: Provide only the push key fields.\n- **Rotate tok" }, { "info": { "name": "Register E2EE push device to bouncer", "type": "http" }, "http": { "method": "POST", "url": "https://{subdomain}.zulipchat.com/api/v1/remotes/push/e2ee/register", "body": { "type": "form-urlencoded", "data": [ { "name": "realm_uuid", "value": "" }, { "name": "token_id", "value": "" }, { "name": "encrypted_push_registration", "value": "" }, { "name": "bouncer_public_key", "value": "" } ] } }, "docs": "Register a push device to bouncer to receive end-to-end encrypted\nmobile push notifications.\n\nSelf-hosted servers use this endpoint to asynchronously register\na push device to the bouncer server after receiving a request from\nthe mobile client to [register E2EE push device](/api/register-push-device).\n\nIt is not meant to be used by mobile clients directly.\n\n**Changes**: New in Zulip 11.0 (feature level 406).\n" }, { "info": { "name": "Register a logged-in device", "type": "http" }, "http": { "method": "POST", "url": "https://{subdomain}.zulipchat.com/api/v1/register_client_device" }, "docs": "Logged-in mobile devices use this endpoint as an initial step to\nregister themselves, before registering for E2EE push notifications.\n\nThis endpoint is currently not useful for clients other than mobile.\n\n**Changes**: New in Zulip 12.0 (feature level 468).\n" }, { "info": { "name": "Remove a registered device", "type": "http" }, "http": { "method": "POST", "url": "https://{subdomain}.zulipchat.com/api/v1/remove_client_device", "body": { "type": "form-urlencoded", "data": [ { "name": "device_id", "value": "" } ] } }, "docs": "Mobile devices use this endpoint to remove their device record\nregistered using [`POST /register_client_device`](/api/register-client-device)\nwhen the user logs out.\n\nThis endpoint is currently not useful for clients other than mobile.\n\n**Changes**: New in Zulip 12.0 (feature level 470).\n" } ] }, { "info": { "name": "server_and_organizations", "type": "folder" }, "items": [ { "info": { "name": "Upload custom emoji", "type": "http" }, "http": { "method": "POST", "url": "https://{subdomain}.zulipchat.com/api/v1/realm/emoji/:emoji_name", "params": [ { "name": "emoji_name", "value": "smile", "type": "path", "description": "The name that should be associated with the uploaded emoji image/gif.\nThe emoji name can only contain letters, numbers, dashes, and spaces.\nUpper and lower case letters are treated the same, and underscores (\\_)\nare treated the same as spaces (consistent with how the Zulip UI\nhandles emoji).\n" } ], "body": { "type": "multipart-form", "data": [ { "name": "filename", "type": "text", "value": "" } ] } }, "docs": "This endpoint is used to upload a custom emoji for use in the user's\norganization. Access to this endpoint depends on the\n[organization's configuration](https://zulip.com/help/custom-emoji#change-who-can-add-custom-emoji).\n" }, { "info": { "name": "Deactivate custom emoji", "type": "http" }, "http": { "method": "DELETE", "url": "https://{subdomain}.zulipchat.com/api/v1/realm/emoji/:emoji_name", "params": [ { "name": "emoji_name", "value": "green_tick", "type": "path", "description": "The name of the custom emoji to deactivate.\n" } ] }, "docs": "[Deactivate a custom emoji](/help/custom-emoji#deactivate-custom-emoji) from\nthe user's organization.\n\nUsers can only deactivate custom emoji that they added themselves except for\norganization administrators, who can deactivate any custom emoji.\n\nNote that deactivated emoji will still be visible in old messages, reactions,\nuser statuses and channel descriptions.\n\n**Changes**: Before Zulip 8.0 (feature level 190), this endpoint returned an\nHTTP status code of 400 when the emoji did not exist, ins" }, { "info": { "name": "Get all custom emoji", "type": "http" }, "http": { "method": "GET", "url": "https://{subdomain}.zulipchat.com/api/v1/realm/emoji" }, "docs": "Get all the custom emoji in the user's organization.\n" }, { "info": { "name": "Get presence of all users", "type": "http" }, "http": { "method": "GET", "url": "https://{subdomain}.zulipchat.com/api/v1/realm/presence" }, "docs": "Get the presence information of all the users in an organization.\n\nIf the `CAN_ACCESS_ALL_USERS_GROUP_LIMITS_PRESENCE` server-level\nsetting is set to `true`, presence information of only accessible\nusers are returned.\n\nComplete Zulip apps are recommended to fetch presence\ninformation when they post their own state using the [`POST\n/presence`](/api/update-presence) API endpoint.\n" }, { "info": { "name": "Get allowed domains", "type": "http" }, "http": { "method": "GET", "url": "https://{subdomain}.zulipchat.com/api/v1/realm/domains" }, "docs": "Get the set of allowed domains configured in the organization for user\naccount email addresses.\n\nAs each Zulip user account is associated with an email address, organization\nowners can [restrict new account creation (and email\nchanges)](/help/restrict-account-creation) to email addresses with these\ndomains.\n" }, { "info": { "name": "Add an allowed domain", "type": "http" }, "http": { "method": "POST", "url": "https://{subdomain}.zulipchat.com/api/v1/realm/domains", "body": { "type": "form-urlencoded", "data": [ { "name": "domain", "value": "" }, { "name": "allow_subdomains", "value": "" } ] } }, "docs": "Add a domain to the set of allowed domains configured in the organization\nfor [user account email addresses](/help/restrict-account-creation).\n\n**Changes**: Prior to Zulip 6.0 (feature level 143), organization\nadministrators who were not owners could access this endpoint.\n" }, { "info": { "name": "Update an allowed domain", "type": "http" }, "http": { "method": "PATCH", "url": "https://{subdomain}.zulipchat.com/api/v1/realm/domains/:domain", "params": [ { "name": "domain", "value": "", "type": "path", "description": "The domain to update.\n" } ], "body": { "type": "form-urlencoded", "data": [ { "name": "allow_subdomains", "value": "" } ] } }, "docs": "Update whether subdomains are allowed in [user account email\naddresses](/help/restrict-account-creation) for the specified domain.\n\n**Changes**: Prior to Zulip 6.0 (feature level 143), organization\nadministrators who were not owners could access this endpoint.\n" }, { "info": { "name": "Remove an allowed domain", "type": "http" }, "http": { "method": "DELETE", "url": "https://{subdomain}.zulipchat.com/api/v1/realm/domains/:domain", "params": [ { "name": "domain", "value": "", "type": "path", "description": "The domain to remove.\n" } ] }, "docs": "Remove the specified domain from the set of allowed domains configured in\nthe organization for [user account email addresses](/help/restrict-account-creation).\n\n**Changes**: Prior to Zulip 6.0 (feature level 143), organization\nadministrators who were not owners could access this endpoint.\n" }, { "info": { "name": "Get all custom profile fields", "type": "http" }, "http": { "method": "GET", "url": "https://{subdomain}.zulipchat.com/api/v1/realm/profile_fields" }, "docs": "Get all the [custom profile fields](/help/custom-profile-fields)\nconfigured for the user's organization.\n" }, { "info": { "name": "Create a custom profile field", "type": "http" }, "http": { "method": "POST", "url": "https://{subdomain}.zulipchat.com/api/v1/realm/profile_fields", "body": { "type": "form-urlencoded", "data": [ { "name": "name", "value": "" }, { "name": "hint", "value": "" }, { "name": "field_type", "value": "" }, { "name": "field_data", "value": "" }, { "name": "display_in_profile_summary", "value": "" }, { "name": "required", "value": "" }, { "name": "editable_by_user", "value": "" }, { "name": "use_for_user_matching", "value": "" } ] } }, "docs": "[Create a custom profile field](/help/custom-profile-fields#add-a-custom-profile-field) in the user's organization.\n" }, { "info": { "name": "Reorder custom profile fields", "type": "http" }, "http": { "method": "PATCH", "url": "https://{subdomain}.zulipchat.com/api/v1/realm/profile_fields", "body": { "type": "form-urlencoded", "data": [ { "name": "order", "value": "" } ] } }, "docs": "Reorder the custom profile fields in the user's organization.\n\nCustom profile fields are displayed in Zulip UI widgets in order; this\nendpoint allows administrative settings UI to change the field ordering.\n\nThis endpoint is used to implement the dragging feature described in the\n[custom profile fields documentation](/help/custom-profile-fields).\n" }, { "info": { "name": "Update realm-level defaults of user settings", "type": "http" }, "http": { "method": "PATCH", "url": "https://{subdomain}.zulipchat.com/api/v1/realm/user_settings_defaults", "body": { "type": "form-urlencoded", "data": [ { "name": "starred_message_counts", "value": "" }, { "name": "receives_typing_notifications", "value": "" }, { "name": "web_suggest_update_timezone", "value": "" }, { "name": "fluid_layout_width", "value": "" }, { "name": "high_contrast_mode", "value": "" }, { "name": "web_mark_read_on_scroll_policy", "value": "" }, { "name": "web_channel_default_view", "value": "" }, { "name": "web_font_size_px", "value": "" }, { "name": "web_line_height_percent", "value": "" }, { "name": "color_scheme", "value": "" }, { "name": "enable_drafts_synchronization", "value": "" }, { "name": "translate_emoticons", "value": "" }, { "name": "display_emoji_reaction_users", "value": "" }, { "name": "web_home_view", "value": "" }, { "name": "web_escape_navigates_to_home_view", "value": "" }, { "name": "left_side_userlist", "value": "" }, { "name": "emojiset", "value": "" }, { "name": "demote_inactive_streams", "value": "" }, { "name": "user_list_style", "value": "" }, { "name": "web_animate_image_previews", "value": "" }, { "name": "web_stream_unreads_count_display_policy", "value": "" }, { "name": "hide_ai_features", "value": "" }, { "name": "web_inbox_show_channel_folders", "value": "" }, { "name": "web_left_sidebar_show_channel_folders", "value": "" }, { "name": "web_left_sidebar_unreads_count_summary", "value": "" }, { "name": "enable_stream_desktop_notifications", "value": "" }, { "name": "enable_stream_email_notifications", "value": "" }, { "name": "enable_stream_push_notifications", "value": "" }, { "name": "enable_stream_audible_notifications", "value": "" }, { "name": "notification_sound", "value": "" }, { "name": "enable_desktop_notifications", "value": "" }, { "name": "enable_sounds", "value": "" }, { "name": "enable_followed_topic_desktop_notifications", "value": "" }, { "name": "enable_followed_topic_email_notifications", "value": "" }, { "name": "enable_followed_topic_push_notifications", "value": "" }, { "name": "enable_followed_topic_audible_notifications", "value": "" }, { "name": "email_notifications_batching_period_seconds", "value": "" }, { "name": "enable_offline_email_notifications", "value": "" }, { "name": "enable_offline_push_notifications", "value": "" }, { "name": "enable_online_push_notifications", "value": "" }, { "name": "enable_digest_emails", "value": "" }, { "name": "message_content_in_email_notifications", "value": "" }, { "name": "pm_content_in_desktop_notifications", "value": "" }, { "name": "wildcard_mentions_notify", "value": "" }, { "name": "enable_followed_topic_wildcard_mentions_notify", "value": "" }, { "name": "desktop_icon_count_display", "value": "" }, { "name": "realm_name_in_email_notifications_policy", "value": "" }, { "name": "automatically_follow_topics_policy", "value": "" }, { "name": "automatically_unmute_topics_in_muted_streams_policy", "value": "" }, { "name": "automatically_follow_topics_where_mentioned", "value": "" }, { "name": "resolved_topic_notice_auto_read_policy", "value": "" }, { "name": "presence_enabled", "value": "" }, { "name": "enter_sends", "value": "" }, { "name": "twenty_four_hour_time", "value": "" }, { "name": "send_private_typing_notifications", "value": "" }, { "name": "send_stream_typing_notifications", "value": "" }, { "name": "send_read_receipts", "value": "" }, { "name": "email_address_visibility", "value": "" }, { "name": "web_navigate_to_sent_message", "value": "" } ] } }, "docs": "Change the [default values of settings][new-user-defaults] for new users\njoining the organization. Essentially all\n[personal preference settings](/api/update-settings) are supported.\n\nThis feature can be invaluable for customizing Zulip's default\nsettings for notifications or UI to be appropriate for how the\norganization is using Zulip. (Note that this only supports\npersonal preference settings, like when to send push\nnotifications or what emoji set to use, not profile or\nidentity settings that " }, { "info": { "name": "Get linkifiers", "type": "http" }, "http": { "method": "GET", "url": "https://{subdomain}.zulipchat.com/api/v1/realm/linkifiers" }, "docs": "List all of an organization's configured\n[linkifiers](/help/add-a-custom-linkifier), regular\nexpression patterns that are automatically linkified when they appear\nin messages and topics.\n\n**Changes**: New in Zulip 4.0 (feature level 54). On older versions,\na similar `GET /realm/filters` endpoint was available with each entry in\na `[pattern, url_format, id]` tuple format.\n" }, { "info": { "name": "Reorder linkifiers", "type": "http" }, "http": { "method": "PATCH", "url": "https://{subdomain}.zulipchat.com/api/v1/realm/linkifiers", "body": { "type": "form-urlencoded", "data": [ { "name": "ordered_linkifier_ids", "value": "" } ] } }, "docs": "Change the order that the regular expression patterns in the organization's\n[linkifiers](/help/add-a-custom-linkifier) are matched in messages and topics.\nUseful when defining linkifiers with overlapping patterns.\n\n**Changes**: New in Zulip 8.0 (feature level 202). Before this feature level,\nlinkifiers were always processed in order by ID, which meant users would\nneed to delete and recreate them to reorder the list of linkifiers.\n" }, { "info": { "name": "Add a linkifier", "type": "http" }, "http": { "method": "POST", "url": "https://{subdomain}.zulipchat.com/api/v1/realm/filters", "body": { "type": "form-urlencoded", "data": [ { "name": "pattern", "value": "" }, { "name": "url_template", "value": "" }, { "name": "example_input", "value": "" }, { "name": "reverse_template", "value": "" }, { "name": "alternative_url_templates", "value": "" } ] } }, "docs": "Configure [linkifiers](/help/add-a-custom-linkifier),\nregular expression patterns that are automatically linkified when they\nappear in messages and topics.\n" }, { "info": { "name": "Update a linkifier", "type": "http" }, "http": { "method": "PATCH", "url": "https://{subdomain}.zulipchat.com/api/v1/realm/filters/:filter_id", "params": [ { "name": "filter_id", "value": "5", "type": "path", "description": "The ID of the linkifier that you want to update.\n" } ], "body": { "type": "form-urlencoded", "data": [ { "name": "pattern", "value": "" }, { "name": "url_template", "value": "" }, { "name": "example_input", "value": "" }, { "name": "reverse_template", "value": "" }, { "name": "alternative_url_templates", "value": "" } ] } }, "docs": "Update a [linkifier](/help/add-a-custom-linkifier), regular\nexpression patterns that are automatically linkified when they appear\nin messages and topics.\n\n**Changes**: New in Zulip 4.0 (feature level 57).\n" }, { "info": { "name": "Remove a linkifier", "type": "http" }, "http": { "method": "DELETE", "url": "https://{subdomain}.zulipchat.com/api/v1/realm/filters/:filter_id", "params": [ { "name": "filter_id", "value": "43", "type": "path", "description": "The ID of the linkifier that you want to remove.\n" } ] }, "docs": "Remove [linkifiers](/help/add-a-custom-linkifier), regular\nexpression patterns that are automatically linkified when they appear\nin messages and topics.\n" }, { "info": { "name": "Add a code playground", "type": "http" }, "http": { "method": "POST", "url": "https://{subdomain}.zulipchat.com/api/v1/realm/playgrounds", "body": { "type": "form-urlencoded", "data": [ { "name": "name", "value": "" }, { "name": "pygments_language", "value": "" }, { "name": "url_template", "value": "" } ] } }, "docs": "Configure [code playgrounds](/help/code-blocks#code-playgrounds) for the organization.\n\n**Changes**: New in Zulip 4.0 (feature level 49). A parameter encoding bug was\nfixed in Zulip 4.0 (feature level 57).\n" }, { "info": { "name": "Remove a code playground", "type": "http" }, "http": { "method": "DELETE", "url": "https://{subdomain}.zulipchat.com/api/v1/realm/playgrounds/:playground_id", "params": [ { "name": "playground_id", "value": "1", "type": "path", "description": "The ID of the playground that you want to remove.\n" } ] }, "docs": "Remove a [code playground](/help/code-blocks#code-playgrounds) previously\nconfigured for an organization.\n\n**Changes**: New in Zulip 4.0 (feature level 49).\n" }, { "info": { "name": "Get all data exports", "type": "http" }, "http": { "method": "GET", "url": "https://{subdomain}.zulipchat.com/api/v1/export/realm" }, "docs": "Fetch all the public and standard [data exports][export-data]\nof the organization.\n\n**Changes**: Prior to Zulip 10.0 (feature level 304), only\npublic data exports could be fetched using this endpoint.\n\nNew in Zulip 2.1.\n\n[export-data]: /help/export-your-organization#export-data-in-an-importable-format\n" }, { "info": { "name": "Create a data export", "type": "http" }, "http": { "method": "POST", "url": "https://{subdomain}.zulipchat.com/api/v1/export/realm", "body": { "type": "form-urlencoded", "data": [ { "name": "export_type", "value": "" } ] } }, "docs": "Create a public or a standard [data export][export-data] of the organization.\n\n!!! warn \"\"\n\n **Note**: If you're the administrator of a self-hosted installation,\n you may be looking for the documentation on [server data export and\n import][data-export] or [server backups][backups].\n\n**Changes**: Prior to Zulip 10.0 (feature level 304), only\npublic data exports could be created using this endpoint.\n\nNew in Zulip 2.1.\n\n[export-data]: /help/export-your-organization#export-data-in-an-import" }, { "info": { "name": "Get data export consent state", "type": "http" }, "http": { "method": "GET", "url": "https://{subdomain}.zulipchat.com/api/v1/export/realm/consents" }, "docs": "Fetches which users have [consented](/help/export-your-organization#configure-whether-administrators-can-export-your-private-data)\nfor their private data to be exported by organization administrators.\n\n**Changes**: Changes in Zulip 12.0 (feature level 430). Added an\ninteger field `email_address_visibility` to the objects in the\n`export_consents` array.\n\nNew in Zulip 10.0 (feature level 295).\n" }, { "info": { "name": "Test welcome bot custom message", "type": "http" }, "http": { "method": "POST", "url": "https://{subdomain}.zulipchat.com/api/v1/realm/test_welcome_bot_custom_message", "body": { "type": "form-urlencoded", "data": [ { "name": "welcome_message_custom_text", "value": "" } ] } }, "docs": "Sends a test Welcome Bot custom message to the acting administrator.\nThis allows administrators to preview how the custom welcome message will\nappear when received by new users upon joining the organization.\n\n**Changes**: New in Zulip 11.0 (feature level 416).\n" }, { "info": { "name": "Get server settings", "type": "http" }, "http": { "method": "GET", "url": "https://{subdomain}.zulipchat.com/api/v1/server_settings" }, "docs": "Fetch global settings for a Zulip server.\n\n**Note:** this endpoint does not require any authentication at all, and you can use it to check:\n\n- If this is a Zulip server, and if so, what version of Zulip it's running.\n- What a Zulip client (e.g. a mobile app or\n [zulip-terminal](https://github.com/zulip/zulip-terminal/)) needs to\n know in order to display a login prompt for the server (e.g. what\n authentication methods are available).\n" } ] }, { "info": { "name": "invites", "type": "folder" }, "items": [ { "info": { "name": "Get all invitations", "type": "http" }, "http": { "method": "GET", "url": "https://{subdomain}.zulipchat.com/api/v1/invites" }, "docs": "Fetch all unexpired [invitations](/help/invite-new-users) (i.e. email\ninvitations and reusable invitation links) that can be managed by the user.\n\nNote that administrators can manage invitations that were created by other users.\n\n**Changes**: Prior to Zulip 8.0 (feature level 209), non-admin users could\nonly create email invitations, and therefore the response would never include\nreusable invitation links for these users.\n" }, { "info": { "name": "Send invitations", "type": "http" }, "http": { "method": "POST", "url": "https://{subdomain}.zulipchat.com/api/v1/invites", "body": { "type": "form-urlencoded", "data": [ { "name": "invitee_emails", "value": "" }, { "name": "invite_expires_in_minutes", "value": "" }, { "name": "invite_as", "value": "" }, { "name": "stream_ids", "value": "" }, { "name": "group_ids", "value": "" }, { "name": "include_realm_default_subscriptions", "value": "" }, { "name": "notify_referrer_on_join", "value": "" }, { "name": "welcome_message_custom_text", "value": "" } ] } }, "docs": "Send [invitations](/help/invite-new-users) to specified email addresses.\n\n**Changes**: In Zulip 6.0 (feature level 126), the `invite_expires_in_days`\nparameter was removed and replaced by `invite_expires_in_minutes`.\n\nIn Zulip 5.0 (feature level 117), added support for passing `null` as\nthe `invite_expires_in_days` parameter to request an invitation that never\nexpires.\n\nIn Zulip 5.0 (feature level 96), the `invite_expires_in_days` parameter was\nadded which specified the number of days before the" }, { "info": { "name": "Create a reusable invitation link", "type": "http" }, "http": { "method": "POST", "url": "https://{subdomain}.zulipchat.com/api/v1/invites/multiuse", "body": { "type": "form-urlencoded", "data": [ { "name": "invite_expires_in_minutes", "value": "" }, { "name": "invite_as", "value": "" }, { "name": "stream_ids", "value": "" }, { "name": "group_ids", "value": "" }, { "name": "include_realm_default_subscriptions", "value": "" }, { "name": "welcome_message_custom_text", "value": "" } ] } }, "docs": "Create a [reusable invitation link](/help/invite-new-users#create-a-reusable-invitation-link)\nwhich can be used to invite new users to the organization.\n\n**Changes**: In Zulip 8.0 (feature level 209), added support for non-admin\nusers [with permission](/help/restrict-account-creation#change-who-can-send-invitations)\nto use this endpoint. Previously, it was restricted to administrators only.\n\nIn Zulip 6.0 (feature level 126), the `invite_expires_in_days`\nparameter was removed and replaced by `inv" }, { "info": { "name": "Revoke an email invitation", "type": "http" }, "http": { "method": "DELETE", "url": "https://{subdomain}.zulipchat.com/api/v1/invites/:invite_id", "params": [ { "name": "invite_id", "value": "1", "type": "path", "description": "The ID of the email invitation to be revoked.\n" } ] }, "docs": "Revoke an [email invitation](/help/invite-new-users#send-email-invitations).\n\nA user can only revoke [invitations that they can\nmanage](/help/invite-new-users#manage-pending-invitations).\n" }, { "info": { "name": "Revoke a reusable invitation link", "type": "http" }, "http": { "method": "DELETE", "url": "https://{subdomain}.zulipchat.com/api/v1/invites/multiuse/:invite_id", "params": [ { "name": "invite_id", "value": "1", "type": "path", "description": "The ID of the reusable invitation link to be revoked.\n" } ] }, "docs": "Revoke a [reusable invitation link](/help/invite-new-users#create-a-reusable-invitation-link).\n\nA user can only revoke [invitations that they can\nmanage](/help/invite-new-users#manage-pending-invitations).\n\n**Changes**: Prior to Zulip 8.0 (feature level 209), only organization\nadministrators were able to create and revoke reusable invitation links.\n" }, { "info": { "name": "Resend an email invitation", "type": "http" }, "http": { "method": "POST", "url": "https://{subdomain}.zulipchat.com/api/v1/invites/:invite_id/resend", "params": [ { "name": "invite_id", "value": "1", "type": "path", "description": "The ID of the email invitation to be resent.\n" } ] }, "docs": "Resend an [email invitation](/help/invite-new-users#send-email-invitations).\n\nA user can only resend [invitations that they can\nmanage](/help/invite-new-users#manage-pending-invitations).\n" } ] }, { "info": { "name": "webhooks", "type": "folder" }, "items": [ { "info": { "name": "Outgoing webhooks", "type": "http" }, "http": { "method": "POST", "url": "https://{subdomain}.zulipchat.com/api/v1/zulip-outgoing-webhook" }, "docs": "Outgoing webhooks allow you to build or set up Zulip integrations which are\nnotified when certain types of messages are sent in Zulip.\n" } ] } ], "bundled": true }