This page documents the HTTP headers used by the Zulip API.
Full details of the HTTP requests are given in the curl example
on each endpoint's documentation page. You can access curl's
documentation at man curl.
Most important is that API clients authenticate to the server using
HTTP Basic authentication. If you're using the official Python or
JavaScript bindings, this is taken
care of when you configure said bindings.
Otherwise, to authenticate an API request:
-
Use HTTP Basic authentication, which is described here.
This means sending an HTTP header named Authorization, with your
credentials in a certain format.
-
For Basic authentication credentials in the Zulip API, a "username"
takes the form of an email address, and a "password" takes the form of
an API key. In the curl example for each endpoint, this is shown as:
-u BOT_EMAIL_ADDRESS:BOT_API_KEY.
-
A bot's credentials can be obtained through the web and desktop apps'
bot management UI or by downloading the bot's
zuliprc file.
-
See fetch an API key (production) for the
password-based authentication flow for getting a user's credentials.
Clients are not required to pass a User-Agent HTTP header, but we
highly recommend doing so when writing an integration. It's easy to do
and it can help save time when debugging issues related to an API
client.
If provided, the Zulip server will parse the User-Agent HTTP header
in order to identify specific clients and integrations. This
information is used by the server for logging, usage
statistics, and on rare occasions, for
backwards-compatibility logic to preserve support for older versions
of official clients.
Official Zulip clients and integrations use a User-Agent that starts
with something like ZulipMobile/20.0.103, encoding the name of the
application and it's version.
Zulip's official API bindings have reasonable defaults for
User-Agent. For example, the official Zulip Python bindings have a
default User-Agent starting with ZulipPython/{version}, where
version is the version of the library.
You can give your bot/integration its own name by passing the client
parameter when initializing the Python bindings. For example, the
official Zulip Nagios integration is initialized like this:
client = zulip.Client(
config_file=opts.config, client=f"ZulipNagios/{VERSION}"
)
If you are working on an integration that you plan to share outside
your organization, you can get help picking a good name in
#integrations in the Zulip development
community.
To help clients avoid exceeding rate limits, Zulip sets the following
HTTP headers in all API responses:
X-RateLimit-Remaining: The number of additional requests of this
type that the client can send before exceeding its limit.X-RateLimit-Limit: The limit that would be applicable to a client
that had not made any recent requests of this type. This is useful
for designing a client's burst behavior so as to avoid ever reaching
a rate limit.X-RateLimit-Reset: The time at which the client will no longer
have any rate limits applied to it (and thus could do a burst of
X-RateLimit-Limit requests).
Zulip's rate limiting rules are configurable,
and can vary by server and over time. The default configuration
currently limits:
- Every user is limited to 200 total API requests per minute.
- Separate, much lower limits for authentication/login attempts.
When the Zulip server has configured multiple rate limits that apply
to a given request, the values returned will be for the strictest
limit.