Zulip users API
The users API from Zulip — 29 operation(s) for users.
OpenAPI Specification
openapi: 3.0.1
info:
version: 1.0.0
title: Zulip REST authentication users API
description: 'Powerful open source group chat
'
contact:
url: https://zulip.com
license:
name: Apache 2.0
url: https://www.apache.org/licenses/LICENSE-2.0.html
servers:
- url: https://{subdomain}.zulipchat.com/api/v1
variables:
subdomain:
default: example
- url: '{server}/api/v1'
variables:
server:
default: https://
- url: https://chat.zulip.org/api/v1
- url: http://localhost:9991/api/v1
- url: http://{subdomain}.testserver/json
security:
- basicAuth: []
tags:
- name: users
paths:
/attachments:
get:
operationId: get-attachments
summary: Get attachments
tags:
- users
description: 'Fetch metadata on files uploaded by the requesting user.
'
responses:
'200':
description: Success.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/JsonSuccessBase'
- additionalProperties: false
properties:
result: {}
msg: {}
ignored_parameters_unsupported: {}
attachments:
type: array
description: 'A list of `attachment` objects, each containing
details about a file uploaded by the user.
'
items:
$ref: '#/components/schemas/Attachment'
upload_space_used:
type: integer
description: 'The total size of all files uploaded by users in the organization,
in bytes.
'
example:
result: success
msg: ''
attachments:
- id: 1
name: 166050.jpg
path_id: 2/ce/DfOkzwdg_IwlrN3myw3KGtiJ/166050.jpg
size: 571946
create_time: 1588145417
message_ids:
- 102
- 103
upload_space_used: 571946
/attachments/{attachment_id}:
delete:
operationId: remove-attachment
summary: Delete an attachment
tags:
- users
description: 'Delete an uploaded file given its attachment ID.
Note that uploaded files that have been referenced in at least
one message are automatically deleted once the last message
containing a link to them is deleted (whether directly or via
a [message retention policy](/help/message-retention-policy)).
Uploaded files that are never used in a message are
automatically deleted a few weeks after being uploaded.
Attachment IDs can be contained from [GET /attachments](/api/get-attachments).
'
parameters:
- name: attachment_id
in: path
description: 'The ID of the attachment to be deleted.
'
schema:
type: integer
example: 1
required: true
responses:
'200':
$ref: '#/components/responses/SimpleSuccess'
'400':
description: Bad request.
content:
application/json:
schema:
oneOf:
- allOf:
- $ref: '#/components/schemas/CodedError'
- example:
result: error
msg: Invalid attachment
code: BAD_REQUEST
description: 'A typical failed JSON response for when the `attachment_id` is invalid
'
'401':
description: Error.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/CodedError'
- example:
code: UNAUTHORIZED
result: error
msg: 'Not logged in: API authentication or user session required'
description: 'A typical failed JSON response for when the user is not logged in:
'
/users:
get:
operationId: get-users
summary: Get users
tags:
- users
description: 'Retrieve details on users in the organization.
By default, returns all accessible users in the organization.
The `user_ids` query parameter can be used to limit the
results to a specific set of user IDs.
Optionally includes values of [custom profile fields](/help/custom-profile-fields).
You can also [fetch details on a single user](/api/get-user).
**Changes**: In Zulip 12.0 (feature level 437), fixed a bug
dating to feature level 232, which caused guest users to
receive fake backwards-compatibility users in the format
intended for clients using `POST /register` without the
`user_list_incomplete` client capability.
This endpoint did not support unauthenticated
access in organizations using the [public access
option](/help/public-access-option) prior to Zulip 11.0
(feature level 387).
'
x-curl-examples-parameters:
oneOf:
- type: include
parameters:
enum:
- ''
- type: exclude
parameters:
enum:
- ''
description: 'You may pass the `client_gravatar` query parameter as follows:
'
parameters:
- $ref: '#/components/parameters/ClientGravatar'
- $ref: '#/components/parameters/IncludeCustomProfileFields'
- name: user_ids
in: query
content:
application/json:
schema:
type: array
items:
type: integer
example:
- 1
- 2
- 3
required: false
description: 'Limits the results to the specified user IDs. If not
provided, the server will return all accessible users in
the organization.
**Changes**: New in Zulip 11.0 (feature level 384).
'
responses:
'200':
description: Success.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/JsonSuccessBase'
- additionalProperties: false
properties:
result: {}
msg: {}
ignored_parameters_unsupported: {}
members:
type: array
description: 'A list of `user` objects, each containing details about a user in the
organization.
'
items:
$ref: '#/components/schemas/User'
example:
msg: ''
result: success
members:
- is_active: true
email: AARON@zulip.com
delivery_email: null
is_admin: false
is_owner: false
role: 400
avatar_url: https://secure.gravatar.com/avatar/818c212b9f8830dfef491b3f7da99a14?d=identicon&version=1
bot_type: null
timezone: ''
is_bot: false
user_id: 7
profile_data: {}
is_guest: false
date_joined: '2019-10-20T07:50:53.728864+00:00'
full_name: aaron
is_imported_stub: false
- date_joined: '2019-10-20T07:50:53.729659+00:00'
full_name: King Hamlet
is_guest: false
profile_data:
'4':
value: '0'
'2':
value: 'I am:
* The prince of Denmark
* Nephew to the usurping Claudius'
rendered_value: '<p>I am:</p>
<ul>
<li>The prince of Denmark</li>
<li>Nephew to the usurping Claudius</li>
</ul>'
'5':
value: '1900-01-01'
'7':
value: '[11]'
'6':
value: https://blog.zulig.org
'1':
value: +0-11-23-456-7890
rendered_value: <p>+0-11-23-456-7890</p>
'8':
value: zulipbot
'3':
rendered_value: <p>Dark chocolate</p>
value: Dark chocolate
user_id: 10
is_bot: false
bot_type: null
timezone: ''
is_admin: false
is_owner: false
role: 400
avatar_url: https://secure.gravatar.com/avatar/6d8cad0fd00256e7b40691d27ddfd466?d=identicon&version=1
is_active: true
email: hamlet@zulip.com
delivery_email: null
is_imported_stub: false
- bot_owner_id: 11
is_guest: false
date_joined: '2019-10-20T12:52:17.862053+00:00'
full_name: Iago's Bot
email: iago-bot@zulipdev.com
delivery_email: iago-bot@zulipdev.com
is_active: true
avatar_url: https://secure.gravatar.com/avatar/7328586831cdbb1627649bd857b1ee8c?d=identicon&version=1
is_admin: false
is_owner: false
role: 400
user_id: 23
bot_type: 1
timezone: ''
is_bot: true
is_imported_stub: false
post:
operationId: create-user
summary: Create a user
tags:
- users
description: "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 account using the `manage.py\n change_user_role` [management command][management-commands].\n\n**Changes**: Before Zulip 4.0 (feature level 36), this endpoint was\navailable to all organization administrators.\n\n[support]: /help/contact-support\n[management-commands]: https://zulip.readthedocs.io/en/latest/production/management-commands.html\n"
x-requires-administrator: true
requestBody:
required: true
content:
application/x-www-form-urlencoded:
schema:
type: object
properties:
email:
description: 'The email address of the new user.
'
type: string
example: username@example.com
password:
description: 'The password of the new user.
'
type: string
example: abcd1234
full_name:
description: 'The full name of the new user.
'
type: string
example: New User
required:
- email
- password
- full_name
responses:
'200':
description: Success.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/JsonSuccessBase'
- additionalProperties: false
properties:
result: {}
msg: {}
ignored_parameters_unsupported: {}
user_id:
type: integer
description: 'The ID assigned to the newly created user.
**Changes**: New in Zulip 4.0 (feature level 30).
'
example:
msg: ''
result: success
user_id: 25
'400':
description: Bad request.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/CodedError'
- example:
code: BAD_REQUEST
msg: Email is already in use.
result: error
description: 'A typical JSON response for when another user with the same
email address already exists in the realm:
'
/users/{user_id}/reactivate:
post:
operationId: reactivate-user
summary: Reactivate a user
tags:
- users
x-requires-administrator: true
description: '[Reactivates a
user](https://zulip.com/help/deactivate-or-reactivate-a-user)
given their user ID.
'
parameters:
- $ref: '#/components/parameters/UserId'
responses:
'200':
$ref: '#/components/responses/SimpleSuccess'
/users/{user_id}/status:
post:
operationId: update-status-for-user
summary: Update user status
tags:
- users
parameters:
- $ref: '#/components/parameters/UserId'
description: 'Administrator endpoint for changing the [status](/help/status-and-availability) of
another user.
**Changes**: Prior to Zulip 12.0 (feature level 473), only
bots could not access this API endpoint, regardless of the
role of the bot.
New in Zulip 11.0 (feature level 407).
'
x-requires-administrator: true
requestBody:
required: false
content:
application/x-www-form-urlencoded:
schema:
type: object
properties:
status_text:
type: string
description: 'The text content of the status message. Sending the empty string
will clear the user''s status.
**Note**: The limit on the size of the message is 60 Unicode code points.
'
example: on vacation
emoji_name:
type: string
description: 'The name for the emoji to associate with this status.
**Changes**: New in Zulip 5.0 (feature level 86).
'
example: car
emoji_code:
type: string
description: 'A unique identifier, defining the specific emoji codepoint requested,
within the namespace of the `reaction_type`.
**Changes**: New in Zulip 5.0 (feature level 86).
'
example: 1f697
reaction_type:
type: string
description: "A string indicating the type of emoji. Each emoji `reaction_type`\nhas an independent namespace for values of `emoji_code`.\n\nMust be one of the following values:\n\n- `unicode_emoji` : In this namespace, `emoji_code` will be a\n dash-separated hex encoding of the sequence of Unicode codepoints\n that define this emoji in the Unicode specification.\n\n- `realm_emoji` : In this namespace, `emoji_code` will be the ID of\n the uploaded [custom emoji](/help/custom-emoji).\n\n- `zulip_extra_emoji` : These are special emoji included with Zulip.\n In this namespace, `emoji_code` will be the name of the emoji (e.g.\n \"zulip\").\n\n**Changes**: New in Zulip 5.0 (feature level 86).\n"
example: unicode_emoji
responses:
'200':
$ref: '#/components/responses/SimpleSuccess'
'400':
description: Bad request.
content:
application/json:
schema:
oneOf:
- allOf:
- $ref: '#/components/schemas/CodedError'
- example:
result: error
msg: Insufficient permission
code: BAD_REQUEST
description: 'An example JSON error response user making request does not have permission to update other user''s status.:
'
- allOf:
- $ref: '#/components/schemas/CodedError'
- example:
result: error
msg: Client did not pass any new values.
code: BAD_REQUEST
description: 'An example JSON error response when no changes were requested:
'
- allOf:
- $ref: '#/components/schemas/CodedError'
- example:
result: error
msg: 'status_text is too long (limit: 60 characters)'
code: BAD_REQUEST
description: 'An example JSON error response when the
`status_text` message exceeds the limit of
60 characters:
'
- allOf:
- $ref: '#/components/schemas/CodedError'
- example:
result: error
msg: Client must pass emoji_name if they pass either emoji_code or reaction_type.
code: BAD_REQUEST
description: 'An example JSON error response when `emoji_name` is not specified
but `emoji_code` or `reaction_type` is specified:
'
- allOf:
- $ref: '#/components/schemas/CodedError'
- example:
result: error
msg: Emoji 'invalid' does not exist
code: BAD_REQUEST
description: 'An example JSON error response when the emoji name does not exist:
'
- allOf:
- $ref: '#/components/schemas/CodedError'
- example:
result: error
msg: Invalid emoji name.
code: BAD_REQUEST
description: 'An example JSON error response when the emoji name is invalid:
'
- allOf:
- $ref: '#/components/schemas/CodedError'
- example:
result: error
msg: Invalid custom emoji.
code: BAD_REQUEST
description: 'An example JSON error response when the custom emoji is invalid:
'
get:
operationId: get-user-status
summary: Get a user's status
tags:
- users
description: 'Get the [status](/help/status-and-availability) currently set by a
user in the organization.
**Changes**: New in Zulip 9.0 (feature level 262). Previously,
user statuses could only be fetched via the [`POST
/register`](/api/register-queue) endpoint.
'
parameters:
- $ref: '#/components/parameters/UserId'
responses:
'200':
description: Success.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/JsonSuccessBase'
- additionalProperties: false
properties:
result: {}
msg: {}
ignored_parameters_unsupported: {}
status:
allOf:
- description: 'The status set by the user. Note that, if the user doesn''t have a status
currently set, then the returned dictionary will be empty as none of the
keys listed below will be present.
'
- $ref: '#/components/schemas/UserStatus'
example:
result: success
msg: ''
status:
status_text: on vacation
emoji_name: car
emoji_code: 1f697
reaction_type: unicode_emoji
'400':
description: Success.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/CodedError'
- example:
result: error
msg: No such user
code: BAD_REQUEST
description: 'An example JSON error response when the user does not exist:
'
/users/{user_id_or_email}/presence:
get:
operationId: get-user-presence
summary: Get a user's presence
tags:
- users
description: 'Get the presence status for a specific user.
This endpoint is most useful for embedding data about a user''s
presence status in other sites (e.g. an employee directory). Full
Zulip clients like mobile/desktop apps will want to use the [main
presence endpoint](/api/get-presence), which returns data for all
active users in the organization, instead.
'
parameters:
- name: user_id_or_email
in: path
description: 'The ID or Zulip API email address of the user whose presence you want to fetch.
**Changes**: New in Zulip 4.0 (feature level 43). Previous versions only supported
identifying the user by Zulip API email.
'
schema:
type: string
example: iago@zulip.com
required: true
responses:
'200':
description: Success.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/JsonSuccessBase'
- additionalProperties: false
properties:
result: {}
msg: {}
ignored_parameters_unsupported: {}
server_timestamp:
type: number
description: 'The time when the server fetched the `presence` data
included in the response. Matches the similar field
in other presence responses.
**Changes**: New in Zulip 12.0 (feature level 497).
'
presence:
type: object
additionalProperties: false
description: 'An object containing the presence details for the user.
The object contains both the modern format fields
(`active_timestamp` and `idle_timestamp`) and the legacy
format fields (`website` and `aggregated` dictionaries,
which contain a timestamp and a status string). New
integrations should use the modern fields; the legacy
fields are retained for backwards compatibility.
**Changes**: In Zulip 12.0 (feature level 497),
the `website` and `aggregated` legacy dictionaries were
restored alongside the modern fields, for backwards
compatibility with integrations written against earlier
versions of the API.
In Zulip 12.0 (feature level 487), the `active_timestamp`
and `idle_timestamp` fields were added to this object, and
the `website` and `aggregated` dictionaries were
temporarily removed.
'
required:
- website
- aggregated
properties:
active_timestamp:
type: integer
description: 'The UNIX timestamp of the last time a client connected
to Zulip reported that the user was actually present.
'
idle_timestamp:
type: integer
description: 'The UNIX timestamp of the last time the user had a
client connected to Zulip, including idle clients.
'
website:
type: object
additionalProperties: false
description: 'Presence details for the user in the legacy format.
Starting with Zulip 7.0 (feature level 178), the
`website` and `aggregated` dictionaries always contain
identical data, since the server no longer stores which
client submitted presence updates.
'
properties:
status:
type: string
enum:
- idle
- active
description: 'The status of the user. Will be either `"idle"` or
`"active"`.
'
timestamp:
type: integer
description: 'The UNIX timestamp of when the user''s presence data
was last updated.
'
aggregated:
type: object
additionalProperties: false
description: 'Presence details for the user in the legacy format.
Unlike `website`, the `status` will be `"offline"` if
the most recent presence update is older than the
server''s offline threshold.
'
properties:
status:
type: string
enum:
- idle
- active
- offline
description: 'The status of the user. Will be either `"idle"`,
`"active"`, or `"offline"`.
'
timestamp:
type: integer
description: 'The UNIX timestamp of when the user''s presence data
was last updated.
'
example:
msg: ''
server_timestamp: 1656958540.123
presence:
active_timestamp: 1656958520
idle_timestamp: 1656958530
website:
status: active
timestamp: 1656958520
aggregated:
status: active
timestamp: 1656958520
result: success
/users/me:
get:
operationId: get-own-user
summary: Get own user
tags:
- users
description: 'Get basic data about the user/bot that requests this endpoint.
**Changes**: Removed `is_billing_admin` field in Zulip 10.0 (feature level 363), as it was
replaced by the `can_manage_billing_group` realm setting.
'
responses:
'200':
description: Success
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/JsonSuccessBase'
- additionalProperties: false
properties:
result: {}
msg: {}
ignored_parameters_unsupported: {}
avatar_url:
type: string
description: 'URL for the requesting user''s avatar.
**Changes**: New in Zulip 2.1.0.
'
example: x
avatar_version:
type: integer
description: 'Version for the requesting user''s avatar. Used for cache-busting requests
for the user''s avatar. Clients generally shouldn''t need to use this;
most avatar URLs sent by Zulip will already end with `?v={avatar_version}`.
**Changes**: New in Zulip 3.0 (feature level 10).
'
example: 1
email:
type: string
description: 'Zulip API email of the requesting user.
'
example: iago@zulip.com
full_name:
type: string
description: 'Full name of the requesting user.
'
example: Iago
is_admin:
type: boolean
description: 'A boolean indicating if the requesting user is an admin.
'
example: true
is_owner:
type: boolean
description: 'A boolean indicating if the requesting user is
an organization owner.
**Changes**: New in Zulip 3.0 (feature level 8).
'
example: false
role:
type: integer
enum:
- 100
- 200
- 300
- 400
- 600
description: '[Organization-level role](/api/roles-and-permissions) of
the requesting user.
Possible values are:
- 100 = Organization owner
- 200 = Organization administrator
- 300 = Organization moderator
- 400 = Member
- 600 = Guest
**Changes**: New in Zulip 4.0 (feature level 59).
'
is_guest:
type: boolean
description: 'A boolean indicating if the requesting user is a guest.
**Changes**: New in Zulip 3.0 (feature level 10).
'
example: false
is_bot:
type: boolean
description: 'A boolean indicating if the requesting user is a bot.
'
example: false
is_active:
type: boolean
description: 'A boolean specifying whether the requesting user account
has been deactivated.
**Changes**: New in Zulip 3.0 (feature level 10).
# --- truncated at 32 KB (223 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/zulip/refs/heads/main/openapi/zulip-users-api-openapi.yml