From 2794bc1ef4bec633d8cd2d831b04696d177927d6 Mon Sep 17 00:00:00 2001 From: Anders Kaseorg Date: Wed, 1 Jul 2020 12:19:49 -0700 Subject: [PATCH] lint: Reformat YAML files with Prettier. Signed-off-by: Anders Kaseorg --- .circleci/config.yml | 171 +- .github/workflows/codeql-analysis.yml | 36 +- tools/semgrep.yml | 2 +- zerver/openapi/testing.yaml | 243 +- zerver/openapi/zulip.yaml | 6319 ++++++++++++------------- 5 files changed, 3320 insertions(+), 3451 deletions(-) diff --git a/.circleci/config.yml b/.circleci/config.yml index ff75b97bd3..64cad52656 100644 --- a/.circleci/config.yml +++ b/.circleci/config.yml @@ -9,9 +9,9 @@ aliases: run: name: create cache directories command: | - dirs=(/srv/zulip-{npm,venv,emoji}-cache) - sudo mkdir -p "${dirs[@]}" - sudo chown -R circleci "${dirs[@]}" + dirs=(/srv/zulip-{npm,venv,emoji}-cache) + sudo mkdir -p "${dirs[@]}" + sudo chown -R circleci "${dirs[@]}" - &restore_cache_package_json restore_cache: @@ -32,24 +32,24 @@ aliases: run: name: install dependencies command: | - sudo apt-get update - # Install moreutils so we can use `ts` and `mispipe` in the following. - sudo apt-get install -y moreutils + sudo apt-get update + # Install moreutils so we can use `ts` and `mispipe` in the following. + sudo apt-get install -y moreutils - # CircleCI sets the following in Git config at clone time: - # url.ssh://git@github.com.insteadOf https://github.com - # This breaks the Git clones in the NVM `install.sh` we run - # in `install-node`. - # TODO: figure out why that breaks, and whether we want it. - # (Is it an optimization?) - rm -f /home/circleci/.gitconfig + # CircleCI sets the following in Git config at clone time: + # url.ssh://git@github.com.insteadOf https://github.com + # This breaks the Git clones in the NVM `install.sh` we run + # in `install-node`. + # TODO: figure out why that breaks, and whether we want it. + # (Is it an optimization?) + rm -f /home/circleci/.gitconfig - # This is the main setup job for the test suite - mispipe "tools/ci/setup-backend --skip-dev-db-build" ts + # This is the main setup job for the test suite + mispipe "tools/ci/setup-backend --skip-dev-db-build" ts - # Cleaning caches is mostly unnecessary in Circle, because - # most builds don't get to write to the cache. - # mispipe "scripts/lib/clean-unused-caches --verbose --threshold 0 2>&1" ts + # Cleaning caches is mostly unnecessary in Circle, because + # most builds don't get to write to the cache. + # mispipe "scripts/lib/clean-unused-caches --verbose --threshold 0 2>&1" ts - &save_cache_package_json save_cache: @@ -73,96 +73,96 @@ aliases: run: name: do Bionic hack command: | - # Temporary hack till `sudo service redis-server start` gets fixes in Bionic. See - # https://chat.zulip.org/#narrow/stream/3-backend/topic/Ubuntu.20bionic.20CircleCI - sudo sed -i '/^bind/s/bind.*/bind 0.0.0.0/' /etc/redis/redis.conf + # Temporary hack till `sudo service redis-server start` gets fixes in Bionic. See + # https://chat.zulip.org/#narrow/stream/3-backend/topic/Ubuntu.20bionic.20CircleCI + sudo sed -i '/^bind/s/bind.*/bind 0.0.0.0/' /etc/redis/redis.conf - &run_backend_tests run: name: run backend tests command: | - . /srv/zulip-py3-venv/bin/activate - mispipe "./tools/ci/backend 2>&1" ts + . /srv/zulip-py3-venv/bin/activate + mispipe "./tools/ci/backend 2>&1" ts - &run_frontend_tests run: name: run frontend tests command: | - . /srv/zulip-py3-venv/bin/activate - mispipe "./tools/ci/frontend 2>&1" ts + . /srv/zulip-py3-venv/bin/activate + mispipe "./tools/ci/frontend 2>&1" ts - &upload_coverage_report run: name: upload coverage report command: | - # codecov requires `.coverage` file to be stored in pwd for - # uploading coverage results. - mv /home/circleci/zulip/var/.coverage /home/circleci/zulip/.coverage + # codecov requires `.coverage` file to be stored in pwd for + # uploading coverage results. + mv /home/circleci/zulip/var/.coverage /home/circleci/zulip/.coverage - . /srv/zulip-py3-venv/bin/activate - # TODO: Check that the next release of codecov doesn't - # throw find error. - # codecov==2.0.16 introduced a bug which uses "find" - # for locating files which is buggy on some platforms. - # It was fixed via https://github.com/codecov/codecov-python/pull/217 - # and should get automatically fixed here once it's released. - # We cannot pin the version here because we need the latest version for uploading files. - # see https://community.codecov.io/t/http-400-while-uploading-to-s3-with-python-codecov-from-travis/1428/7 - pip install codecov && codecov \ - || echo "Error in uploading coverage reports to codecov.io." + . /srv/zulip-py3-venv/bin/activate + # TODO: Check that the next release of codecov doesn't + # throw find error. + # codecov==2.0.16 introduced a bug which uses "find" + # for locating files which is buggy on some platforms. + # It was fixed via https://github.com/codecov/codecov-python/pull/217 + # and should get automatically fixed here once it's released. + # We cannot pin the version here because we need the latest version for uploading files. + # see https://community.codecov.io/t/http-400-while-uploading-to-s3-with-python-codecov-from-travis/1428/7 + pip install codecov && codecov \ + || echo "Error in uploading coverage reports to codecov.io." - &build_production run: name: build production command: | - sudo apt-get update - # Install moreutils so we can use `ts` and `mispipe` in the following. - sudo apt-get install -y moreutils + sudo apt-get update + # Install moreutils so we can use `ts` and `mispipe` in the following. + sudo apt-get install -y moreutils - mispipe "./tools/ci/production-build 2>&1" ts + mispipe "./tools/ci/production-build 2>&1" ts - &production_extract_tarball run: name: production extract tarball command: | - sudo apt-get update - # Install moreutils so we can use `ts` and `mispipe` in the following. - sudo apt-get install -y moreutils + sudo apt-get update + # Install moreutils so we can use `ts` and `mispipe` in the following. + sudo apt-get install -y moreutils - mispipe "/tmp/production-extract-tarball 2>&1" ts + mispipe "/tmp/production-extract-tarball 2>&1" ts - &install_production run: name: install production command: | - sudo service rabbitmq-server restart - sudo mispipe "/tmp/production-install 2>&1" ts + sudo service rabbitmq-server restart + sudo mispipe "/tmp/production-install 2>&1" ts - &verify_production run: name: verify install command: | - sudo mispipe "/tmp/production-verify 2>&1" ts + sudo mispipe "/tmp/production-verify 2>&1" ts - &upgrade_postgresql run: name: upgrade postgresql command: | - sudo mispipe "/tmp/production-upgrade-pg 2>&1" ts + sudo mispipe "/tmp/production-upgrade-pg 2>&1" ts - &check_xenial_provision_error run: name: check tools/provision error message on xenial command: | - ! tools/provision > >(tee provision.out) - grep -Fqx 'CRITICAL:root:Unsupported platform: ubuntu 16.04' provision.out + ! tools/provision > >(tee provision.out) + grep -Fqx 'CRITICAL:root:Unsupported platform: ubuntu 16.04' provision.out - &check_xenial_upgrade_error run: name: check scripts/lib/upgrade-zulip-stage-2 error message on xenial command: | - ! sudo scripts/lib/upgrade-zulip-stage-2 2> >(tee upgrade.err >&2) - grep -Fq 'upgrade-zulip-stage-2: Unsupported platform: ubuntu 16.04' upgrade.err + ! sudo scripts/lib/upgrade-zulip-stage-2 2> >(tee upgrade.err >&2) + grep -Fq 'upgrade-zulip-stage-2: Unsupported platform: ubuntu 16.04' upgrade.err - ¬ify_failure_status run: @@ -171,11 +171,11 @@ aliases: branches: only: master command: | - if [[ "$CIRCLE_REPOSITORY_URL" == "git@github.com:zulip/zulip.git" && "$ZULIP_BOT_KEY" != "" ]]; then - curl -H "Content-Type: application/json" \ - -X POST -i 'https://chat.zulip.org/api/v1/external/circleci?api_key='"$ZULIP_BOT_KEY"'&stream=automated%20testing&topic=master%20failing' \ - -d '{"payload": { "branch": "'"$CIRCLE_BRANCH"'", "reponame": "'"$CIRCLE_PROJECT_REPONAME"'", "status": "failed", "build_url": "'"$CIRCLE_BUILD_URL"'", "username": "'"$CIRCLE_USERNAME"'"}}' - fi + if [[ "$CIRCLE_REPOSITORY_URL" == "git@github.com:zulip/zulip.git" && "$ZULIP_BOT_KEY" != "" ]]; then + curl -H "Content-Type: application/json" \ + -X POST -i 'https://chat.zulip.org/api/v1/external/circleci?api_key='"$ZULIP_BOT_KEY"'&stream=automated%20testing&topic=master%20failing' \ + -d '{"payload": { "branch": "'"$CIRCLE_BRANCH"'", "reponame": "'"$CIRCLE_PROJECT_REPONAME"'", "status": "failed", "build_url": "'"$CIRCLE_BUILD_URL"'", "username": "'"$CIRCLE_USERNAME"'"}}' + fi jobs: "bionic-backend-frontend": @@ -203,8 +203,8 @@ jobs: - run: name: test locked requirements command: | - . /srv/zulip-py3-venv/bin/activate - mispipe "./tools/test-locked-requirements 2>&1" ts + . /srv/zulip-py3-venv/bin/activate + mispipe "./tools/test-locked-requirements 2>&1" ts - *run_frontend_tests # We only need to upload coverage reports on whichever platform @@ -227,31 +227,30 @@ jobs: path: ./var/xunit-test-results/casper/ - *notify_failure_status - "focal-backend": - docker: - # This is built from tools/ci/images/focal/Dockerfile. - # Focal ships with Python 3.8.2. - - image: arpit551/circleci:focal-python-test + docker: + # This is built from tools/ci/images/focal/Dockerfile. + # Focal ships with Python 3.8.2. + - image: arpit551/circleci:focal-python-test - working_directory: ~/zulip + working_directory: ~/zulip - steps: - - checkout + steps: + - checkout - - *create_cache_directories - - *restore_cache_package_json - - *restore_cache_requirements - - *restore_emoji_cache - - *install_dependencies - - *save_cache_package_json - - *save_cache_requirements - - *save_emoji_cache - - *run_backend_tests - - run: - name: Check development database build - command: mispipe "tools/ci/setup-backend" ts - - *notify_failure_status + - *create_cache_directories + - *restore_cache_package_json + - *restore_cache_requirements + - *restore_emoji_cache + - *install_dependencies + - *save_cache_package_json + - *save_cache_requirements + - *save_emoji_cache + - *run_backend_tests + - run: + name: Check development database build + command: mispipe "tools/ci/setup-backend" ts + - *notify_failure_status "xenial-legacy": docker: @@ -351,9 +350,9 @@ jobs: - run: name: do memcached hack command: | - # Temporary hack till memcached upstream is updated in Focal. - # https://bugs.launchpad.net/ubuntu/+source/memcached/+bug/1878721 - echo "export SASL_CONF_PATH=/etc/sasl2" | sudo tee - a /etc/default/memcached + # Temporary hack till memcached upstream is updated in Focal. + # https://bugs.launchpad.net/ubuntu/+source/memcached/+bug/1878721 + echo "export SASL_CONF_PATH=/etc/sasl2" | sudo tee - a /etc/default/memcached - *production_extract_tarball - *restore_cache_package_json diff --git a/.github/workflows/codeql-analysis.yml b/.github/workflows/codeql-analysis.yml index 154ab821e4..74c5830dae 100644 --- a/.github/workflows/codeql-analysis.yml +++ b/.github/workflows/codeql-analysis.yml @@ -7,24 +7,24 @@ jobs: runs-on: ubuntu-latest steps: - - name: Checkout repository - uses: actions/checkout@v2 - with: - # We must fetch at least the immediate parents so that if this is - # a pull request then we can checkout the head. - fetch-depth: 2 + - name: Checkout repository + uses: actions/checkout@v2 + with: + # We must fetch at least the immediate parents so that if this is + # a pull request then we can checkout the head. + fetch-depth: 2 - # If this run was triggered by a pull request event, then checkout - # the head of the pull request instead of the merge commit. - - run: git checkout HEAD^2 - if: ${{ github.event_name == 'pull_request' }} + # If this run was triggered by a pull request event, then checkout + # the head of the pull request instead of the merge commit. + - run: git checkout HEAD^2 + if: ${{ github.event_name == 'pull_request' }} - # Initializes the CodeQL tools for scanning. - - name: Initialize CodeQL - uses: github/codeql-action/init@v1 - # Override language selection by uncommenting this and choosing your languages - # with: - # languages: go, javascript, csharp, python, cpp, java + # Initializes the CodeQL tools for scanning. + - name: Initialize CodeQL + uses: github/codeql-action/init@v1 - - name: Perform CodeQL Analysis - uses: github/codeql-action/analyze@v1 + # Override language selection by uncommenting this and choosing your languages + # with: + # languages: go, javascript, csharp, python, cpp, java + - name: Perform CodeQL Analysis + uses: github/codeql-action/analyze@v1 diff --git a/tools/semgrep.yml b/tools/semgrep.yml index 3384e4873c..5084aa3959 100644 --- a/tools/semgrep.yml +++ b/tools/semgrep.yml @@ -1,7 +1,7 @@ # See https://github.com/returntocorp/semgrep/blob/experimental/docs/config/advanced.md rules: -####################### PYTHON RULES ####################### + ####################### PYTHON RULES ####################### - id: deprecated-render-usage pattern: django.shortcuts.render_to_response(...) message: "Use render() (from django.shortcuts) instead of render_to_response()" diff --git a/zerver/openapi/testing.yaml b/zerver/openapi/testing.yaml index ebdaf0240d..7e5c4233d1 100644 --- a/zerver/openapi/testing.yaml +++ b/zerver/openapi/testing.yaml @@ -1,140 +1,115 @@ test1: responses: - '200': - content: - application/json: - schema: - additionalProperties: false - properties: - top_array: - type: array - items: - oneOf: - - type: object - properties: - obj: - oneOf: - - type: array - items: - type: string - - type: object - properties: - str3: - type: string - - type: array - items: - type: object - properties: - str1: - type: string - str2: - type: string - example: - { - "top_array": [ - { - "obj": { - "str3": "test" - } - }, - [ - { - "str1": "success", - "str2": "success" - } - ] - ] - } + "200": + content: + application/json: + schema: + additionalProperties: false + properties: + top_array: + type: array + items: + oneOf: + - type: object + properties: + obj: + oneOf: + - type: array + items: + type: string + - type: object + properties: + str3: + type: string + - type: array + items: + type: object + properties: + str1: + type: string + str2: + type: string + example: + { + "top_array": + [ + { "obj": { "str3": "test" } }, + [{ "str1": "success", "str2": "success" }], + ], + } test2: responses: - '200': - content: - application/json: - schema: - additionalProperties: false - properties: - top_array: - type: array - items: - oneOf: - - type: object - properties: - obj: - oneOf: - - type: array - items: - type: string - - type: object - additionalProperties: false - properties: - str3: - type: string - - type: array - items: - type: object - properties: - str1: - type: string - str2: - type: string - example: - { - "top_array": [ - { - "obj": { - "str3": "test", - "str4": "extraneous" - } - }, - [ - { - "str1": "success", - "str2": "success" - } - ] - ] - } + "200": + content: + application/json: + schema: + additionalProperties: false + properties: + top_array: + type: array + items: + oneOf: + - type: object + properties: + obj: + oneOf: + - type: array + items: + type: string + - type: object + additionalProperties: false + properties: + str3: + type: string + - type: array + items: + type: object + properties: + str1: + type: string + str2: + type: string + example: + { + "top_array": + [ + { "obj": { "str3": "test", "str4": "extraneous" } }, + [{ "str1": "success", "str2": "success" }], + ], + } test3: responses: - '200': - content: - application/json: - schema: - additionalProperties: false - properties: - top_array: - type: array - items: - oneOf: - - type: object - properties: - obj: - oneOf: - - type: array - items: - type: string - - type: object - - type: array - items: - type: object - properties: - str1: - type: string - str2: - type: string - example: - { - "top_array": [ - { - "obj": { - "str3": "test" - } - }, - [ - { - "str1": "success", - "str2": "success" - } - ] - ] - } + "200": + content: + application/json: + schema: + additionalProperties: false + properties: + top_array: + type: array + items: + oneOf: + - type: object + properties: + obj: + oneOf: + - type: array + items: + type: string + - type: object + - type: array + items: + type: object + properties: + str1: + type: string + str2: + type: string + example: + { + "top_array": + [ + { "obj": { "str3": "test" } }, + [{ "str1": "success", "str2": "success" }], + ], + } diff --git a/zerver/openapi/zulip.yaml b/zerver/openapi/zulip.yaml index cea10e0104..3513484cfc 100644 --- a/zerver/openapi/zulip.yaml +++ b/zerver/openapi/zulip.yaml @@ -19,20 +19,20 @@ info: name: Apache 2.0 url: https://www.apache.org/licenses/LICENSE-2.0.html servers: -# Zulip Cloud -- url: 'https://{subdomain}.zulipchat.com/api/v1' - variables: - subdomain: - default: example -# Self-hosted -- url: '{server}/api/v1' - variables: - server: - default: https:// -# chat.zulip.org -- url: 'https://chat.zulip.org/api/v1' -# Development server -- url: 'http://localhost:9991/api/v1' + # Zulip Cloud + - url: "https://{subdomain}.zulipchat.com/api/v1" + variables: + subdomain: + default: example + # Self-hosted + - url: "{server}/api/v1" + variables: + server: + default: https:// + # chat.zulip.org + - url: "https://chat.zulip.org/api/v1" + # Development server + - url: "http://localhost:9991/api/v1" security: - basicAuth: [] ####################### @@ -49,28 +49,28 @@ paths: Used to authenticate the mobile and terminal apps when the server has EmailAuthBackend or LDAPAuthBackend enabled. parameters: - - name: username - in: query - description: | - The username to be used for authentication (typically, the email - address, but it could be an LDAP username). - schema: - type: string - required: true - - name: password - in: query - schema: - type: string - description: | - The user's Zulip password (or LDAP password, if LDAP authentication is in use). - required: true + - name: username + in: query + description: | + The username to be used for authentication (typically, the email + address, but it could be an LDAP username). + schema: + type: string + required: true + - name: password + in: query + schema: + type: string + description: | + The user's Zulip password (or LDAP password, if LDAP authentication is in use). + required: true responses: - '200': + "200": description: The credentials needed to use the Zulip API. content: application/json: schema: - $ref: '#/components/schemas/ApiKeyResponse' + $ref: "#/components/schemas/ApiKeyResponse" /dev_fetch_api_key: post: operationId: dev_fetch_api_key @@ -88,22 +88,22 @@ paths: `POST {{ api_url }}/v1/dev_fetch_api_key` parameters: - - name: username - in: query - description: | - The email address for the user that owns the API key. - schema: - type: string - example: iago@zulip.com - required: true + - name: username + in: query + description: | + The email address for the user that owns the API key. + schema: + type: string + example: iago@zulip.com + required: true security: [] responses: - '200': + "200": description: Success. content: application/json: schema: - $ref: '#/components/schemas/ApiKeyResponse' + $ref: "#/components/schemas/ApiKeyResponse" /events: get: operationId: get_events @@ -114,119 +114,123 @@ paths: This endpoint allows you to receive new events from [a registered event queue](/api/register-queue). parameters: - - $ref: '#/components/parameters/QueueId' - - name: last_event_id - in: query - description: | - The highest event ID in this queue that you've received and - wish to acknowledge. See the [code for - `call_on_each_event`](https://github.com/zulip/python-zulip-api/blob/master/zulip/zulip/__init__.py) - in the [zulip Python - module](https://github.com/zulip/python-zulip-api) for an - example implementation of correctly processing each event - exactly once. - schema: - type: integer - example: -1 - - name: dont_block - in: query - description: | - Set to `true` if the client is requesting a nonblocking reply. If not - specified, the request will block until either a new event is available - or a few minutes have passed, in which case the server will send the - client a heartbeat event. - schema: - type: boolean - default: false - example: true + - $ref: "#/components/parameters/QueueId" + - name: last_event_id + in: query + description: | + The highest event ID in this queue that you've received and + wish to acknowledge. See the [code for + `call_on_each_event`](https://github.com/zulip/python-zulip-api/blob/master/zulip/zulip/__init__.py) + in the [zulip Python + module](https://github.com/zulip/python-zulip-api) for an + example implementation of correctly processing each event + exactly once. + schema: + type: integer + example: -1 + - name: dont_block + in: query + description: | + Set to `true` if the client is requesting a nonblocking reply. If not + specified, the request will block until either a new event is available + or a few minutes have passed, in which case the server will send the + client a heartbeat event. + schema: + type: boolean + default: false + example: true responses: - '200': + "200": description: Success. content: application/json: schema: allOf: - - $ref: '#/components/schemas/JsonSuccess' - - properties: - events: - type: array - description: | - An array of `event` objects (possibly zero-length if `dont_block` is - set) with IDs newer than `last_event_id`. Event IDs are - guaranteed to be increasing, but they are not guaranteed to be - consecutive. - items: - type: object - additionalProperties: false - queue_id: - type: string - description: | - The ID of the registered queue. - - example: - { + - $ref: "#/components/schemas/JsonSuccess" + - properties: + events: + type: array + description: | + An array of `event` objects (possibly zero-length if `dont_block` is + set) with IDs newer than `last_event_id`. Event IDs are + guaranteed to be increasing, but they are not guaranteed to be + consecutive. + items: + type: object + additionalProperties: false + queue_id: + type: string + description: | + The ID of the registered queue. + - example: + { "queue_id": "1375801870:2942", - "events": [ + "events": + [ { - "id": 0, - "message": { - "avatar_url": "https://url/for/othello-bots/avatar", - "client": "website", - "content": "I come not, friends, to steal away your hearts.", - "content_type": "text/x-markdown", - "display_recipient": "Denmark", - "id": 12345678, - "recipient_id": 12314, - "sender_email": "othello-bot@example.com", - "sender_full_name": "Othello Bot", - "sender_id": 13215, - "sender_realm_str": "example", - "sender_short_name": "othello-bot", - "topic": "Castle", - "topic_links": [], - "timestamp": 1375978403, - "type": "stream" + "id": 0, + "message": + { + "avatar_url": "https://url/for/othello-bots/avatar", + "client": "website", + "content": "I come not, friends, to steal away your hearts.", + "content_type": "text/x-markdown", + "display_recipient": "Denmark", + "id": 12345678, + "recipient_id": 12314, + "sender_email": "othello-bot@example.com", + "sender_full_name": "Othello Bot", + "sender_id": 13215, + "sender_realm_str": "example", + "sender_short_name": "othello-bot", + "topic": "Castle", + "topic_links": [], + "timestamp": 1375978403, + "type": "stream", }, - "type": "message" + "type": "message", }, { - "id": 1, - "message": { - "avatar_url": "https://url/for/othello-bots/avatar", - "client": "website", - "content": "With mirth and laughter let old wrinkles come.", - "content_type": "text/x-markdown", - "display_recipient": [ - { - "email": "hamlet@example.com", - "full_name": "Hamlet of Denmark", - "id": 31572, - "short_name": "hamlet" - } + "id": 1, + "message": + { + "avatar_url": "https://url/for/othello-bots/avatar", + "client": "website", + "content": "With mirth and laughter let old wrinkles come.", + "content_type": "text/x-markdown", + "display_recipient": + [ + { + "email": "hamlet@example.com", + "full_name": "Hamlet of Denmark", + "id": 31572, + "short_name": "hamlet", + }, ], - "id": 12345679, - "recipient_id": 18391, - "sender_email": "othello-bot@example.com", - "sender_full_name": "Othello Bot", - "sender_id": 13215, - "sender_realm_str": "example", - "sender_short_name": "othello-bot", - "subject": "", - "topic_links": [], - "timestamp": 1375978404, - "type": "private" + "id": 12345679, + "recipient_id": 18391, + "sender_email": "othello-bot@example.com", + "sender_full_name": "Othello Bot", + "sender_id": 13215, + "sender_realm_str": "example", + "sender_short_name": "othello-bot", + "subject": "", + "topic_links": [], + "timestamp": 1375978404, + "type": "private", }, - "type": "message" - } - ], + "type": "message", + }, + ], "msg": "", - "result": "success" - } - '400': + "result": "success", + } + "400": description: Bad request. content: application/json: schema: - $ref: '#/components/schemas/BadEventQueueIdError' + $ref: "#/components/schemas/BadEventQueueIdError" delete: operationId: delete_queue tags: ["real_time_events"] @@ -235,20 +239,20 @@ paths: `DELETE {{ api_url }}/v1/events` parameters: - - $ref: '#/components/parameters/QueueId' + - $ref: "#/components/parameters/QueueId" responses: - '200': + "200": description: Success. content: application/json: schema: - $ref: '#/components/schemas/JsonSuccess' - '400': + $ref: "#/components/schemas/JsonSuccess" + "400": description: Bad request. content: application/json: schema: - $ref: '#/components/schemas/BadEventQueueIdError' + $ref: "#/components/schemas/BadEventQueueIdError" /get_stream_id: get: operationId: get_stream_id @@ -258,40 +262,35 @@ paths: `GET {{ api_url }}/v1/get_stream_id` parameters: - - $ref: '#/components/parameters/Stream' - required: true + - $ref: "#/components/parameters/Stream" + required: true responses: - '200': + "200": description: Success. content: application/json: schema: allOf: - - $ref: '#/components/schemas/JsonSuccess' - - properties: - stream_id: - type: integer - description: | - The ID of the given stream. - - example: - { - "msg": "", - "result": "success", - "stream_id": 15 - } - '400': + - $ref: "#/components/schemas/JsonSuccess" + - properties: + stream_id: + type: integer + description: | + The ID of the given stream. + - example: { "msg": "", "result": "success", "stream_id": 15 } + "400": description: Bad request. content: application/json: schema: allOf: - - $ref: '#/components/schemas/CodedError' - - example: - { + - $ref: "#/components/schemas/CodedError" + - example: + { "code": "BAD_REQUEST", "msg": "Invalid stream name 'nonexistent'", - "result": "error" - } + "result": "error", + } /mark_all_as_read: post: operationId: mark_all_as_read @@ -301,12 +300,12 @@ paths: `POST {{ api_url }}/v1/mark_all_as_read` responses: - '200': + "200": description: Success. content: application/json: schema: - $ref: '#/components/schemas/JsonSuccess' + $ref: "#/components/schemas/JsonSuccess" /mark_stream_as_read: post: operationId: mark_stream_as_read @@ -314,15 +313,15 @@ paths: description: | Mark all the unread messages in a stream as read. parameters: - - $ref: '#/components/parameters/StreamIdInQuery' - required: true + - $ref: "#/components/parameters/StreamIdInQuery" + required: true responses: - '200': + "200": description: Success. content: application/json: schema: - $ref: '#/components/schemas/JsonSuccess' + $ref: "#/components/schemas/JsonSuccess" /mark_topic_as_read: post: operationId: mark_topic_as_read @@ -330,23 +329,23 @@ paths: description: | Mark all the unread messages in a topic as read. parameters: - - $ref: '#/components/parameters/StreamIdInQuery' - required: true - - name: topic_name - in: query - description: | - The name of the topic whose messages should be marked as read. - schema: - type: string - example: new coffee machine - required: true + - $ref: "#/components/parameters/StreamIdInQuery" + required: true + - name: topic_name + in: query + description: | + The name of the topic whose messages should be marked as read. + schema: + type: string + example: new coffee machine + required: true responses: - '200': + "200": description: Success. content: application/json: schema: - $ref: '#/components/schemas/JsonSuccess' + $ref: "#/components/schemas/JsonSuccess" /attachments: get: operationId: get_attachments @@ -356,106 +355,102 @@ paths: `GET {{ api_url }}/v1/attachments` responses: - '200': + "200": description: Success. content: application/json: schema: allOf: - - $ref: '#/components/schemas/JsonSuccess' - - properties: - attachments: - type: array - description: | - A list of `attachment` objects, each containing - details about a file uploaded by the user. - items: - type: object - additionalProperties: false - properties: - id: - type: integer - description: | - The unique ID for the attachment. - name: - type: string - description: | - Name of the uploaded file. - path_id: - type: string - description: | - A representation of the path of the file within the - repository of user-uploaded files. If the `path_id` of a - file is `{realm_id}/ab/cdef/temp_file.py`, its URL will be: - `{server_url}/user_uploads/{realm_id}/ab/cdef/temp_file.py`. - size: - type: integer - description: | - Size of the file in bytes. - create_time: - type: integer - description: | - Time when the attachment was uploaded as a UNIX timestamp - multiplied by 1000 (matching the format of getTime() in JavaScript). + - $ref: "#/components/schemas/JsonSuccess" + - properties: + attachments: + type: array + description: | + A list of `attachment` objects, each containing + details about a file uploaded by the user. + items: + type: object + additionalProperties: false + properties: + id: + type: integer + description: | + The unique ID for the attachment. + name: + type: string + description: | + Name of the uploaded file. + path_id: + type: string + description: | + A representation of the path of the file within the + repository of user-uploaded files. If the `path_id` of a + file is `{realm_id}/ab/cdef/temp_file.py`, its URL will be: + `{server_url}/user_uploads/{realm_id}/ab/cdef/temp_file.py`. + size: + type: integer + description: | + Size of the file in bytes. + create_time: + type: integer + description: | + Time when the attachment was uploaded as a UNIX timestamp + multiplied by 1000 (matching the format of getTime() in JavaScript). - **Changes**: Changed in Zulip 2.2 (feature level 22). This field was - previously a floating point number. - messages: - type: array - description: | - Contains basic details on any Zulip messages that have been - sent referencing this [uploaded file](/api/upload-file). - This includes messages sent by any user in the Zulip - organization who sent a message containing a link to the - uploaded file. - items: - type: object - additionalProperties: false - properties: - date_sent: - type: integer - description: | - Time when the message was sent as a UNIX timestamp - multiplied by 1000 (matching the format of getTime() in JavaScript). + **Changes**: Changed in Zulip 2.2 (feature level 22). This field was + previously a floating point number. + messages: + type: array + description: | + Contains basic details on any Zulip messages that have been + sent referencing this [uploaded file](/api/upload-file). + This includes messages sent by any user in the Zulip + organization who sent a message containing a link to the + uploaded file. + items: + type: object + additionalProperties: false + properties: + date_sent: + type: integer + description: | + Time when the message was sent as a UNIX timestamp + multiplied by 1000 (matching the format of getTime() in JavaScript). - **Changes**: Changed in Zulip 2.2 (feature level 22). This - field was previously strangely called `name` and was a floating - point number. - id: - type: integer - description: | - The unique message ID. Messages should always be - displayed sorted by ID. - upload_space_used: - type: integer - description: | - The total size of all files uploaded by in the organization, - in bytes. - - example: - { + **Changes**: Changed in Zulip 2.2 (feature level 22). This + field was previously strangely called `name` and was a floating + point number. + id: + type: integer + description: | + The unique message ID. Messages should always be + displayed sorted by ID. + upload_space_used: + type: integer + description: | + The total size of all files uploaded by in the organization, + in bytes. + - example: + { "result": "success", "msg": "", - "attachments": [ + "attachments": + [ { - "id": 1, - "name": "166050.jpg", - "path_id": "2/ce/DfOkzwdg_IwlrN3myw3KGtiJ/166050.jpg", - "size": 571946, - "create_time": 1588145417000, - "messages": [ - { - "id": 102, - "date_sent": 1588145424000 - }, - { - "id": 103, - "date_sent": 1588145448000 - } - ] - } - ], - "upload_space_used": 571946 - } + "id": 1, + "name": "166050.jpg", + "path_id": "2/ce/DfOkzwdg_IwlrN3myw3KGtiJ/166050.jpg", + "size": 571946, + "create_time": 1588145417000, + "messages": + [ + { "id": 102, "date_sent": 1588145424000 }, + { "id": 103, "date_sent": 1588145448000 }, + ], + }, + ], + "upload_space_used": 571946, + } /messages: get: operationId: get_messages @@ -490,219 +485,217 @@ paths: can be obtained per request; attempting to exceed this will result in an error. parameters: - - name: anchor - in: query - description: | - Integer message ID to anchor fetching of new messages. Supports special - string values for when the client wants the server to compute the anchor - to use: + - name: anchor + in: query + description: | + Integer message ID to anchor fetching of new messages. Supports special + string values for when the client wants the server to compute the anchor + to use: - * `newest`: The most recent message. - * `oldest`: The oldest message. - * `first_unread`: The oldest unread message matching the - query, if any; otherwise, the most recent message. + * `newest`: The most recent message. + * `oldest`: The oldest message. + * `first_unread`: The oldest unread message matching the + query, if any; otherwise, the most recent message. - The special values of `'newest'` and `'oldest'` are also supported - for anchoring the query at the most recent or oldest messages. + The special values of `'newest'` and `'oldest'` are also supported + for anchoring the query at the most recent or oldest messages. - **Changes**: String values are new in Zulip 3.0 (feature level 1). The - `first_unread` functionality was supported in Zulip 2.1.x - and older by not sending anchor and using use_first_unread_anchor. + **Changes**: String values are new in Zulip 3.0 (feature level 1). The + `first_unread` functionality was supported in Zulip 2.1.x + and older by not sending anchor and using use_first_unread_anchor. - In Zulip 2.1.x and older, `oldest` can be emulated with - `anchor=0`, and `newest` with `anchor=10000000000000000` - (that specific large value works around a bug in Zulip - 2.1.x and older in the `found_newest` return value). - schema: - oneOf: - - type: string - - type: integer - example: 42 - - name: num_before - in: query - description: | - The number of messages with IDs less than the anchor to retrieve. - schema: - type: integer - minimum: 0 - example: 4 - required: true - - name: num_after - in: query - description: | - The number of messages with IDs greater than the anchor to retrieve. - schema: - type: integer - minimum: 0 - example: 8 - required: true - - name: narrow - in: query - description: | - The narrow where you want to fetch the messages from. See how to - [construct a narrow](/api/construct-narrow). - content: - application/json: - schema: - type: array - items: - type: object - default: [] - example: [{"operand": "Denmark", "operator": "stream"}] - - $ref: '#/components/parameters/ClientGravatar' - - name: apply_markdown - in: query - description: | - If `true`, message content is returned in the rendered HTML - format. If `false`, message content is returned in the raw - markdown-format text that user entered. - schema: - type: boolean - default: true - example: false - - name: use_first_unread_anchor - in: query - deprecated: true - description: | - Legacy way to specify `anchor="first_unread"` in Zulip 2.1.x and older. + In Zulip 2.1.x and older, `oldest` can be emulated with + `anchor=0`, and `newest` with `anchor=10000000000000000` + (that specific large value works around a bug in Zulip + 2.1.x and older in the `found_newest` return value). + schema: + oneOf: + - type: string + - type: integer + example: 42 + - name: num_before + in: query + description: | + The number of messages with IDs less than the anchor to retrieve. + schema: + type: integer + minimum: 0 + example: 4 + required: true + - name: num_after + in: query + description: | + The number of messages with IDs greater than the anchor to retrieve. + schema: + type: integer + minimum: 0 + example: 8 + required: true + - name: narrow + in: query + description: | + The narrow where you want to fetch the messages from. See how to + [construct a narrow](/api/construct-narrow). + content: + application/json: + schema: + type: array + items: + type: object + default: [] + example: [{ "operand": "Denmark", "operator": "stream" }] + - $ref: "#/components/parameters/ClientGravatar" + - name: apply_markdown + in: query + description: | + If `true`, message content is returned in the rendered HTML + format. If `false`, message content is returned in the raw + markdown-format text that user entered. + schema: + type: boolean + default: true + example: false + - name: use_first_unread_anchor + in: query + deprecated: true + description: | + Legacy way to specify `anchor="first_unread"` in Zulip 2.1.x and older. - Whether to use the (computed by the server) first unread message - matching the narrow as the `anchor`. Mutually exclusive with `anchor`. + Whether to use the (computed by the server) first unread message + matching the narrow as the `anchor`. Mutually exclusive with `anchor`. - **Changes**: Deprecated in Zulip 3.0, replaced by - `anchor="first_unread"` instead. - schema: - type: boolean - default: false - example: true + **Changes**: Deprecated in Zulip 3.0, replaced by + `anchor="first_unread"` instead. + schema: + type: boolean + default: false + example: true responses: - '200': + "200": description: Success. content: application/json: schema: allOf: - - $ref: '#/components/schemas/JsonSuccess' - - properties: - anchor: - type: integer - description: | - The same `anchor` specified in the request (or the computed one, if - `use_first_unread_anchor` is `true`). - found_newest: - type: boolean - description: | - Whether the `messages` list includes the very newest messages matching - the narrow (used by clients that paginate their requests to decide - whether there are more messages to fetch). - found_oldest: - type: boolean - description: | - Whether the `messages` list includes the very oldest messages matching - the narrow (used by clients that paginate their requests to decide - whether there are more messages to fetch). - found_anchor: - type: boolean - description: | - Whether the anchor message is included in the - response. If the message with the ID specified - in the request does not exist or did not match - the narrow, this will be false. - history_limited: - type: boolean - description: | - Whether the message history was limited due to - plan restrictions. This flag is set to `true` - only when the oldest messages(`found_oldest`) - matching the narrow is fetched. - messages: - type: array - description: | - an array of `message` objects, each containing the following - fields: - items: - $ref: '#/components/schemas/Messages' - - example: - { + - $ref: "#/components/schemas/JsonSuccess" + - properties: + anchor: + type: integer + description: | + The same `anchor` specified in the request (or the computed one, if + `use_first_unread_anchor` is `true`). + found_newest: + type: boolean + description: | + Whether the `messages` list includes the very newest messages matching + the narrow (used by clients that paginate their requests to decide + whether there are more messages to fetch). + found_oldest: + type: boolean + description: | + Whether the `messages` list includes the very oldest messages matching + the narrow (used by clients that paginate their requests to decide + whether there are more messages to fetch). + found_anchor: + type: boolean + description: | + Whether the anchor message is included in the + response. If the message with the ID specified + in the request does not exist or did not match + the narrow, this will be false. + history_limited: + type: boolean + description: | + Whether the message history was limited due to + plan restrictions. This flag is set to `true` + only when the oldest messages(`found_oldest`) + matching the narrow is fetched. + messages: + type: array + description: | + an array of `message` objects, each containing the following + fields: + items: + $ref: "#/components/schemas/Messages" + - example: + { "anchor": 21, "found_newest": true, "found_anchor": true, "result": "success", "msg": "", - "messages": [ + "messages": + [ { - "subject": "", - "sender_realm_str": "zulip", - "type": "private", - "content": "

Security experts agree that relational algorithms are an interesting new topic in the field of networking, and scholars concur.

", - "flags": [ - "read" + "subject": "", + "sender_realm_str": "zulip", + "type": "private", + "content": "

Security experts agree that relational algorithms are an interesting new topic in the field of networking, and scholars concur.

", + "flags": ["read"], + "id": 16, + "display_recipient": + [ + { + "short_name": "hamlet", + "id": 4, + "is_mirror_dummy": false, + "email": "hamlet@zulip.com", + "full_name": "King Hamlet", + }, + { + "short_name": "iago", + "id": 5, + "is_mirror_dummy": false, + "email": "iago@zulip.com", + "full_name": "Iago", + }, + { + "short_name": "prospero", + "id": 8, + "is_mirror_dummy": false, + "email": "prospero@zulip.com", + "full_name": "Prospero from The Tempest", + }, ], - "id": 16, - "display_recipient": [ - { - "short_name": "hamlet", - "id": 4, - "is_mirror_dummy": false, - "email": "hamlet@zulip.com", - "full_name": "King Hamlet" - }, - { - "short_name": "iago", - "id": 5, - "is_mirror_dummy": false, - "email": "iago@zulip.com", - "full_name": "Iago" - }, - { - "short_name": "prospero", - "id": 8, - "is_mirror_dummy": false, - "email": "prospero@zulip.com", - "full_name": "Prospero from The Tempest" - } - ], - "content_type": "text/html", - "is_me_message": false, - "sender_short_name": "hamlet", - "timestamp": 1527921326, - "sender_id": 4, - "sender_full_name": "King Hamlet", - "recipient_id": 27, - "topic_links": [], - "client": "populate_db", - "avatar_url": "https://secure.gravatar.com/avatar/6d8cad0fd00256e7b40691d27ddfd466?d=identicon&version=1", - "submessages": [], - "sender_email": "hamlet@zulip.com", - "reactions": [] + "content_type": "text/html", + "is_me_message": false, + "sender_short_name": "hamlet", + "timestamp": 1527921326, + "sender_id": 4, + "sender_full_name": "King Hamlet", + "recipient_id": 27, + "topic_links": [], + "client": "populate_db", + "avatar_url": "https://secure.gravatar.com/avatar/6d8cad0fd00256e7b40691d27ddfd466?d=identicon&version=1", + "submessages": [], + "sender_email": "hamlet@zulip.com", + "reactions": [], }, { - "subject": "Verona3", - "stream_id": 5, - "sender_realm_str": "zulip", - "type": "stream", - "content": "

Wait, is this from the frontend js code or backend python code

", - "flags": [ - "read" - ], - "id": 21, - "display_recipient": "Verona", - "content_type": "text/html", - "is_me_message": false, - "sender_short_name": "hamlet", - "timestamp": 1527939746, - "sender_id": 4, - "sender_full_name": "King Hamlet", - "recipient_id": 20, - "topic_links": [], - "client": "populate_db", - "avatar_url": "https://secure.gravatar.com/avatar/6d8cad0fd00256e7b40691d27ddfd466?d=identicon&version=1", - "submessages": [], - "sender_email": "hamlet@zulip.com", - "reactions": [] - } - ] - } + "subject": "Verona3", + "stream_id": 5, + "sender_realm_str": "zulip", + "type": "stream", + "content": "

Wait, is this from the frontend js code or backend python code

", + "flags": ["read"], + "id": 21, + "display_recipient": "Verona", + "content_type": "text/html", + "is_me_message": false, + "sender_short_name": "hamlet", + "timestamp": 1527939746, + "sender_id": 4, + "sender_full_name": "King Hamlet", + "recipient_id": 20, + "topic_links": [], + "client": "populate_db", + "avatar_url": "https://secure.gravatar.com/avatar/6d8cad0fd00256e7b40691d27ddfd466?d=identicon&version=1", + "submessages": [], + "sender_email": "hamlet@zulip.com", + "reactions": [], + }, + ], + } post: operationId: send_message tags: ["messages"] @@ -711,102 +704,97 @@ paths: `POST {{ api_url }}/v1/messages` parameters: - - name: type - in: query - description: | - The type of message to be sent. `private` for a private message and - `stream` for a stream message. - schema: - type: string - enum: - - private - - stream - example: private - required: true - - name: to - in: query - description: | - For stream messages, either the name or integer ID of the stream. For - private messages, either a list containing integer user IDs or a list - containing string email addresses. + - name: type + in: query + description: | + The type of message to be sent. `private` for a private message and + `stream` for a stream message. + schema: + type: string + enum: + - private + - stream + example: private + required: true + - name: to + in: query + description: | + For stream messages, either the name or integer ID of the stream. For + private messages, either a list containing integer user IDs or a list + containing string email addresses. - **Changes**: Support for using user/stream IDs was added in Zulip 2.0.0. - content: - application/json: - schema: - type: array - items: - type: integer - example: [9, 10] - required: true - - $ref: '#/components/parameters/RequiredContent' - - $ref: '#/components/parameters/Topic' - - name: queue_id - in: query - schema: - type: string - description: | - For clients supporting - [local echo](https://zulip.readthedocs.io/en/latest/subsystems/sending-messages.html#local-echo), - the [event queue](/api/register-queue) - ID for the client. If passed, `local_id` is required. If the message is - successfully sent, the server will include `local_id` in the `message` event - that the client with this `queue_id` will receive notifying it of the new message - via [`GET /events`](/api/get-events). This lets the client know unambiguously - that it should replace the locally echoed message, rather than adding this new - message (which would be correct if the user had sent the new message from another - device). - example: "1593114627:0" - - name: local_id - in: query - schema: - type: string - description: | - For clients supporting local echo, a unique string-format identifier - chosen freely by the client; the server will pass it back to the client without - inspecting it, as described in the `queue_id` description. - example: "100.01" + **Changes**: Support for using user/stream IDs was added in Zulip 2.0.0. + content: + application/json: + schema: + type: array + items: + type: integer + example: [9, 10] + required: true + - $ref: "#/components/parameters/RequiredContent" + - $ref: "#/components/parameters/Topic" + - name: queue_id + in: query + schema: + type: string + description: | + For clients supporting + [local echo](https://zulip.readthedocs.io/en/latest/subsystems/sending-messages.html#local-echo), + the [event queue](/api/register-queue) + ID for the client. If passed, `local_id` is required. If the message is + successfully sent, the server will include `local_id` in the `message` event + that the client with this `queue_id` will receive notifying it of the new message + via [`GET /events`](/api/get-events). This lets the client know unambiguously + that it should replace the locally echoed message, rather than adding this new + message (which would be correct if the user had sent the new message from another + device). + example: "1593114627:0" + - name: local_id + in: query + schema: + type: string + description: | + For clients supporting local echo, a unique string-format identifier + chosen freely by the client; the server will pass it back to the client without + inspecting it, as described in the `queue_id` description. + example: "100.01" responses: - '200': + "200": description: Success. content: application/json: schema: allOf: - - $ref: '#/components/schemas/JsonSuccess' - - properties: - id: - type: integer - description: | - The unique ID assigned to the sent message. - deliver_at: - type: string - description: | - Present for scheduled messages, encodes the time when the message will - be sent. Note that scheduled messages ("Send later") is a beta API and - may change before it's a finished feature. - example: "2020-06-24 11:19:54.337533+00:00" - - example: - { - "msg": "", - "id": 42, - "result": "success" - } - '400': + - $ref: "#/components/schemas/JsonSuccess" + - properties: + id: + type: integer + description: | + The unique ID assigned to the sent message. + deliver_at: + type: string + description: | + Present for scheduled messages, encodes the time when the message will + be sent. Note that scheduled messages ("Send later") is a beta API and + may change before it's a finished feature. + example: "2020-06-24 11:19:54.337533+00:00" + - example: { "msg": "", "id": 42, "result": "success" } + "400": description: Bad request. content: application/json: schema: oneOf: - - $ref: '#/components/schemas/NonExistingStreamError' - - allOf: - - $ref: '#/components/schemas/CodedError' - - example: - { - "code": "BAD_REQUEST", - "msg": "Invalid email 'eeshan@zulip.com'", - "result": "error" - } + - $ref: "#/components/schemas/NonExistingStreamError" + - allOf: + - $ref: "#/components/schemas/CodedError" + - example: + { + "code": "BAD_REQUEST", + "msg": "Invalid email 'eeshan@zulip.com'", + "result": "error", + } /messages/{message_id}/history: get: operationId: get_message_history @@ -821,95 +809,96 @@ paths: [edit-settings]: /help/view-a-messages-edit-history parameters: - - $ref: '#/components/parameters/MessageId' + - $ref: "#/components/parameters/MessageId" responses: - '200': + "200": description: Success. content: application/json: schema: allOf: - - $ref: '#/components/schemas/JsonSuccess' - - properties: - message_history: - type: array - items: - type: object - additionalProperties: false - properties: - topic: - type: string - description: | - the topic for the message. - prev_topic: - type: string - description: | - the topic for the message before being edited. - content: - type: string - description: | - the body of the message. - rendered_content: - type: string - description: | - the already rendered, HTML version of `content`. - prev_content: - type: string - description: | - the body of the message before being edited. - prev_rendered_content: - type: string - description: | - the already rendered, HTML version of - `prev_content`. - user_id: - type: integer - description: | - the ID of the user that made the edit. - content_html_diff: - type: string - description: | - an HTML diff between this version of the message - and the previous one. - timestamp: - type: integer - description: | - the UNIX timestamp for this edit. - description: | - A chronologically sorted array of `snapshot` - objects, each one with the values of the - message after the edit. - - example: - { - "message_history": [ + - $ref: "#/components/schemas/JsonSuccess" + - properties: + message_history: + type: array + items: + type: object + additionalProperties: false + properties: + topic: + type: string + description: | + the topic for the message. + prev_topic: + type: string + description: | + the topic for the message before being edited. + content: + type: string + description: | + the body of the message. + rendered_content: + type: string + description: | + the already rendered, HTML version of `content`. + prev_content: + type: string + description: | + the body of the message before being edited. + prev_rendered_content: + type: string + description: | + the already rendered, HTML version of + `prev_content`. + user_id: + type: integer + description: | + the ID of the user that made the edit. + content_html_diff: + type: string + description: | + an HTML diff between this version of the message + and the previous one. + timestamp: + type: integer + description: | + the UNIX timestamp for this edit. + description: | + A chronologically sorted array of `snapshot` + objects, each one with the values of the + message after the edit. + - example: + { + "message_history": + [ { - "content": "Hello!", - "topic": "party at my houz", - "rendered_content": "

Hello!

", - "timestamp": 1530129122, - "user_id": 5 + "content": "Hello!", + "topic": "party at my houz", + "rendered_content": "

Hello!

", + "timestamp": 1530129122, + "user_id": 5, }, { - "topic": "party at my house", - "content": "Howdy!", - "prev_content": "Hello!", - "rendered_content": "

Howdy!

", - "user_id": 5, - "prev_rendered_content": "

Hello!

", - "content_html_diff": "

Howdy!

Hello!

", - "prev_topic": "party at my houz", - "timestamp": 1530129134 - } - ], + "topic": "party at my house", + "content": "Howdy!", + "prev_content": "Hello!", + "rendered_content": "

Howdy!

", + "user_id": 5, + "prev_rendered_content": "

Hello!

", + "content_html_diff": '

Howdy!

Hello!

', + "prev_topic": "party at my houz", + "timestamp": 1530129134, + }, + ], "msg": "", - "result": "success" - } - '400': + "result": "success", + } + "400": description: Bad request. content: application/json: schema: - $ref: '#/components/schemas/InvalidMessageError' + $ref: "#/components/schemas/InvalidMessageError" /messages/flags: post: operationId: update_message_flags @@ -924,60 +913,58 @@ paths: the [special endpoints for marking message as read in bulk](/api/mark-all-as-read). parameters: - - name: messages - in: query - description: | - An array containing the IDs of the target messages. - content: - application/json: - schema: - type: array - items: - type: integer - example: [4, 8, 15] - required: true - - name: op - in: query - description: | - Whether to `add` the flag or `remove` it. - schema: - type: string - enum: - - add - - remove - example: add - required: true - - name: flag - in: query - description: | - The flag that should be added/removed. - schema: - type: string - example: read - required: true + - name: messages + in: query + description: | + An array containing the IDs of the target messages. + content: + application/json: + schema: + type: array + items: + type: integer + example: [4, 8, 15] + required: true + - name: op + in: query + description: | + Whether to `add` the flag or `remove` it. + schema: + type: string + enum: + - add + - remove + example: add + required: true + - name: flag + in: query + description: | + The flag that should be added/removed. + schema: + type: string + example: read + required: true responses: - '200': + "200": description: Success. content: application/json: schema: allOf: - - $ref: '#/components/schemas/JsonSuccess' - - properties: - messages: - type: array - items: - type: integer - description: | - An array with the IDs of the modified messages. - - example: - { + - $ref: "#/components/schemas/JsonSuccess" + - properties: + messages: + type: array + items: + type: integer + description: | + An array with the IDs of the modified messages. + - example: + { "msg": "", - "messages": [ - 4, 18, 15 - ], - "result": "success" - } + "messages": [4, 18, 15], + "result": "success", + } /messages/render: post: operationId: render_message @@ -987,26 +974,26 @@ paths: `POST {{ api_url }}/v1/messages/render` parameters: - - $ref: '#/components/parameters/RequiredContent' + - $ref: "#/components/parameters/RequiredContent" responses: - '200': + "200": description: Success. content: application/json: schema: allOf: - - $ref: '#/components/schemas/JsonSuccess' - - properties: - rendered: - type: string - description: | - The rendered HTML. - - example: - { + - $ref: "#/components/schemas/JsonSuccess" + - properties: + rendered: + type: string + description: | + The rendered HTML. + - example: + { "msg": "", "rendered": "

foo

", - "result": "success" - } + "result": "success", + } /messages/{message_id}/reactions: post: operationId: add_reaction @@ -1016,28 +1003,28 @@ paths: `POST {{ api_url }}/v1/messages/{message_id}/reactions` parameters: - - $ref: '#/components/parameters/MessageId' - - $ref: '#/components/parameters/EmojiName' - required: true - - $ref: '#/components/parameters/EmojiCode' - - $ref: '#/components/parameters/ReactionType' + - $ref: "#/components/parameters/MessageId" + - $ref: "#/components/parameters/EmojiName" + required: true + - $ref: "#/components/parameters/EmojiCode" + - $ref: "#/components/parameters/ReactionType" responses: - '200': - $ref: '#/components/responses/SimpleSuccess' + "200": + $ref: "#/components/responses/SimpleSuccess" - '400': + "400": description: Bad request. content: application/json: schema: allOf: - - $ref: '#/components/schemas/CodedError' - - example: - { + - $ref: "#/components/schemas/CodedError" + - example: + { "result": "error", "msg": "Invalid emoji code", - "code": "BAD_REQUEST" - } + "code": "BAD_REQUEST", + } delete: operationId: remove_reaction @@ -1047,27 +1034,27 @@ paths: `DELETE {{ api_url }}/v1/messages/{message_id}/reactions` parameters: - - $ref: '#/components/parameters/MessageId' - - $ref: '#/components/parameters/EmojiName' - required: false - - $ref: '#/components/parameters/EmojiCode' - - $ref: '#/components/parameters/ReactionType' + - $ref: "#/components/parameters/MessageId" + - $ref: "#/components/parameters/EmojiName" + required: false + - $ref: "#/components/parameters/EmojiCode" + - $ref: "#/components/parameters/ReactionType" responses: - '200': - $ref: '#/components/responses/SimpleSuccess' - '400': + "200": + $ref: "#/components/responses/SimpleSuccess" + "400": description: Bad request. content: application/json: schema: allOf: - - $ref: '#/components/schemas/CodedError' - - example: - { + - $ref: "#/components/schemas/CodedError" + - example: + { "result": "error", "msg": "Invalid message(s)", - "code": "BAD_REQUEST" - } + "code": "BAD_REQUEST", + } /messages/matches_narrow: get: operationId: check_messages_match_narrow @@ -1091,73 +1078,76 @@ paths: object identical to how a `GET /messages` for the current narrow would have returned the message. parameters: - - name: msg_ids - in: query - description: List of IDs for the messages to check. - content: - application/json: - schema: - type: array - items: - type: integer - example: [31, 32] - required: true - - name: narrow - in: query - description: A structure defining the narrow to check against. See how to - [construct a narrow](/api/construct-narrow). - content: - application/json: - schema: - type: array - items: - type: object - example: [{'operator': 'has', 'operand': 'link'}] - required: true + - name: msg_ids + in: query + description: List of IDs for the messages to check. + content: + application/json: + schema: + type: array + items: + type: integer + example: [31, 32] + required: true + - name: narrow + in: query + description: + A structure defining the narrow to check against. See how to + [construct a narrow](/api/construct-narrow). + content: + application/json: + schema: + type: array + items: + type: object + example: [{ "operator": "has", "operand": "link" }] + required: true responses: - '200': + "200": description: Success. content: application/json: schema: allOf: - - $ref: '#/components/schemas/JsonSuccess' - - properties: - messages: - type: object - description: | - A dictionary with a key for each queried message that matches the narrow, - with message IDs as keys and search rendering data as values. - additionalProperties: + - $ref: "#/components/schemas/JsonSuccess" + - properties: + messages: type: object - additionalProperties: false - properties: - match_content: - type: string - description: | - HTML content of a queried message that matches the narrow. If the - narrow is a search narrow, `` elements - will be included, wrapping the matches for the search keywords. - match_subject: - type: string - description: | - HTML-escaped topic of a queried message that matches the narrow. If the - narrow is a search narrow, `` elements - will be included wrapping the matches for the search keywords. description: | - The ID of the message that matches the narrow. No record will be returned - for queried messages that do not match the narrow. - - example: - { - 'result': 'success', - 'msg': '', - 'messages': { - '31': { - 'match_content': '

http://foo.com

', - 'match_subject': 'test_topic' - } + A dictionary with a key for each queried message that matches the narrow, + with message IDs as keys and search rendering data as values. + additionalProperties: + type: object + additionalProperties: false + properties: + match_content: + type: string + description: | + HTML content of a queried message that matches the narrow. If the + narrow is a search narrow, `` elements + will be included, wrapping the matches for the search keywords. + match_subject: + type: string + description: | + HTML-escaped topic of a queried message that matches the narrow. If the + narrow is a search narrow, `` elements + will be included wrapping the matches for the search keywords. + description: | + The ID of the message that matches the narrow. No record will be returned + for queried messages that do not match the narrow. + - example: + { + "result": "success", + "msg": "", + "messages": + { + "31": + { + "match_content": '

http://foo.com

', + "match_subject": "test_topic", + }, + }, } - } /messages/{message_id}: get: operationId: get_raw_message @@ -1172,32 +1162,32 @@ paths: the message's raw markdown (e.g. for pre-filling a message-editing UI). parameters: - - $ref: '#/components/parameters/MessageId' + - $ref: "#/components/parameters/MessageId" responses: - '200': + "200": description: Success. content: application/json: schema: allOf: - - $ref: '#/components/schemas/JsonSuccess' - - properties: - raw_content: - type: string - description: | - The raw content of the message. - - example: - { + - $ref: "#/components/schemas/JsonSuccess" + - properties: + raw_content: + type: string + description: | + The raw content of the message. + - example: + { "raw_content": "**Don't** forget your towel!", "result": "success", - "msg": "" - } - '400': + "msg": "", + } + "400": description: Bad request. content: application/json: schema: - $ref: '#/components/schemas/InvalidMessageError' + $ref: "#/components/schemas/InvalidMessageError" patch: operationId: update_message tags: ["messages"] @@ -1209,74 +1199,74 @@ paths: `{msg_id}` in the above URL should be replaced with the ID of the message you wish you update. parameters: - - $ref: '#/components/parameters/MessageId' - - $ref: '#/components/parameters/Topic' - - name: propagate_mode - in: query - description: | - Which message(s) should be edited: just the one indicated in - `message_id`, messages in the same topic that had been sent after this - one, or all of them. - schema: - type: string - enum: - - change_one - - change_later - - change_all - default: change_one - example: change_all - - name: send_notification_to_old_thread - in: query - description: | - Whether to send breadcrumb message to the old thread to - notify users where the messages were moved to. + - $ref: "#/components/parameters/MessageId" + - $ref: "#/components/parameters/Topic" + - name: propagate_mode + in: query + description: | + Which message(s) should be edited: just the one indicated in + `message_id`, messages in the same topic that had been sent after this + one, or all of them. + schema: + type: string + enum: + - change_one + - change_later + - change_all + default: change_one + example: change_all + - name: send_notification_to_old_thread + in: query + description: | + Whether to send breadcrumb message to the old thread to + notify users where the messages were moved to. - **Changes**: New in Zulip 3.0 (feature level 9). - schema: - type: boolean - default: true - example: true - - name: send_notification_to_new_thread - in: query - description: | - Whether to send a notification message to the new thread to - notify users where the messages came from. + **Changes**: New in Zulip 3.0 (feature level 9). + schema: + type: boolean + default: true + example: true + - name: send_notification_to_new_thread + in: query + description: | + Whether to send a notification message to the new thread to + notify users where the messages came from. - **Changes**: New in Zulip 3.0 (feature level 9). - schema: - type: boolean - default: true - example: true - - $ref: '#/components/parameters/OptionalContent' - - $ref: '#/components/parameters/StreamIdInQuery' + **Changes**: New in Zulip 3.0 (feature level 9). + schema: + type: boolean + default: true + example: true + - $ref: "#/components/parameters/OptionalContent" + - $ref: "#/components/parameters/StreamIdInQuery" responses: - '200': + "200": description: Success. content: application/json: schema: - $ref: '#/components/schemas/JsonSuccess' - '400': + $ref: "#/components/schemas/JsonSuccess" + "400": description: Bad request. content: application/json: schema: allOf: - - $ref: '#/components/schemas/CodedError' - - properties: - msg: - enum: - - Your organization has turned off message editing - - You don't have permission to edit this message - - The time limit for editing this message has past - - Nothing to change - - Topic can't be empty - - example: - { + - $ref: "#/components/schemas/CodedError" + - properties: + msg: + enum: + - Your organization has turned off message editing + - You don't have permission to edit this message + - The time limit for editing this message has past + - Nothing to change + - Topic can't be empty + - example: + { "code": "BAD_REQUEST", "msg": "You don't have permission to edit this message", - "result": "error" - } + "result": "error", + } delete: operationId: delete_message tags: ["messages"] @@ -1289,29 +1279,29 @@ paths: [delete a message completely][delete-completely] feature documented in the Zulip Help Center. parameters: - - $ref: '#/components/parameters/MessageId' + - $ref: "#/components/parameters/MessageId" responses: - '200': + "200": description: Success. content: application/json: schema: - $ref: '#/components/schemas/JsonSuccess' - '400': + $ref: "#/components/schemas/JsonSuccess" + "400": description: Bad request. content: application/json: schema: oneOf: - - $ref: '#/components/schemas/InvalidMessageError' - - allOf: - - $ref: '#/components/schemas/CodedError' - - example: - { - "code": "BAD_REQUEST", - "msg": "You don't have permission to delete this message", - "result": "error" - } + - $ref: "#/components/schemas/InvalidMessageError" + - allOf: + - $ref: "#/components/schemas/CodedError" + - example: + { + "code": "BAD_REQUEST", + "msg": "You don't have permission to delete this message", + "result": "error", + } /user_uploads: post: operationId: upload_file @@ -1339,24 +1329,24 @@ paths: format: binary example: /path/to/file responses: - '200': + "200": description: Success. content: application/json: schema: allOf: - - $ref: '#/components/schemas/JsonSuccess' - - properties: - uri: - type: string - description: | - The URI of the uploaded file. - - example: - { + - $ref: "#/components/schemas/JsonSuccess" + - properties: + uri: + type: string + description: | + The URI of the uploaded file. + - example: + { "msg": "", "result": "success", - "uri": "/user_uploads/1/4e/m2A3MSqFnWRLUf9SaPzQ0Up_/zulip.txt" - } + "uri": "/user_uploads/1/4e/m2A3MSqFnWRLUf9SaPzQ0Up_/zulip.txt", + } /user_uploads/{realm_id_str}/{filename}: get: operationId: get_file_temporary_url @@ -1364,42 +1354,42 @@ paths: description: | Get a temporary URL for access to the file that doesn't require authentication. parameters: - - name: realm_id_str - in: path - description: | - The realm id. - schema: - type: integer - example: 1 - required: true - - name: filename - in: path - description: | - Path to the URL. - schema: - type: string - example: 4e/m2A3MSqFnWRLUf9SaPzQ0Up_/zulip.txt - required: true + - name: realm_id_str + in: path + description: | + The realm id. + schema: + type: integer + example: 1 + required: true + - name: filename + in: path + description: | + Path to the URL. + schema: + type: string + example: 4e/m2A3MSqFnWRLUf9SaPzQ0Up_/zulip.txt + required: true responses: - '200': + "200": description: Success. content: application/json: schema: allOf: - - $ref: '#/components/schemas/JsonSuccess' - - properties: - url: - type: string - description: | - A temporary URL that can be used to access the uploaded file - without Zulip's normal API authentication. - - example: - { + - $ref: "#/components/schemas/JsonSuccess" + - properties: + url: + type: string + description: | + A temporary URL that can be used to access the uploaded file + without Zulip's normal API authentication. + - example: + { "msg": "", "result": "success", - "url": "/user_uploads/temporary/322F32632F39765378464E4C63306D3961396F4970705A4D74424565432F7A756C69702E7478743A316A5053616A3A3938625F44393446466D37357254315F4F414C425A4553464F6A55" - } + "url": "/user_uploads/temporary/322F32632F39765378464E4C63306D3961396F4970705A4D74424565432F7A756C69702E7478743A316A5053616A3A3938625F44393446466D37357254315F4F414C425A4553464F6A55", + } /users: get: @@ -1411,104 +1401,99 @@ paths: `GET {{ api_url }}/v1/users` parameters: - - $ref: '#/components/parameters/ClientGravatar' - - $ref: '#/components/parameters/IncludeCustomProfileFields' + - $ref: "#/components/parameters/ClientGravatar" + - $ref: "#/components/parameters/IncludeCustomProfileFields" responses: - '200': + "200": description: Success. content: application/json: schema: allOf: - - $ref: '#/components/schemas/JsonSuccess' - - properties: - 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", - "is_admin": false, - "is_owner": false, - "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" - }, - { - "date_joined": "2019-10-20T07:50:53.729659+00:00", - "full_name": "King Hamlet", - "is_guest": false, - "profile_data": { - "4": { - "value": "vim" + - $ref: "#/components/schemas/JsonSuccess" + - properties: + 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", + "is_admin": false, + "is_owner": false, + "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", + }, + { + "date_joined": "2019-10-20T07:50:53.729659+00:00", + "full_name": "King Hamlet", + "is_guest": false, + "profile_data": + { + "4": { "value": "vim" }, + "2": + { + "value": "I am:\n* The prince of Denmark\n* Nephew to the usurping Claudius", + "rendered_value": "

I am:

\n
    \n
  • The prince of Denmark
    • \n
  • Nephew to the usurping Claudius
    • \n
", + }, + "5": { "value": "1900-1-1" }, + "7": { "value": "[11]" }, + "6": { "value": "https://blog.zulig.org" }, + "1": + { + "value": "+0-11-23-456-7890", + "rendered_value": "

+0-11-23-456-7890

", + }, + "8": { "value": "zulipbot" }, + "3": + { + "rendered_value": "

Dark chocolate

", + "value": "Dark chocolate", + }, }, - "2": { - "value": "I am:\n* The prince of Denmark\n* Nephew to the usurping Claudius", - "rendered_value": "

I am:

\n
    \n
  • The prince of Denmark
    • \n
  • Nephew to the usurping Claudius
    • \n
" - }, - "5": { - "value": "1900-1-1" - }, - "7": { - "value": "[11]" - }, - "6": { - "value": "https://blog.zulig.org" - }, - "1": { - "value": "+0-11-23-456-7890", - "rendered_value": "

+0-11-23-456-7890

" - }, - "8": { - "value": "zulipbot" - }, - "3": { - "rendered_value": "

Dark chocolate

", - "value": "Dark chocolate" - } - }, - "user_id": 10, - "is_bot": false, - "bot_type": null, - "timezone": "", - "is_admin": false, - "is_owner": false, - "avatar_url": "https://secure.gravatar.com/avatar/6d8cad0fd00256e7b40691d27ddfd466?d=identicon&version=1", - "is_active": true, - "email": "hamlet@zulip.com" - }, - { - "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", - "is_active": true, - "avatar_url": "https://secure.gravatar.com/avatar/7328586831cdbb1627649bd857b1ee8c?d=identicon&version=1", - "is_admin": false, - "is_owner": false, - "user_id": 23, - "bot_type": 1, - "timezone": "", - "is_bot": true - } - ] - } + "user_id": 10, + "is_bot": false, + "bot_type": null, + "timezone": "", + "is_admin": false, + "is_owner": false, + "avatar_url": "https://secure.gravatar.com/avatar/6d8cad0fd00256e7b40691d27ddfd466?d=identicon&version=1", + "is_active": true, + "email": "hamlet@zulip.com", + }, + { + "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", + "is_active": true, + "avatar_url": "https://secure.gravatar.com/avatar/7328586831cdbb1627649bd857b1ee8c?d=identicon&version=1", + "is_admin": false, + "is_owner": false, + "user_id": 23, + "bot_type": 1, + "timezone": "", + "is_bot": true, + }, + ], + } post: operationId: create_user tags: ["users"] @@ -1519,57 +1504,57 @@ paths: `POST {{ api_url }}/v1/users` parameters: - - name: email - in: query - description: | - The email address of the new user. - schema: - type: string - example: username@example.com - required: true - - name: password - in: query - description: | - The password of the new user. - schema: - type: string - example: abcd1234 - required: true - - name: full_name - in: query - description: | - The full name of the new user. - schema: - type: string - example: New User - required: true - - name: short_name - in: query - description: | - The short name of the new user. Not user-visible. - schema: - type: string - example: newuser - required: true + - name: email + in: query + description: | + The email address of the new user. + schema: + type: string + example: username@example.com + required: true + - name: password + in: query + description: | + The password of the new user. + schema: + type: string + example: abcd1234 + required: true + - name: full_name + in: query + description: | + The full name of the new user. + schema: + type: string + example: New User + required: true + - name: short_name + in: query + description: | + The short name of the new user. Not user-visible. + schema: + type: string + example: newuser + required: true responses: - '200': + "200": description: Success. content: application/json: schema: - $ref: '#/components/schemas/JsonSuccess' - '400': + $ref: "#/components/schemas/JsonSuccess" + "400": description: Bad request. content: application/json: schema: allOf: - - $ref: '#/components/schemas/JsonError' - - example: - { + - $ref: "#/components/schemas/JsonError" + - example: + { "msg": "Email 'newbie@zulip.com' already in use", - "result": "error" - } + "result": "error", + } /users/{user_id}/reactivate: post: @@ -1584,20 +1569,16 @@ paths: `POST {{ api_url }}/v1/users/{user_id}/reactivate` parameters: - - $ref: '#/components/parameters/UserId' + - $ref: "#/components/parameters/UserId" responses: - '200': + "200": description: Success content: application/json: schema: allOf: - - $ref: '#/components/schemas/JsonSuccess' - - example: - { - "msg": "", - "result": "success", - } + - $ref: "#/components/schemas/JsonSuccess" + - example: { "msg": "", "result": "success" } /users/{email}/presence: get: @@ -1618,73 +1599,68 @@ paths: [Zulip's developer documentation](https://zulip.readthedocs.io/en/latest/subsystems/presence.html) for details on the data model for presence in Zulip. parameters: - - name: email - in: path - description: | - The email address of the user whose presence you want to fetch. - schema: - type: string - example: iago@zulip.com - required: true + - name: email + in: path + description: | + The email address of the user whose presence you want to fetch. + schema: + type: string + example: iago@zulip.com + required: true responses: - '200': + "200": description: Success. content: application/json: schema: allOf: - - $ref: '#/components/schemas/JsonSuccess' - - properties: - presence: - type: object - description: | - An object containing the presence details for every client the user has - logged into. - additionalProperties: + - $ref: "#/components/schemas/JsonSuccess" + - properties: + presence: type: object - additionalProperties: false - properties: - timestamp: - type: integer - description: | - when this update was received; if the timestamp - is more than a few minutes in the past, the user is offline. - status: - type: string - description: | - either `active` or `idle`: whether the user had - recently interacted with Zulip at the time in the timestamp - (this distinguishes orange vs. green dots in the Zulip web - UI; orange/idle means we don't know whether the user is - actually at their computer or just left the Zulip app open - on their desktop). description: | - `{client_name}` or `aggregated`: the keys for these objects are - the names of the different clients where this user is logged in, - like `website`, `ZulipDesktop`, `ZulipTerminal`, or - `ZulipMobile`. There is also an `aggregated` key, which matches - the contents of the object that has been updated most - recently. For most applications, you'll just want to look at the - `aggregated` key. - - example: - { - "presence": { - "website": { - "timestamp": 1532697622, - "status": "active", - }, - "ZulipMobile": { - "timestamp": 1522687421, - "status": "active", - }, - "aggregated": { - "timestamp": 1532697622, - "status": "active", - } - }, + An object containing the presence details for every client the user has + logged into. + additionalProperties: + type: object + additionalProperties: false + properties: + timestamp: + type: integer + description: | + when this update was received; if the timestamp + is more than a few minutes in the past, the user is offline. + status: + type: string + description: | + either `active` or `idle`: whether the user had + recently interacted with Zulip at the time in the timestamp + (this distinguishes orange vs. green dots in the Zulip web + UI; orange/idle means we don't know whether the user is + actually at their computer or just left the Zulip app open + on their desktop). + description: | + `{client_name}` or `aggregated`: the keys for these objects are + the names of the different clients where this user is logged in, + like `website`, `ZulipDesktop`, `ZulipTerminal`, or + `ZulipMobile`. There is also an `aggregated` key, which matches + the contents of the object that has been updated most + recently. For most applications, you'll just want to look at the + `aggregated` key. + - example: + { + "presence": + { + "website": + { "timestamp": 1532697622, "status": "active" }, + "ZulipMobile": + { "timestamp": 1522687421, "status": "active" }, + "aggregated": + { "timestamp": 1532697622, "status": "active" }, + }, "result": "success", - "msg": "" - } + "msg": "", + } /users/me: get: operationId: get_own_user @@ -1694,116 +1670,116 @@ paths: `GET {{ api_url }}/v1/users/me` responses: - '200': + "200": description: Success content: application/json: schema: allOf: - - $ref: '#/components/schemas/JsonSuccess' - - properties: - avatar_url: - type: string - description: | - URL for the user's avatar. + - $ref: "#/components/schemas/JsonSuccess" + - properties: + avatar_url: + type: string + description: | + URL for the user's avatar. - **Changes**: New in Zulip 2.1.0. - example: "x" - avatar_version: - type: integer - description: | - Version for the the 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 2.1.0. + example: "x" + avatar_version: + type: integer + description: | + Version for the the 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). Previous - versions do not return this field. - example: 1 - email: - type: string - description: | - 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 10). Previous + versions do not return this field. + example: 1 + email: + type: string + description: | + 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 - is_guest: - type: boolean - description: | - A boolean indicating if the requesting user is a guest. + **Changes**: New in Zulip 3.0 (feature level 8). + example: false + is_guest: + type: boolean + description: | + A boolean indicating if the requesting user is a guest. - **Changes**: New in Zulip 3.0 (feature level 10). Previous - versions do not return this field. - 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 user account has been deactivated. + **Changes**: New in Zulip 3.0 (feature level 10). Previous + versions do not return this field. + 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 user account has been deactivated. - **Changes**: New in Zulip 3.0 (feature level 10). Previous - versions do not return this field. - example: true - timezone: - type: string - description: | - The time zone of the user. + **Changes**: New in Zulip 3.0 (feature level 10). Previous + versions do not return this field. + example: true + timezone: + type: string + description: | + The time zone of the user. - **Changes**: New in Zulip 3.0 (feature level 10). Previous - versions do not return this field. - example: "" - date_joined: - type: string - description: | - The time the user account was created. + **Changes**: New in Zulip 3.0 (feature level 10). Previous + versions do not return this field. + example: "" + date_joined: + type: string + description: | + The time the user account was created. - **Changes**: New in Zulip 3.0 (feature level 10). Previous - versions do not return this field. - example: "2019-10-20T07:50:53.728864+00:00" - max_message_id: - type: integer - deprecated: true - description: | - The integer ID of the last message received by your account. + **Changes**: New in Zulip 3.0 (feature level 10). Previous + versions do not return this field. + example: "2019-10-20T07:50:53.728864+00:00" + max_message_id: + type: integer + deprecated: true + description: | + The integer ID of the last message received by your account. - **Deprecated**. We plan to remove this in favor of recommending - using `GET /messages` with `anchor="newest"`. - example: 30 - user_id: - type: integer - description: | - The user's ID. - example: 1 - delivery_email: - type: string - description: | - The user's real email address. This field is present only if - [email address visibility](/help/restrict-visibility-of-email-addresses) is - limited and you are an administrator with access to real email addresses - under the configured policy. - profile_data: - $ref: '#/components/schemas/profile_data' - - example: - { + **Deprecated**. We plan to remove this in favor of recommending + using `GET /messages` with `anchor="newest"`. + example: 30 + user_id: + type: integer + description: | + The user's ID. + example: 1 + delivery_email: + type: string + description: | + The user's real email address. This field is present only if + [email address visibility](/help/restrict-visibility-of-email-addresses) is + limited and you are an administrator with access to real email addresses + under the configured policy. + profile_data: + $ref: "#/components/schemas/profile_data" + - example: + { "avatar_url": "https://secure.gravatar.com/avatar/af4f06322c177ef4e1e9b2c424986b54?d=identicon&version=1", "avatar_version": 1, "email": "iago@zulip.com", @@ -1819,66 +1795,59 @@ paths: "msg": "", "result": "success", "user_id": 5, - "profile_data": { - "5": { - "value": "2000-1-1" - }, - "4": { - "value": "emacs" - }, - "7": { - "value": "[10]" - }, - "1": { - "value": "+1-234-567-8901", - "rendered_value": "

+1-234-567-8901

" - }, - "2": { - "rendered_value": "

Betrayer of Othello.

", - "value": "Betrayer of Othello." - }, - "8": { - "value": "zulip" - }, - "3": { - "value": "Apples", - "rendered_value": "

Apples

" - }, - "6": { - "value": "https://zulip.readthedocs.io/en/latest/" - } - } - } + "profile_data": + { + "5": { "value": "2000-1-1" }, + "4": { "value": "emacs" }, + "7": { "value": "[10]" }, + "1": + { + "value": "+1-234-567-8901", + "rendered_value": "

+1-234-567-8901

", + }, + "2": + { + "rendered_value": "

Betrayer of Othello.

", + "value": "Betrayer of Othello.", + }, + "8": { "value": "zulip" }, + "3": + { + "value": "Apples", + "rendered_value": "

Apples

", + }, + "6": + { + "value": "https://zulip.readthedocs.io/en/latest/", + }, + }, + } delete: operationId: deactivate_my_account tags: ["users"] description: | Delete the requesting user from the realm. responses: - '200': + "200": description: Bad Request content: application/json: schema: allOf: - - $ref: '#/components/schemas/JsonSuccess' - - example: - { - "msg": "", - "result": "success", - } - '400': + - $ref: "#/components/schemas/JsonSuccess" + - example: { "msg": "", "result": "success" } + "400": description: Bad Request content: application/json: schema: allOf: - - $ref: '#/components/schemas/JsonError' - - example: - { + - $ref: "#/components/schemas/JsonError" + - example: + { "msg": "Cannot deactivate the only organization administrator", - "result": "error" - } + "result": "error", + } /users/me/{stream_id}/topics: get: operationId: get_stream_topics @@ -1888,64 +1857,56 @@ paths: `GET {{ api_url }}/v1/users/me/{stream_id}/topics` parameters: - - $ref: '#/components/parameters/StreamIdInPath' + - $ref: "#/components/parameters/StreamIdInPath" responses: - '200': + "200": description: Success. content: application/json: schema: allOf: - - $ref: '#/components/schemas/JsonSuccess' - - properties: - topics: - type: array - description: | - An array of `topic` objects. - items: - type: object - additionalProperties: false - properties: - max_id: - description: | - The message ID of the last message sent to this topic. - type: integer - name: - description: | - The name of the topic. - type: string - - example: - { + - $ref: "#/components/schemas/JsonSuccess" + - properties: + topics: + type: array + description: | + An array of `topic` objects. + items: + type: object + additionalProperties: false + properties: + max_id: + description: | + The message ID of the last message sent to this topic. + type: integer + name: + description: | + The name of the topic. + type: string + - example: + { "msg": "", "result": "success", - "topics": [ - { - "max_id": 26, - "name": "Denmark3" - }, - { - "max_id": 23, - "name": "Denmark1" - }, - { - "max_id": 6, - "name": "Denmark2" - } - ] - } - '400': + "topics": + [ + { "max_id": 26, "name": "Denmark3" }, + { "max_id": 23, "name": "Denmark1" }, + { "max_id": 6, "name": "Denmark2" }, + ], + } + "400": description: Bad request. content: application/json: schema: allOf: - - $ref: '#/components/schemas/JsonError' - - example: - { + - $ref: "#/components/schemas/JsonError" + - example: + { "code": "BAD_REQUEST", "msg": "Invalid stream id", - "result": "error" - } + "result": "error", + } /users/me/subscriptions: get: operationId: get_subscriptions @@ -1958,264 +1919,254 @@ paths: # corresponds to an endpoint. TODO: Add these for more # endpoints, and perhaps use this to provide links to implementations. parameters: - - $ref: '#/components/parameters/IncludeSubscribers' + - $ref: "#/components/parameters/IncludeSubscribers" responses: - '200': + "200": description: Success. content: application/json: schema: allOf: - - $ref: '#/components/schemas/JsonSuccess' - # TODO: Is this the best way to declare required elements in 200 responses? - - required: - - subscriptions - - properties: - subscriptions: - type: array - description: | - A list of dictionaries where each dictionary contains - information about one of the subscribed streams. - items: - type: object - additionalProperties: false - properties: - stream_id: - type: integer - description: | - The unique ID of a stream. - name: - type: string - description: | - The name of a stream. - description: - type: string - description: | - The short description of a stream in text/markdown format, - intended to be used to prepopulate UI for editing a stream's - description. - rendered_description: - type: string - description: | - A short description of a stream rendered as HTML, intended to - be used when displaying the stream description in a UI. + - $ref: "#/components/schemas/JsonSuccess" + # TODO: Is this the best way to declare required elements in 200 responses? + - required: + - subscriptions + - properties: + subscriptions: + type: array + description: | + A list of dictionaries where each dictionary contains + information about one of the subscribed streams. + items: + type: object + additionalProperties: false + properties: + stream_id: + type: integer + description: | + The unique ID of a stream. + name: + type: string + description: | + The name of a stream. + description: + type: string + description: | + The short description of a stream in text/markdown format, + intended to be used to prepopulate UI for editing a stream's + description. + rendered_description: + type: string + description: | + A short description of a stream rendered as HTML, intended to + be used when displaying the stream description in a UI. - One should use the standard Zulip rendered_markdown CSS when - displaying this content so that emoji, LaTeX, and other syntax - work correctly. And any client-side security logic for - user-generated message content should be applied when displaying - this HTML as though it were the body of a Zulip message. - invite_only: - type: boolean - description: | - Specifies whether the stream is private or not. - Only people who have been invited can access a private stream. - # TODO: This subscribers item should probably be declared optional more - # explicitly in the OpenAPI format? - subscribers: - type: array - items: - type: integer - description: | - A list of user IDs of users who are also subscribed - to a given stream. Included only if `include_subscribers` is `true`. - desktop_notifications: - type: boolean - nullable: true - description: | - A boolean specifying whether desktop notifications - are enabled for the given stream. + One should use the standard Zulip rendered_markdown CSS when + displaying this content so that emoji, LaTeX, and other syntax + work correctly. And any client-side security logic for + user-generated message content should be applied when displaying + this HTML as though it were the body of a Zulip message. + invite_only: + type: boolean + description: | + Specifies whether the stream is private or not. + Only people who have been invited can access a private stream. + # TODO: This subscribers item should probably be declared optional more + # explicitly in the OpenAPI format? + subscribers: + type: array + items: + type: integer + description: | + A list of user IDs of users who are also subscribed + to a given stream. Included only if `include_subscribers` is `true`. + desktop_notifications: + type: boolean + nullable: true + description: | + A boolean specifying whether desktop notifications + are enabled for the given stream. - A null value means the value of this setting - should be inherited from the user-level default - setting, enable_stream_desktop_notifications, for - this stream. - email_notifications: - type: boolean - nullable: true - description: | - A boolean specifying whether email notifications - are enabled for the given stream. + A null value means the value of this setting + should be inherited from the user-level default + setting, enable_stream_desktop_notifications, for + this stream. + email_notifications: + type: boolean + nullable: true + description: | + A boolean specifying whether email notifications + are enabled for the given stream. - A null value means the value of this setting - should be inherited from the user-level default - setting, enable_stream_email_notifications, for - this stream. - wildcard_mentions_notify: - type: boolean - nullable: true - description: | - A boolean specifying whether wildcard mentions - trigger notifications as though they were personal - mentions in this stream. + A null value means the value of this setting + should be inherited from the user-level default + setting, enable_stream_email_notifications, for + this stream. + wildcard_mentions_notify: + type: boolean + nullable: true + description: | + A boolean specifying whether wildcard mentions + trigger notifications as though they were personal + mentions in this stream. - A null value means the value of this setting - should be inherited from the user-level default - setting, wildcard_mentions_notify, for - this stream. - push_notifications: - type: boolean - nullable: true - description: | - A boolean specifying whether push notifications - are enabled for the given stream. + A null value means the value of this setting + should be inherited from the user-level default + setting, wildcard_mentions_notify, for + this stream. + push_notifications: + type: boolean + nullable: true + description: | + A boolean specifying whether push notifications + are enabled for the given stream. - A null value means the value of this setting - should be inherited from the user-level default - setting, enable_stream_push_notifications, for - this stream. - audible_notifications: - type: boolean - nullable: true - description: | - A boolean specifying whether audible notifications - are enabled for the given stream. + A null value means the value of this setting + should be inherited from the user-level default + setting, enable_stream_push_notifications, for + this stream. + audible_notifications: + type: boolean + nullable: true + description: | + A boolean specifying whether audible notifications + are enabled for the given stream. - A null value means the value of this setting - should be inherited from the user-level default - setting, enable_stream_audible_notifications, for - this stream. - pin_to_top: - type: boolean - description: | - A boolean specifying whether the given stream has been pinned - to the top. - email_address: - type: string - description: | - Email address of the given stream, used for - [sending emails to the stream](/help/message-a-stream-by-email). - is_muted: - type: boolean - description: | - Whether the user has muted the stream. Muted streams do - not count towards your total unread count and do not show up in - `All messages` view (previously known as `Home` view). + A null value means the value of this setting + should be inherited from the user-level default + setting, enable_stream_audible_notifications, for + this stream. + pin_to_top: + type: boolean + description: | + A boolean specifying whether the given stream has been pinned + to the top. + email_address: + type: string + description: | + Email address of the given stream, used for + [sending emails to the stream](/help/message-a-stream-by-email). + is_muted: + type: boolean + description: | + Whether the user has muted the stream. Muted streams do + not count towards your total unread count and do not show up in + `All messages` view (previously known as `Home` view). - **Changes**: Prior to Zulip 2.1, this feature was - represented by the more confusingly named `in_home_view` (with the - opposite value, `in_home_view=!is_muted`). - in_home_view: - type: boolean - deprecated: true - description: | - Legacy property for if the given stream is muted, with inverted meeting. + **Changes**: Prior to Zulip 2.1, this feature was + represented by the more confusingly named `in_home_view` (with the + opposite value, `in_home_view=!is_muted`). + in_home_view: + type: boolean + deprecated: true + description: | + Legacy property for if the given stream is muted, with inverted meeting. - **Deprecated**; clients should use is_muted where available. - is_announcement_only: - type: boolean - deprecated: true - description: | - Whether only organization administrators can post to the stream. + **Deprecated**; clients should use is_muted where available. + is_announcement_only: + type: boolean + deprecated: true + description: | + Whether only organization administrators can post to the stream. - **Changes**: Deprecated in Zulip 3.0 (feature level 1), use - `stream_post_policy` instead. - is_web_public: - type: boolean - description: | - Whether the stream has been configured to allow unauthenticated - access to its message history from the web. - color: - type: string - description: | - The user's personal color for the stream. - stream_post_policy: - type: integer - description: | - Policy for which users can post messages to the stream. + **Changes**: Deprecated in Zulip 3.0 (feature level 1), use + `stream_post_policy` instead. + is_web_public: + type: boolean + description: | + Whether the stream has been configured to allow unauthenticated + access to its message history from the web. + color: + type: string + description: | + The user's personal color for the stream. + stream_post_policy: + type: integer + description: | + Policy for which users can post messages to the stream. - * 1 => Any user can post. - * 2 => Only administrators can post. - * 3 => Only new members can post. + * 1 => Any user can post. + * 2 => Only administrators can post. + * 3 => Only new members can post. - **Changes**: New in Zulip 3.0, replacing the previous - `is_announcement_only` boolean. - message_retention_days: - type: integer - nullable: true - description: | - Number of days that messages sent to this stream will be stored - before being automatically deleted by the [message retention - policy](/help/message-retention-policy). There are two special values: + **Changes**: New in Zulip 3.0, replacing the previous + `is_announcement_only` boolean. + message_retention_days: + type: integer + nullable: true + description: | + Number of days that messages sent to this stream will be stored + before being automatically deleted by the [message retention + policy](/help/message-retention-policy). There are two special values: - * `null`, the default, means the stream will inherit the organization - level setting. - * `-1` encodes retaining messages in this stream forever. + * `null`, the default, means the stream will inherit the organization + level setting. + * `-1` encodes retaining messages in this stream forever. - **Changes**: New in Zulip 3.0 (feature level 17). - history_public_to_subscribers: - type: boolean - description: | - Whether the history of the stream is public to its subscribers. + **Changes**: New in Zulip 3.0 (feature level 17). + history_public_to_subscribers: + type: boolean + description: | + Whether the history of the stream is public to its subscribers. - Currently always true for public streams (i.e. invite_only=False implies - history_public_to_subscribers=True), but clients should not make that - assumption, as we may change that behavior in the future. - first_message_id: - type: integer - description: | - The id of the first message in the stream. + Currently always true for public streams (i.e. invite_only=False implies + history_public_to_subscribers=True), but clients should not make that + assumption, as we may change that behavior in the future. + first_message_id: + type: integer + description: | + The id of the first message in the stream. - Intended to help clients determine whether they need to display - UI like the "more topics" widget that would suggest the stream - has older history that can be accessed. + Intended to help clients determine whether they need to display + UI like the "more topics" widget that would suggest the stream + has older history that can be accessed. - Null is used for streams with no message history. - stream_weekly_traffic: - type: integer - nullable: true - description: | - The average number of messages sent to the stream in recent weeks, - rounded to the nearest integer. + Null is used for streams with no message history. + stream_weekly_traffic: + type: integer + nullable: true + description: | + The average number of messages sent to the stream in recent weeks, + rounded to the nearest integer. - Null means the stream was recently created and there is - insufficient data to estimate the average traffic. - - example: - { - "msg": "", - "result": "success", - "subscriptions": [ - { - "audible_notifications": true, - "color": "#e79ab5", - "description": "A Scandinavian country", - "desktop_notifications": true, - "email_address": "Denmark+187b4125ed36d6af8b5d03ef4f65c0cf@zulipdev.com:9981", - "is_muted": false, - "invite_only": false, - "name": "Denmark", - "pin_to_top": false, - "push_notifications": false, - "stream_id": 1, - "subscribers": [ - 7, - 10, - 11, - 12, - 14 - ] - }, - { - "audible_notifications": true, - "color": "#e79ab5", - "description": "Located in the United Kingdom", - "desktop_notifications": true, - "email_address": "Scotland+f5786390183e60a1ccb18374f9d05649@zulipdev.com:9981", - "is_muted": false, - "invite_only": false, - "name": "Scotland", - "pin_to_top": false, - "push_notifications": false, - "stream_id": 3, - "subscribers": [ - 7, - 11, - 12, - 14 - ] - } - ] - } + Null means the stream was recently created and there is + insufficient data to estimate the average traffic. + - example: + { + "msg": "", + "result": "success", + "subscriptions": + [ + { + "audible_notifications": true, + "color": "#e79ab5", + "description": "A Scandinavian country", + "desktop_notifications": true, + "email_address": "Denmark+187b4125ed36d6af8b5d03ef4f65c0cf@zulipdev.com:9981", + "is_muted": false, + "invite_only": false, + "name": "Denmark", + "pin_to_top": false, + "push_notifications": false, + "stream_id": 1, + "subscribers": [7, 10, 11, 12, 14], + }, + { + "audible_notifications": true, + "color": "#e79ab5", + "description": "Located in the United Kingdom", + "desktop_notifications": true, + "email_address": "Scotland+f5786390183e60a1ccb18374f9d05649@zulipdev.com:9981", + "is_muted": false, + "invite_only": false, + "name": "Scotland", + "pin_to_top": false, + "push_notifications": false, + "stream_id": 3, + "subscribers": [7, 11, 12, 14], + }, + ], + } post: operationId: subscribe tags: ["streams"] @@ -2228,121 +2179,112 @@ paths: created. The initial [stream settings](/api/update-stream) will be determined by the optional parameters like `invite_only` detailed below. parameters: - - name: subscriptions - in: query - description: | - A list of dictionaries containing the the key `name` and value - specifying the name of the stream to subscribe. If the stream does not - exist a new stream is created. The description of the stream created can - be specified by setting the dictionary key `description` with an - appropriate value. - content: - application/json: - schema: - type: array - items: - type: object - example: [{"name": "Verona", "description": "Italian City"}] - required: true - - $ref: '#/components/parameters/Principals' - - name: authorization_errors_fatal - in: query - description: | - A boolean specifying whether authorization errors (such as when the - requesting user is not authorized to access a private stream) should be - considered fatal or not. When `True`, an authorization error is reported - as such. When set to `False`, the response will be a 200 and any streams - where the request encountered an authorization error will be listed - in the `unauthorized` key. - schema: - type: boolean - default: true - example: false - - name: announce - in: query - description: | - If one of the streams specified did not exist previously and is thus craeted - by this call, this determines whether [notification bot](/help/configure-notification-bot) - will send an announcement about the new stream's creation. - schema: - type: boolean - default: false - example: true - - name: invite_only - in: query - description: | - As described above, this endpoint will create a new stream if passed - a stream name that doesn't already exist. This parameters and the ones - that follow are used to request an initial configuration of a created - stream; they are ignored for streams that already exist. + - name: subscriptions + in: query + description: | + A list of dictionaries containing the the key `name` and value + specifying the name of the stream to subscribe. If the stream does not + exist a new stream is created. The description of the stream created can + be specified by setting the dictionary key `description` with an + appropriate value. + content: + application/json: + schema: + type: array + items: + type: object + example: [{ "name": "Verona", "description": "Italian City" }] + required: true + - $ref: "#/components/parameters/Principals" + - name: authorization_errors_fatal + in: query + description: | + A boolean specifying whether authorization errors (such as when the + requesting user is not authorized to access a private stream) should be + considered fatal or not. When `True`, an authorization error is reported + as such. When set to `False`, the response will be a 200 and any streams + where the request encountered an authorization error will be listed + in the `unauthorized` key. + schema: + type: boolean + default: true + example: false + - name: announce + in: query + description: | + If one of the streams specified did not exist previously and is thus craeted + by this call, this determines whether [notification bot](/help/configure-notification-bot) + will send an announcement about the new stream's creation. + schema: + type: boolean + default: false + example: true + - name: invite_only + in: query + description: | + As described above, this endpoint will create a new stream if passed + a stream name that doesn't already exist. This parameters and the ones + that follow are used to request an initial configuration of a created + stream; they are ignored for streams that already exist. - This parameter determines whether any newly created streams will be - private streams. - schema: - type: boolean - default: false - example: true - - $ref: '#/components/parameters/HistoryPublicToSubscribers' - - $ref: '#/components/parameters/StreamPostPolicy' - - $ref: '#/components/parameters/MessageRetentionDays' + This parameter determines whether any newly created streams will be + private streams. + schema: + type: boolean + default: false + example: true + - $ref: "#/components/parameters/HistoryPublicToSubscribers" + - $ref: "#/components/parameters/StreamPostPolicy" + - $ref: "#/components/parameters/MessageRetentionDays" responses: - '200': + "200": description: Success. content: application/json: schema: oneOf: - - allOf: - - $ref: '#/components/schemas/AddSubscriptionsResponse' - - example: - { - "already_subscribed": {}, - "msg": "", - "result": "success", - "subscribed": { - "iago@zulip.com": [ - "new stream" - ] + - allOf: + - $ref: "#/components/schemas/AddSubscriptionsResponse" + - example: + { + "already_subscribed": {}, + "msg": "", + "result": "success", + "subscribed": { "iago@zulip.com": ["new stream"] }, } - } - - allOf: - - $ref: '#/components/schemas/AddSubscriptionsResponse' - - example: - { - "already_subscribed": { - "newbie@zulip.com": [ - "new stream" - ] - }, - "msg": "", - "result": "success", - "subscribed": {} - } - '400': + - allOf: + - $ref: "#/components/schemas/AddSubscriptionsResponse" + - example: + { + "already_subscribed": + { "newbie@zulip.com": ["new stream"] }, + "msg": "", + "result": "success", + "subscribed": {}, + } + "400": description: Success. content: application/json: schema: oneOf: - - allOf: - - $ref: '#/components/schemas/AddSubscriptionsResponse' - - example: - { - "msg": "Unable to access stream (private_stream).", - "result": "error" - } - - allOf: - - $ref: '#/components/schemas/AddSubscriptionsResponse' - - example: - { - "already_subscribed": {}, - "msg": "", - "result": "success", - "subscribed": {}, - "unauthorized": [ - "private_stream" - ] - } + - allOf: + - $ref: "#/components/schemas/AddSubscriptionsResponse" + - example: + { + "msg": "Unable to access stream (private_stream).", + "result": "error", + } + - allOf: + - $ref: "#/components/schemas/AddSubscriptionsResponse" + - example: + { + "already_subscribed": {}, + "msg": "", + "result": "success", + "subscribed": {}, + "unauthorized": ["private_stream"], + } patch: operationId: update_subscriptions tags: ["streams"] @@ -2359,7 +2301,7 @@ paths: type: array items: type: string - example: ['Verona', 'Denmark'] + example: ["Verona", "Denmark"] required: false - name: add in: query @@ -2383,83 +2325,79 @@ paths: type: string example: [ - { - "name": "Verona" - }, + { "name": "Verona" }, { "name": "Denmark", "color": "#e79ab5", "description": "A Scandinavian country", - } + }, ] required: false responses: - '200': + "200": description: Success. content: application/json: schema: allOf: - - $ref: '#/components/schemas/JsonSuccess' - - required: - - subscribed - - already_subscribed - - removed - - properties: - subscribed: - type: object - description: | - A dictionary where the key is the email - address of the user/bot and the value is a - list of the names of the streams that were - subscribed to as a result of the query. - additionalProperties: + - $ref: "#/components/schemas/JsonSuccess" + - required: + - subscribed + - already_subscribed + - removed + - properties: + subscribed: + type: object description: | - `{email_id}`: A list of the names of streams that - the user was subscribed to as a result of the query. + A dictionary where the key is the email + address of the user/bot and the value is a + list of the names of the streams that were + subscribed to as a result of the query. + additionalProperties: + description: | + `{email_id}`: A list of the names of streams that + the user was subscribed to as a result of the query. + type: array + items: + type: string + already_subscribed: + type: object + description: | + A dictionary where the key is the email + address of the user/bot and the value is a + list of the names of the streams that the + user/bot is already subscribed to. + additionalProperties: + description: | + `{email_id}`: A list of the names of streams that + the user was already subscribed to. + type: array + items: + type: string + not_removed: type: array items: type: string - already_subscribed: - type: object - description: | - A dictionary where the key is the email - address of the user/bot and the value is a - list of the names of the streams that the - user/bot is already subscribed to. - additionalProperties: description: | - `{email_id}`: A list of the names of streams that - the user was already subscribed to. + A list of the names of streams that the user + is already unsubscribed from, and hence + doesn't need to be unsubscribed. + removed: type: array items: type: string - not_removed: - type: array - items: - type: string - description: | - A list of the names of streams that the user - is already unsubscribed from, and hence - doesn't need to be unsubscribed. - removed: - type: array - items: - type: string - description: | - A list of the names of streams which were unsubscribed - from as a result of the query. - - example: - { + description: | + A list of the names of streams which were unsubscribed + from as a result of the query. + - example: + { "msg": "", "subscribed": {}, - "already_subscribed": {"iago@zulip.com":["Verona"]}, + "already_subscribed": { "iago@zulip.com": ["Verona"] }, "not_removed": [], - "removed": [ - "new stream" - ], - "result": "success" - } + "removed": ["new stream"], + "result": "success", + } delete: operationId: unsubscribe tags: ["streams"] @@ -2468,58 +2406,56 @@ paths: `DELETE {{ api_url }}/v1/users/me/subscriptions` parameters: - - name: subscriptions - in: query - description: | - A list of stream names to unsubscribe from. This parameter is called - `streams` in our Python API. - content: - application/json: - schema: - type: array - items: - type: string - example: ['Verona', 'Denmark'] - required: true - - $ref: '#/components/parameters/Principals' + - name: subscriptions + in: query + description: | + A list of stream names to unsubscribe from. This parameter is called + `streams` in our Python API. + content: + application/json: + schema: + type: array + items: + type: string + example: ["Verona", "Denmark"] + required: true + - $ref: "#/components/parameters/Principals" responses: - '200': + "200": description: Success. content: application/json: schema: allOf: - - $ref: '#/components/schemas/JsonSuccess' - - properties: - not_removed: - type: array - items: - type: string - description: | - A list of the names of streams that the user is already unsubscribed - from, and hence doesn't need to be unsubscribed. - removed: - type: array - items: - type: string - description: | - A list of the names of streams which were unsubscribed from as a result - of the query. - - example: - { + - $ref: "#/components/schemas/JsonSuccess" + - properties: + not_removed: + type: array + items: + type: string + description: | + A list of the names of streams that the user is already unsubscribed + from, and hence doesn't need to be unsubscribed. + removed: + type: array + items: + type: string + description: | + A list of the names of streams which were unsubscribed from as a result + of the query. + - example: + { "msg": "", "not_removed": [], - "removed": [ - "new stream" - ], - "result": "success" - } - '400': + "removed": ["new stream"], + "result": "success", + } + "400": description: Bad request. content: application/json: schema: - $ref: '#/components/schemas/NonExistingStreamError' + $ref: "#/components/schemas/NonExistingStreamError" /users/{user_id}/subscriptions/{stream_id}: get: operationId: get_subscription_status @@ -2531,29 +2467,25 @@ paths: **Changes**: New in Zulip 3.0 (feature level 11). parameters: - - $ref: '#/components/parameters/UserId' - example: 7 - - $ref: '#/components/parameters/StreamIdInPath' - example: 1 + - $ref: "#/components/parameters/UserId" + example: 7 + - $ref: "#/components/parameters/StreamIdInPath" + example: 1 responses: - '200': + "200": description: Success content: application/json: schema: allOf: - - $ref: '#/components/schemas/JsonSuccess' - - properties: - is_subscribed: - type: boolean - description: | - Whether the user is subscribed to the stream. - - example: - { - "msg": "", - "result": "success", - "is_subscribed": false - } + - $ref: "#/components/schemas/JsonSuccess" + - properties: + is_subscribed: + type: boolean + description: | + Whether the user is subscribed to the stream. + - example: + { "msg": "", "result": "success", "is_subscribed": false } /users/me/subscriptions/muted_topics: patch: operationId: mute_topic @@ -2566,57 +2498,51 @@ paths: `PATCH {{ api_url }}/v1/users/me/subscriptions/muted_topics` parameters: - - $ref: '#/components/parameters/Stream' - required: false - - $ref: '#/components/parameters/StreamIdInQuery' - required: false - - name: topic - in: query - description: | - The topic to (un)mute. Note that the request will succeed regardless of - whether any messages have been sent to the specified topic. - schema: - type: string - example: dinner - required: true - - name: op - in: query - description: | - Whether to mute (`add`) or unmute (`remove`) the provided topic. - schema: - type: string - enum: - - add - - remove - example: add - required: true + - $ref: "#/components/parameters/Stream" + required: false + - $ref: "#/components/parameters/StreamIdInQuery" + required: false + - name: topic + in: query + description: | + The topic to (un)mute. Note that the request will succeed regardless of + whether any messages have been sent to the specified topic. + schema: + type: string + example: dinner + required: true + - name: op + in: query + description: | + Whether to mute (`add`) or unmute (`remove`) the provided topic. + schema: + type: string + enum: + - add + - remove + example: add + required: true responses: - '200': + "200": description: Success. content: application/json: schema: - $ref: '#/components/schemas/JsonSuccess' - '400': + $ref: "#/components/schemas/JsonSuccess" + "400": description: Bad request. content: application/json: schema: oneOf: - - allOf: - - $ref: '#/components/schemas/JsonError' - - example: - { - "msg": "Topic already muted", - "result": "error" - } - - allOf: - - $ref: '#/components/schemas/JsonError' - - example: - { - "msg": "Topic is not muted", - "result": "error" - } + - allOf: + - $ref: "#/components/schemas/JsonError" + - example: + { "msg": "Topic already muted", "result": "error" } + - allOf: + - $ref: "#/components/schemas/JsonError" + - example: + { "msg": "Topic is not muted", "result": "error" } /realm/emoji/{emoji_name}: post: operationId: upload_custom_emoji @@ -2628,13 +2554,13 @@ paths: `POST {{ api_url }}/v1/realm/emoji/{emoji_name}` parameters: - - name: emoji_name - required: true - in: path - description: | - The name that should be associated with the uploaded emoji image/gif. - schema: - type: string + - name: emoji_name + required: true + in: path + description: | + The name that should be associated with the uploaded emoji image/gif. + schema: + type: string requestBody: content: multipart/form-data: @@ -2645,13 +2571,13 @@ paths: format: binary example: /path/to/img.png responses: - '200': + "200": description: Success. content: application/json: schema: allOf: - - $ref: '#/components/schemas/JsonSuccess' + - $ref: "#/components/schemas/JsonSuccess" /realm/emoji: get: @@ -2662,67 +2588,69 @@ paths: `GET {{ api_url }}/v1/realm/emoji` responses: - '200': + "200": description: Success. content: application/json: schema: allOf: - - $ref: '#/components/schemas/JsonSuccess' - - properties: - emoji: - type: object - description: | - An object that contains `emoji` objects, each identified with their - emoji ID as the key. - additionalProperties: + - $ref: "#/components/schemas/JsonSuccess" + - properties: + emoji: type: object - additionalProperties: false description: | - `{emoji_id}`: Object containing details about the emoji with - the specified ID. It has the following properties: - properties: - id: - type: string - description: | - The ID for this emoji, same as the object's key. - name: - type: string - description: | - The user-friendly name for this emoji. Users in the organization - can use this emoji by writing this name between colons (`:name :`). - source_url: - type: string - description: | - The path relative to the organization's URL where the - emoji's image can be found. - deactivated: - type: boolean - description: | - Whether the emoji has been deactivated or not. - author_id: - type: integer - nullable: true - description: | - The user ID of the user who uploaded the custom emoji. - Will be null if the uploader is unknown. + An object that contains `emoji` objects, each identified with their + emoji ID as the key. + additionalProperties: + type: object + additionalProperties: false + description: | + `{emoji_id}`: Object containing details about the emoji with + the specified ID. It has the following properties: + properties: + id: + type: string + description: | + The ID for this emoji, same as the object's key. + name: + type: string + description: | + The user-friendly name for this emoji. Users in the organization + can use this emoji by writing this name between colons (`:name :`). + source_url: + type: string + description: | + The path relative to the organization's URL where the + emoji's image can be found. + deactivated: + type: boolean + description: | + Whether the emoji has been deactivated or not. + author_id: + type: integer + nullable: true + description: | + The user ID of the user who uploaded the custom emoji. + Will be null if the uploader is unknown. - **Changes**: New in Zulip 3.0 (feature level 7). Previously - was accessible via and `author` object with an `id` field. - - example: - { + **Changes**: New in Zulip 3.0 (feature level 7). Previously + was accessible via and `author` object with an `id` field. + - example: + { "result": "success", "msg": "", - "emoji": { - "1": { + "emoji": + { + "1": + { "id": "1", "name": "green_tick", "source_url": "/user_avatars/1/emoji/images/1.png", "deactivated": false, - "author_id": 5 - } - } - } + "author_id": 5, + }, + }, + } /users/me/subscriptions/properties: post: operationId: update_subscription_settings @@ -2734,112 +2662,117 @@ paths: `POST {{ api_url }}/v1/users/me/subscriptions/properties` parameters: - - name: subscription_data - in: query - description: | - A list of objects that describe the changes that should be applied in - each subscription. Each object represents a subscription, and must have - a `stream_id` key that identifies the stream, as well as the `property` - being modified and its new `value`. - content: - application/json: - schema: - type: array - items: - type: object - example: [{"stream_id": 1, "property": "pin_to_top", "value": true}, {"stream_id": 3, "property": "color", "value": '#f00f00'}] - required: true + - name: subscription_data + in: query + description: | + A list of objects that describe the changes that should be applied in + each subscription. Each object represents a subscription, and must have + a `stream_id` key that identifies the stream, as well as the `property` + being modified and its new `value`. + content: + application/json: + schema: + type: array + items: + type: object + example: + [ + { "stream_id": 1, "property": "pin_to_top", "value": true }, + { "stream_id": 3, "property": "color", "value": "#f00f00" }, + ] + required: true responses: - '200': + "200": description: Success. content: application/json: schema: allOf: - - $ref: '#/components/schemas/JsonSuccess' - - properties: - subscription_data: - type: array - items: - type: object - additionalProperties: false - properties: - property: - type: string - description: | - The property to be changed. It is one of: - *`color`: The hex value of the user's personal display color for the stream. + - $ref: "#/components/schemas/JsonSuccess" + - properties: + subscription_data: + type: array + items: + type: object + additionalProperties: false + properties: + property: + type: string + description: | + The property to be changed. It is one of: + *`color`: The hex value of the user's personal display color for the stream. - *`is_muted`: Whether the stream is [muted](/help/mute-a-stream). + *`is_muted`: Whether the stream is [muted](/help/mute-a-stream). - **Changes**: Prior to Zulip 2.1, this feature was - represented by the more confusingly named `in_home_view` (with the - opposite value, `in_home_view=!is_muted`); for - backwards-compatibility, modern Zulip still accepts that value. + **Changes**: Prior to Zulip 2.1, this feature was + represented by the more confusingly named `in_home_view` (with the + opposite value, `in_home_view=!is_muted`); for + backwards-compatibility, modern Zulip still accepts that value. - *`pin_to_top`: Whether to pin the stream at the top of the stream list. + *`pin_to_top`: Whether to pin the stream at the top of the stream list. - *`desktop_notifications`: Whether to show desktop notifications for all - messages sent to the stream. + *`desktop_notifications`: Whether to show desktop notifications for all + messages sent to the stream. - *`audible_notifications`: Whether to play a sound notification for all - messages sent to the stream. + *`audible_notifications`: Whether to play a sound notification for all + messages sent to the stream. - *`push_notifications`: Whether to trigger a mobile push notification for - all messages sent to the stream. + *`push_notifications`: Whether to trigger a mobile push notification for + all messages sent to the stream. - *`email_notifications`: Whether to trigger an email notification for all - messages sent to the stream. + *`email_notifications`: Whether to trigger an email notification for all + messages sent to the stream. - *`in_home_view`: Whether to mute the stream (Legacy property) + *`in_home_view`: Whether to mute the stream (Legacy property) - *`wildcard_mentions_notify`: whether wildcard mentions trigger notifications - as though they were personal mentions in this stream. + *`wildcard_mentions_notify`: whether wildcard mentions trigger notifications + as though they were personal mentions in this stream. - A null value means the value of this setting - should be inherited from the user-level default - setting, wildcard_mentions_notify, for - this stream. - enum: - - color - - push_notifications - - is_muted - - pin_to_top - - desktop_notifications - - audible_notifications - - push_notifications - - email_notifications - - in_home_view - - wildcard_mentions_notify - value: - description: | - The desired value of the property - oneOf: - - type: boolean - - type: string - stream_id: - description: | - The desired value of the property - type: integer - description: | - The same `subscription_data` array sent by the client for the request. - - example: - { - "subscription_data": [ + A null value means the value of this setting + should be inherited from the user-level default + setting, wildcard_mentions_notify, for + this stream. + enum: + - color + - push_notifications + - is_muted + - pin_to_top + - desktop_notifications + - audible_notifications + - push_notifications + - email_notifications + - in_home_view + - wildcard_mentions_notify + value: + description: | + The desired value of the property + oneOf: + - type: boolean + - type: string + stream_id: + description: | + The desired value of the property + type: integer + description: | + The same `subscription_data` array sent by the client for the request. + - example: + { + "subscription_data": + [ { - "property": "pin_to_top", - "value": true, - "stream_id": 1 + "property": "pin_to_top", + "value": true, + "stream_id": 1, }, { - "property": "color", - "value": '#f00f00', - "stream_id": 3 - } - ], + "property": "color", + "value": "#f00f00", + "stream_id": 3, + }, + ], "result": "success", - "msg": "" - } + "msg": "", + } /users/{user_id}: get: operationId: get_user @@ -2853,68 +2786,63 @@ paths: *This endpoint is new in Zulip Server 3.0 (feature level 1).* parameters: - - $ref: '#/components/parameters/UserId' - - $ref: '#/components/parameters/ClientGravatar' - - $ref: '#/components/parameters/IncludeCustomProfileFields' + - $ref: "#/components/parameters/UserId" + - $ref: "#/components/parameters/ClientGravatar" + - $ref: "#/components/parameters/IncludeCustomProfileFields" responses: - '200': + "200": description: Success. content: application/json: schema: allOf: - - $ref: '#/components/schemas/JsonSuccess' - - properties: - user: - $ref: '#/components/schemas/User' - - example: - { - "msg": "", - "result": "success", - "user": { - "date_joined": "2019-10-20T07:50:53.729659+00:00", - "full_name": "King Hamlet", - "is_guest": false, - "profile_data": { - "4": { - "value": "vim" - }, - "2": { - "value": "I am:\n* The prince of Denmark\n* Nephew to the usurping Claudius", - "rendered_value": "

I am:

\n
    \n
  • The prince of Denmark
    • \n
  • Nephew to the usurping Claudius
    • \n
" - }, - "5": { - "value": "1900-1-1" - }, - "7": { - "value": "[11]" - }, - "6": { - "value": "https://blog.zulig.org" - }, - "1": { - "value": "+0-11-23-456-7890", - "rendered_value": "

+0-11-23-456-7890

" - }, - "8": { - "value": "zulipbot" - }, - "3": { - "rendered_value": "

Dark chocolate

", - "value": "Dark chocolate" - } - }, - "user_id": 10, - "is_bot": false, - "bot_type": null, - "timezone": "", - "is_admin": false, - "is_owner": false, - "avatar_url": "https://secure.gravatar.com/avatar/6d8cad0fd00256e7b40691d27ddfd466?d=identicon&version=1", - "is_active": true, - "email": "hamlet@zulip.com" - } - } + - $ref: "#/components/schemas/JsonSuccess" + - properties: + user: + $ref: "#/components/schemas/User" + - example: + { + "msg": "", + "result": "success", + "user": + { + "date_joined": "2019-10-20T07:50:53.729659+00:00", + "full_name": "King Hamlet", + "is_guest": false, + "profile_data": + { + "4": { "value": "vim" }, + "2": + { + "value": "I am:\n* The prince of Denmark\n* Nephew to the usurping Claudius", + "rendered_value": "

I am:

\n
    \n
  • The prince of Denmark
    • \n
  • Nephew to the usurping Claudius
    • \n
", + }, + "5": { "value": "1900-1-1" }, + "7": { "value": "[11]" }, + "6": { "value": "https://blog.zulig.org" }, + "1": + { + "value": "+0-11-23-456-7890", + "rendered_value": "

+0-11-23-456-7890

", + }, + "8": { "value": "zulipbot" }, + "3": + { + "rendered_value": "

Dark chocolate

", + "value": "Dark chocolate", + }, + }, + "user_id": 10, + "is_bot": false, + "bot_type": null, + "timezone": "", + "is_admin": false, + "is_owner": false, + "avatar_url": "https://secure.gravatar.com/avatar/6d8cad0fd00256e7b40691d27ddfd466?d=identicon&version=1", + "is_active": true, + "email": "hamlet@zulip.com", + }, + } patch: operationId: update_user tags: ["users"] @@ -2930,76 +2858,71 @@ paths: [role](/help/roles-and-permissions), and [custom profile fields](/help/add-custom-profile-fields). parameters: - - $ref: '#/components/parameters/UserId' - - name: full_name - in: query - description: | - The user's full name. - content: - application/json: - schema: - type: string - example: NewName - required: false - - name: role - in: query - description: | - New [role](/help/roles-and-permissions) for the user. Roles are encoded as: + - $ref: "#/components/parameters/UserId" + - name: full_name + in: query + description: | + The user's full name. + content: + application/json: + schema: + type: string + example: NewName + required: false + - name: role + in: query + description: | + New [role](/help/roles-and-permissions) for the user. Roles are encoded as: - * Organization owner: 100 - * Organization administrator: 200 - * Member: 400 - * Guest: 600 + * Organization owner: 100 + * Organization administrator: 200 + * Member: 400 + * Guest: 600 - Only organization owners can add or remove the owner role. + Only organization owners can add or remove the owner role. - The owner role cannot be removed from the only organization owner. + The owner role cannot be removed from the only organization owner. - **Changes**: New in Zulip 3.0 (feature level 8), replacing the previous - pair of `is_admin` and `is_guest` boolean parameters. - schema: - type: integer - example: 400 - required: false - - name: profile_data - in: query - description: | - A dictionary containing the to be updated custom profile field data for the user. - content: - application/json: - schema: - type: array - items: - type: object - example: [ - { - "id": 4, - "value": "vim" - }, - { - "id": 5, - "value": "1909-04-05" - }, - ] - required: false + **Changes**: New in Zulip 3.0 (feature level 8), replacing the previous + pair of `is_admin` and `is_guest` boolean parameters. + schema: + type: integer + example: 400 + required: false + - name: profile_data + in: query + description: | + A dictionary containing the to be updated custom profile field data for the user. + content: + application/json: + schema: + type: array + items: + type: object + example: + [ + { "id": 4, "value": "vim" }, + { "id": 5, "value": "1909-04-05" }, + ] + required: false responses: - '200': - $ref: '#/components/responses/SimpleSuccess' + "200": + $ref: "#/components/responses/SimpleSuccess" - '400': + "400": description: Bad request. content: application/json: schema: allOf: - - $ref: '#/components/schemas/CodedError' - - example: - { + - $ref: "#/components/schemas/CodedError" + - example: + { "result": "error", "msg": "Guests cannot be organization administrators", - "code": "BAD_REQUEST" - } + "code": "BAD_REQUEST", + } delete: operationId: deactivate_user @@ -3013,32 +2936,28 @@ paths: `DELETE {{ api_url }}/v1/users/{user_id}` parameters: - - $ref: '#/components/parameters/UserId' + - $ref: "#/components/parameters/UserId" responses: - '200': + "200": description: Success content: application/json: schema: allOf: - - $ref: '#/components/schemas/JsonSuccess' - - example: - { - "msg": "", - "result": "success", - } - '400': + - $ref: "#/components/schemas/JsonSuccess" + - example: { "msg": "", "result": "success" } + "400": description: Bad Request content: application/json: schema: allOf: - - $ref: '#/components/schemas/JsonError' - - example: - { + - $ref: "#/components/schemas/JsonError" + - example: + { "msg": "Cannot deactivate the only organization administrator", - "result": "error" - } + "result": "error", + } /realm/filters: get: operationId: get_linkifiers @@ -3051,42 +2970,43 @@ paths: `GET {{ api_url }}/v1/realm/filters` responses: - '200': + "200": description: Success. content: application/json: schema: allOf: - - $ref: '#/components/schemas/JsonSuccess' - - properties: - filters: - type: array - items: + - $ref: "#/components/schemas/JsonSuccess" + - properties: + filters: type: array items: - oneOf: - - type: string - - type: integer - description: | - An array of tuples, each representing one of - the linkifiers set up in the - organization. Each of these tuples contain the - pattern, the formatted URL and the filter's - ID, in that order. See the [Create - linkifiers](/api/add-linkifier) article for - details on what each field means. - - example: - { + type: array + items: + oneOf: + - type: string + - type: integer + description: | + An array of tuples, each representing one of + the linkifiers set up in the + organization. Each of these tuples contain the + pattern, the formatted URL and the filter's + ID, in that order. See the [Create + linkifiers](/api/add-linkifier) article for + details on what each field means. + - example: + { "msg": "", - "filters": [ + "filters": + [ [ - "#(?P[0-9]+)", - "https://github.com/zulip/zulip/issues/%(id)s", - 1 - ] - ], - "result": "success" - } + "#(?P[0-9]+)", + "https://github.com/zulip/zulip/issues/%(id)s", + 1, + ], + ], + "result": "success", + } post: operationId: add_linkifier tags: ["server_and_organizations"] @@ -3097,45 +3017,40 @@ paths: `POST {{ api_url }}/v1/realm/filters` parameters: - - name: pattern - in: query - description: | - The [Python regular - expression](https://docs.python.org/3/howto/regex.html) that should - trigger the linkifier. - schema: - type: string - example: '#(?P[0-9]+)' - required: true - - name: url_format_string - in: query - description: | - The URL used for the link. If you used named groups for the `pattern`, - you can insert their content here with - `%(name_of_the_capturing_group)s`. - schema: - type: string - example: https://github.com/zulip/zulip/issues/%(id)s - required: true + - name: pattern + in: query + description: | + The [Python regular + expression](https://docs.python.org/3/howto/regex.html) that should + trigger the linkifier. + schema: + type: string + example: "#(?P[0-9]+)" + required: true + - name: url_format_string + in: query + description: | + The URL used for the link. If you used named groups for the `pattern`, + you can insert their content here with + `%(name_of_the_capturing_group)s`. + schema: + type: string + example: https://github.com/zulip/zulip/issues/%(id)s + required: true responses: - '200': + "200": description: Success. content: application/json: schema: allOf: - - $ref: '#/components/schemas/JsonSuccess' - - properties: - id: - type: integer - description: | - The numeric ID assigned to this filter. - - example: - { - "id": 42, - "result": "success", - "msg": "" - } + - $ref: "#/components/schemas/JsonSuccess" + - properties: + id: + type: integer + description: | + The numeric ID assigned to this filter. + - example: { "id": 42, "result": "success", "msg": "" } /realm/filters/{filter_id}: delete: operationId: remove_linkifier @@ -3147,21 +3062,21 @@ paths: `DELETE {{ api_url }}/v1/realm/filters/{filter_id}` parameters: - - name: filter_id - in: path - description: | - The ID of the filter that you want to remove. - schema: - type: integer - example: 42 - required: true + - name: filter_id + in: path + description: | + The ID of the filter that you want to remove. + schema: + type: integer + example: 42 + required: true responses: - '200': + "200": description: Success. content: application/json: schema: - $ref: '#/components/schemas/JsonSuccess' + $ref: "#/components/schemas/JsonSuccess" /register: post: operationId: register_queue @@ -3172,136 +3087,135 @@ paths: other Zulip data the current user has access to), as well as to fetch the current state of that data. parameters: - - name: apply_markdown - in: query - description: | - Set to `true` if you would like the content to be rendered in HTML - format (otherwise the API will return the raw text that the user - entered) - schema: - type: boolean - default: false - example: true - - $ref: '#/components/parameters/ClientGravatar' - - name: slim_presence - in: query - description: | - Setting this to `true` will make presence dictionaries be keyed by - user_id instead of email. + - name: apply_markdown + in: query + description: | + Set to `true` if you would like the content to be rendered in HTML + format (otherwise the API will return the raw text that the user + entered) + schema: + type: boolean + default: false + example: true + - $ref: "#/components/parameters/ClientGravatar" + - name: slim_presence + in: query + description: | + Setting this to `true` will make presence dictionaries be keyed by + user_id instead of email. - **Changes**: New in Zulip 3.0 (Unstable with no feature level yet). - schema: - type: boolean - default: false - example: true - - $ref: '#/components/parameters/Event_types' - - name: all_public_streams - in: query - description: | - Set to `True` if you would like to receive events that occur within all - public streams. - schema: - type: boolean - default: false - example: true - - $ref: '#/components/parameters/IncludeSubscribers' - - name: client_capabilities - in: query - description: | - Dictionary containing details on features the client supports that are - relevant to the format of responses sent by the server. + **Changes**: New in Zulip 3.0 (Unstable with no feature level yet). + schema: + type: boolean + default: false + example: true + - $ref: "#/components/parameters/Event_types" + - name: all_public_streams + in: query + description: | + Set to `True` if you would like to receive events that occur within all + public streams. + schema: + type: boolean + default: false + example: true + - $ref: "#/components/parameters/IncludeSubscribers" + - name: client_capabilities + in: query + description: | + Dictionary containing details on features the client supports that are + relevant to the format of responses sent by the server. - * `notification_settings_null`: Boolean for whether the - client can handle the current API with null values for - stream-level notification settings (which means the stream - is not customized and should inherit the user's global - notification settings for stream messages). New in Zulip - 2.1.0; in earlier Zulip releases, stream-level - notification settings were simple booleans. + * `notification_settings_null`: Boolean for whether the + client can handle the current API with null values for + stream-level notification settings (which means the stream + is not customized and should inherit the user's global + notification settings for stream messages). New in Zulip + 2.1.0; in earlier Zulip releases, stream-level + notification settings were simple booleans. - * `bulk_message_deletion`: Boolean for whether the client's - handler for the `delete_message` event type has been - updated to process the new bulk format (with a - `message_ids`, rather than a singleton `message_id`). - Otherwise, the server will send `delete_message` events - in a loop. New in Zulip 3.0 (feature level 13). This - capability is for backwards-compatibility; it will be - required in a future server release. + * `bulk_message_deletion`: Boolean for whether the client's + handler for the `delete_message` event type has been + updated to process the new bulk format (with a + `message_ids`, rather than a singleton `message_id`). + Otherwise, the server will send `delete_message` events + in a loop. New in Zulip 3.0 (feature level 13). This + capability is for backwards-compatibility; it will be + required in a future server release. - * `user_avatar_url_field_optional`: Boolean for whether the - client required avatar URLs for all users, or supports - using `GET /avatar/{user_id}` to access user avatars. If the - client has this capability, the server may skip sending a - `avatar_url` field in the `realm_user` at its sole discretion - to optimize network performance. This is an important optimization - in organizations with 10,000s of users. - New in Zulip 3.0 (feature level 18). - content: - application/json: - schema: - type: object - example: - { - "notification_settings_null": true - } - - name: fetch_event_types - in: query - description: | - Same as the `event_types` parameter except that the values in - `fetch_event_types` are used to fetch initial data. If - `fetch_event_types` is not provided, `event_types` is used and if - `event_types` is not provided, this parameter defaults to `None`. - content: - application/json: - schema: - type: array - items: - type: string - example: ['message'] - - $ref: '#/components/parameters/Narrow' + * `user_avatar_url_field_optional`: Boolean for whether the + client required avatar URLs for all users, or supports + using `GET /avatar/{user_id}` to access user avatars. If the + client has this capability, the server may skip sending a + `avatar_url` field in the `realm_user` at its sole discretion + to optimize network performance. This is an important optimization + in organizations with 10,000s of users. + New in Zulip 3.0 (feature level 18). + content: + application/json: + schema: + type: object + example: { "notification_settings_null": true } + - name: fetch_event_types + in: query + description: | + Same as the `event_types` parameter except that the values in + `fetch_event_types` are used to fetch initial data. If + `fetch_event_types` is not provided, `event_types` is used and if + `event_types` is not provided, this parameter defaults to `None`. + content: + application/json: + schema: + type: array + items: + type: string + example: ["message"] + - $ref: "#/components/parameters/Narrow" responses: - '200': + "200": description: Success. content: application/json: schema: allOf: - - $ref: '#/components/schemas/JsonSuccess' - - properties: - queue_id: - type: string - description: | - The ID of the queue that has been allocated for your client. - last_event_id: - type: integer - description: | - The initial value of `last_event_id` to pass to `GET /api/v1/events`. - zulip_feature_level: - type: integer - description: | - The server's current [Zulip feature level](/api/changelog). - zulip_version: - type: string - description: | - The server's version. - - example: - { + - $ref: "#/components/schemas/JsonSuccess" + - properties: + queue_id: + type: string + description: | + The ID of the queue that has been allocated for your client. + last_event_id: + type: integer + description: | + The initial value of `last_event_id` to pass to `GET /api/v1/events`. + zulip_feature_level: + type: integer + description: | + The server's current [Zulip feature level](/api/changelog). + zulip_version: + type: string + description: | + The server's version. + - example: + { "last_event_id": -1, "msg": "", "queue_id": "1517975029:0", - "realm_emoji": { - "1": { + "realm_emoji": + { + "1": + { "author_id": 5, "deactivated": false, "id": "1", "name": "green_tick", - "source_url": "/user_avatars/1/emoji/images/1.png" - } - }, + "source_url": "/user_avatars/1/emoji/images/1.png", + }, + }, "result": "success", "zulip_feature_level": 2, - "zulip_version": "2.1.0" - } + "zulip_version": "2.1.0", + } /server_settings: get: operationId: get_server_settings @@ -3319,185 +3233,186 @@ paths: know in order to display a login prompt for the server (e.g. what authentication methods are available). responses: - '200': + "200": description: Success. content: application/json: schema: allOf: - - $ref: '#/components/schemas/JsonSuccess' - - properties: - authentication_methods: - type: object - additionalProperties: false - deprecated: true - description: | - Each key-value pair in the object indicates whether the authentication - method is enabled on this server. - - **Changes**: Deprecated in Zulip 2.1, in favor of the more expressive - `external_authentication_methods`. - properties: - password: - description: | - Whether the user can authenticate using password. - type: boolean - dev: - description: | - Whether the user can authenticate using development api key. - type: boolean - email: - description: | - Whether the user can authenticate using email. - type: boolean - ldap: - description: | - Whether the user can authenticate using ldap. - type: boolean - remoteuser: - description: | - Whether the user can authenticate using remoteuser. - type: boolean - github: - description: | - Whether the user can authenticate using their github account. - type: boolean - azuread: - description: | - Whether the user can authenticate using their azuread account. - type: boolean - gitlab: - description: | - Whether the user can authenticate using their gitlab account. - type: boolean - apple: - description: | - Whether the user can authenticate using their apple account. - type: boolean - google: - description: | - Whether the user can authenticate using their google account. - type: boolean - saml: - description: | - Whether the user can authenticate using saml. - type: boolean - external_authentication_methods: - type: array - description: | - A list of dictionaries describing the available external - authentication methods (E.g. Google, GitHub, or SAML) - enabled for this organization. - - The list is sorted in the order in which these - authentication methods should be displayed. - - **Changes**: New in Zulip 2.1. - items: + - $ref: "#/components/schemas/JsonSuccess" + - properties: + authentication_methods: type: object additionalProperties: false + deprecated: true + description: | + Each key-value pair in the object indicates whether the authentication + method is enabled on this server. + + **Changes**: Deprecated in Zulip 2.1, in favor of the more expressive + `external_authentication_methods`. properties: - name: - type: string + password: description: | - A unique, table, machine-readable name for the authentication method, - intended to be used by clients with special behavior for specific - authenatication methods to correctly identify the method. - display_name: - type: string + Whether the user can authenticate using password. + type: boolean + dev: description: | - Display name of the authentication method, to be used in all buttons - for the authentication method. - display_icon: - type: string - nullable: true + Whether the user can authenticate using development api key. + type: boolean + email: description: | - URL for an image to be displayed as an icon in all buttons for - the external authentication method. + Whether the user can authenticate using email. + type: boolean + ldap: + description: | + Whether the user can authenticate using ldap. + type: boolean + remoteuser: + description: | + Whether the user can authenticate using remoteuser. + type: boolean + github: + description: | + Whether the user can authenticate using their github account. + type: boolean + azuread: + description: | + Whether the user can authenticate using their azuread account. + type: boolean + gitlab: + description: | + Whether the user can authenticate using their gitlab account. + type: boolean + apple: + description: | + Whether the user can authenticate using their apple account. + type: boolean + google: + description: | + Whether the user can authenticate using their google account. + type: boolean + saml: + description: | + Whether the user can authenticate using saml. + type: boolean + external_authentication_methods: + type: array + description: | + A list of dictionaries describing the available external + authentication methods (E.g. Google, GitHub, or SAML) + enabled for this organization. - When null, no icon should be displayed. - login_url: - type: string - description: | - URL to be used to initiate authentication using this method. - signup_url: - type: string - description: | - URL to be used to initiate account registration using this method. - zulip_version: - type: string - description: | - The version of Zulip running in the server. - zulip_feature_level: - type: integer - description: | - An integer indicating what features are - available on the server. The feature level increases monotonically; - a value of N means the server supports all API features introduced - before feature level N. This is designed to provide a simple way - for client apps to decide whether the server supports a given - feature or API change. See the [changelog](/api/changelog) for - details on what each feature level means. + The list is sorted in the order in which these + authentication methods should be displayed. - **Changes**. New in Zulip 3.0. We recommend using an implied value - of 0 for Zulip servers that do not send this field. - push_notifications_enabled: - type: boolean - description: | - Whether mobile/push notifications are enabled. - is_incompatible: - type: boolean - description: | - Whether the Zulip client that has sent a request to this endpoint is - deemed incompatible with the server. - email_auth_enabled: - type: boolean - description: | - Setting for allowing users authenticate with an email-password - combination. - require_email_format_usernames: - type: boolean - description: | - Whether all valid usernames for authentication to this - organization will be email addresses. This is important - for clients to know whether to do client side validation - of email address format in a login prompt. + **Changes**: New in Zulip 2.1. + items: + type: object + additionalProperties: false + properties: + name: + type: string + description: | + A unique, table, machine-readable name for the authentication method, + intended to be used by clients with special behavior for specific + authenatication methods to correctly identify the method. + display_name: + type: string + description: | + Display name of the authentication method, to be used in all buttons + for the authentication method. + display_icon: + type: string + nullable: true + description: | + URL for an image to be displayed as an icon in all buttons for + the external authentication method. - This value will be false if the server has [LDAP - authentication][ldap-auth] enabled with a username and - password combination. - realm_uri: - type: string - description: | - The organization's canonical URL. - realm_name: - type: string - description: | - The organization's name (for display purposes). - realm_icon: - type: string - description: | - The URL for the organization's logo formatted as a square image, - used for identifying the organization in small locations in the - mobile and desktop apps. - realm_description: - type: string - description: | - HTML description of the organization, as configured by the [organization - profile](/help/create-your-organization-profile). - - example: - { - "authentication_methods": { - "password": true, - "dev": true, - "email": true, - "ldap": false, - "remoteuser": false, - "github": true, - "azuread": false, - "google": true, - "saml": true - }, + When null, no icon should be displayed. + login_url: + type: string + description: | + URL to be used to initiate authentication using this method. + signup_url: + type: string + description: | + URL to be used to initiate account registration using this method. + zulip_version: + type: string + description: | + The version of Zulip running in the server. + zulip_feature_level: + type: integer + description: | + An integer indicating what features are + available on the server. The feature level increases monotonically; + a value of N means the server supports all API features introduced + before feature level N. This is designed to provide a simple way + for client apps to decide whether the server supports a given + feature or API change. See the [changelog](/api/changelog) for + details on what each feature level means. + + **Changes**. New in Zulip 3.0. We recommend using an implied value + of 0 for Zulip servers that do not send this field. + push_notifications_enabled: + type: boolean + description: | + Whether mobile/push notifications are enabled. + is_incompatible: + type: boolean + description: | + Whether the Zulip client that has sent a request to this endpoint is + deemed incompatible with the server. + email_auth_enabled: + type: boolean + description: | + Setting for allowing users authenticate with an email-password + combination. + require_email_format_usernames: + type: boolean + description: | + Whether all valid usernames for authentication to this + organization will be email addresses. This is important + for clients to know whether to do client side validation + of email address format in a login prompt. + + This value will be false if the server has [LDAP + authentication][ldap-auth] enabled with a username and + password combination. + realm_uri: + type: string + description: | + The organization's canonical URL. + realm_name: + type: string + description: | + The organization's name (for display purposes). + realm_icon: + type: string + description: | + The URL for the organization's logo formatted as a square image, + used for identifying the organization in small locations in the + mobile and desktop apps. + realm_description: + type: string + description: | + HTML description of the organization, as configured by the [organization + profile](/help/create-your-organization-profile). + - example: + { + "authentication_methods": + { + "password": true, + "dev": true, + "email": true, + "ldap": false, + "remoteuser": false, + "github": true, + "azuread": false, + "google": true, + "saml": true, + }, "zulip_version": "2.0.6+git", "push_notifications_enabled": false, "msg": "", @@ -3509,30 +3424,31 @@ paths: "realm_icon": "https://secure.gravatar.com/avatar/62429d594b6ffc712f54aee976a18b44?d=identicon", "realm_description": "

The Zulip development environment default organization. It's great for testing!

", "result": "success", - "external_authentication_methods": [ - { - "name": "saml:idp_name", - "display_name": "SAML", - "display_icon": null, - "login_url": "/accounts/login/social/saml/idp_name", - "signup_url": "/accounts/register/social/saml/idp_name" - }, - { - "name": "google", - "display_name": "Google", - "display_icon": "/static/images/landing-page/logos/googl_e-icon.png", - "login_url": "/accounts/login/social/google", - "signup_url": "/accounts/register/social/google" - }, - { - "name": "github", - "display_name": "GitHub", - "display_icon": "/static/images/landing-page/logos/github-icon.png", - "login_url": "/accounts/login/social/github", - "signup_url": "/accounts/register/social/github" - } - ] - } + "external_authentication_methods": + [ + { + "name": "saml:idp_name", + "display_name": "SAML", + "display_icon": null, + "login_url": "/accounts/login/social/saml/idp_name", + "signup_url": "/accounts/register/social/saml/idp_name", + }, + { + "name": "google", + "display_name": "Google", + "display_icon": "/static/images/landing-page/logos/googl_e-icon.png", + "login_url": "/accounts/login/social/google", + "signup_url": "/accounts/register/social/google", + }, + { + "name": "github", + "display_name": "GitHub", + "display_icon": "/static/images/landing-page/logos/github-icon.png", + "login_url": "/accounts/login/social/github", + "signup_url": "/accounts/register/social/github", + }, + ], + } /settings/notifications: patch: operationId: update_notification_settings @@ -3544,214 +3460,214 @@ paths: `PATCH {{ api_url }}/v1/settings/notifications` parameters: - - name: enable_stream_desktop_notifications - in: query - description: | - Enable visual desktop notifications for stream messages. - schema: - type: boolean - example: true - - name: enable_stream_email_notifications - in: query - description: | - Enable email notifications for stream messages. - schema: - type: boolean - example: true - - name: enable_stream_push_notifications - in: query - description: | - Enable mobile notifications for stream messages. - schema: - type: boolean - example: true - - name: enable_stream_audible_notifications - in: query - description: | - Enable audible desktop notifications for stream messages. - schema: - type: boolean - example: true - - name: notification_sound - in: query - description: | - Notification sound name. - content: - application/json: - schema: - type: string - example: ding - - name: enable_desktop_notifications - in: query - description: | - Enable visual desktop notifications for private messages and @-mentions. - schema: - type: boolean - example: true - - name: enable_sounds - in: query - description: | - Enable audible desktop notifications for private messages and - @-mentions. - schema: - type: boolean - example: true - - name: enable_offline_email_notifications - in: query - description: | - Enable email notifications for private messages and @-mentions received - when the user is offline. - schema: - type: boolean - example: true - - name: enable_offline_push_notifications - in: query - description: | - Enable mobile notification for private messages and @-mentions received - when the user is offline. - schema: - type: boolean - example: true - - name: enable_online_push_notifications - in: query - description: | - Enable mobile notification for private messages and @-mentions received - when the user is online. - schema: - type: boolean - example: true - - name: enable_digest_emails - in: query - description: | - Enable digest emails when the user is away. - schema: - type: boolean - example: true - - name: enable_login_emails - in: query - description: | - Enable email notifications for new logins to account. - schema: - type: boolean - example: true - - name: message_content_in_email_notifications - in: query - description: | - Include the message's content in missed messages email notifications. - schema: - type: boolean - example: true - - name: pm_content_in_desktop_notifications - in: query - description: | - Include content of private messages in desktop notifications. - schema: - type: boolean - example: true - - name: wildcard_mentions_notify - in: query - description: | - Whether wildcard mentions (E.g. @**all**) should send notifications - like a personal mention. - schema: - type: boolean - example: true - - name: desktop_icon_count_display - in: query - description: | - Unread count summary (appears in desktop sidebar and browser tab) - - * 1 - All unreads - * 2 - Private messages and mentions - * 3 - None - content: - application/json: - schema: - type: integer - enum: - - 1 - - 2 - - 3 - example: 1 - - name: realm_name_in_notifications - in: query - description: | - Include organization name in subject of missed message emails. - schema: - type: boolean - example: true - - name: presence_enabled - in: query - description: | - Display the presence status to other users when online. - schema: + - name: enable_stream_desktop_notifications + in: query + description: | + Enable visual desktop notifications for stream messages. + schema: type: boolean - example: true + example: true + - name: enable_stream_email_notifications + in: query + description: | + Enable email notifications for stream messages. + schema: + type: boolean + example: true + - name: enable_stream_push_notifications + in: query + description: | + Enable mobile notifications for stream messages. + schema: + type: boolean + example: true + - name: enable_stream_audible_notifications + in: query + description: | + Enable audible desktop notifications for stream messages. + schema: + type: boolean + example: true + - name: notification_sound + in: query + description: | + Notification sound name. + content: + application/json: + schema: + type: string + example: ding + - name: enable_desktop_notifications + in: query + description: | + Enable visual desktop notifications for private messages and @-mentions. + schema: + type: boolean + example: true + - name: enable_sounds + in: query + description: | + Enable audible desktop notifications for private messages and + @-mentions. + schema: + type: boolean + example: true + - name: enable_offline_email_notifications + in: query + description: | + Enable email notifications for private messages and @-mentions received + when the user is offline. + schema: + type: boolean + example: true + - name: enable_offline_push_notifications + in: query + description: | + Enable mobile notification for private messages and @-mentions received + when the user is offline. + schema: + type: boolean + example: true + - name: enable_online_push_notifications + in: query + description: | + Enable mobile notification for private messages and @-mentions received + when the user is online. + schema: + type: boolean + example: true + - name: enable_digest_emails + in: query + description: | + Enable digest emails when the user is away. + schema: + type: boolean + example: true + - name: enable_login_emails + in: query + description: | + Enable email notifications for new logins to account. + schema: + type: boolean + example: true + - name: message_content_in_email_notifications + in: query + description: | + Include the message's content in missed messages email notifications. + schema: + type: boolean + example: true + - name: pm_content_in_desktop_notifications + in: query + description: | + Include content of private messages in desktop notifications. + schema: + type: boolean + example: true + - name: wildcard_mentions_notify + in: query + description: | + Whether wildcard mentions (E.g. @**all**) should send notifications + like a personal mention. + schema: + type: boolean + example: true + - name: desktop_icon_count_display + in: query + description: | + Unread count summary (appears in desktop sidebar and browser tab) + + * 1 - All unreads + * 2 - Private messages and mentions + * 3 - None + content: + application/json: + schema: + type: integer + enum: + - 1 + - 2 + - 3 + example: 1 + - name: realm_name_in_notifications + in: query + description: | + Include organization name in subject of missed message emails. + schema: + type: boolean + example: true + - name: presence_enabled + in: query + description: | + Display the presence status to other users when online. + schema: + type: boolean + example: true responses: - '200': + "200": description: Success. content: application/json: schema: allOf: - - $ref: '#/components/schemas/JsonSuccess' - - properties: - enable_desktop_notifications: - type: boolean - description: | - The setting for `enable_desktop_notifications`, if it was changed in - this request. - enable_digest_emails: - type: boolean - description: | - The setting for `enable_digest_emails`, if it was changed in this - request. - enable_offline_email_notifications: - type: boolean - description: | - The setting for `enable_offline_email_notifications`, if it was changed - in this request. - enable_offline_push_notifications: - type: boolean - description: | - The setting for `enable_offline_push_notifications`, if it was changed - in this request. - enable_online_push_notifications: - type: boolean - description: | - The setting for `enable_online_push_notifications`, if it was changed in - this request. - enable_sounds: - type: boolean - description: | - The setting for `enable_sounds`, if it was changed in this request. - enable_stream_email_notifications: - type: boolean - description: | - The setting for `enable_stream_email_notifications`, if it was changed - in this request. - enable_stream_push_notifications: - type: boolean - description: | - The setting for `enable_stream_push_notifications`, if it was changed in - this request. - enable_stream_audible_notifications: - type: boolean - description: | - The setting for `enable_stream_audible_notifications`, if it was changed - in this request. - message_content_in_email_notifications: - type: boolean - description: | - The setting for `message_content_in_email_notifications`, if it was - changed in this request. - - example: - { + - $ref: "#/components/schemas/JsonSuccess" + - properties: + enable_desktop_notifications: + type: boolean + description: | + The setting for `enable_desktop_notifications`, if it was changed in + this request. + enable_digest_emails: + type: boolean + description: | + The setting for `enable_digest_emails`, if it was changed in this + request. + enable_offline_email_notifications: + type: boolean + description: | + The setting for `enable_offline_email_notifications`, if it was changed + in this request. + enable_offline_push_notifications: + type: boolean + description: | + The setting for `enable_offline_push_notifications`, if it was changed + in this request. + enable_online_push_notifications: + type: boolean + description: | + The setting for `enable_online_push_notifications`, if it was changed in + this request. + enable_sounds: + type: boolean + description: | + The setting for `enable_sounds`, if it was changed in this request. + enable_stream_email_notifications: + type: boolean + description: | + The setting for `enable_stream_email_notifications`, if it was changed + in this request. + enable_stream_push_notifications: + type: boolean + description: | + The setting for `enable_stream_push_notifications`, if it was changed in + this request. + enable_stream_audible_notifications: + type: boolean + description: | + The setting for `enable_stream_audible_notifications`, if it was changed + in this request. + message_content_in_email_notifications: + type: boolean + description: | + The setting for `message_content_in_email_notifications`, if it was + changed in this request. + - example: + { "enable_offline_push_notifications": true, "enable_online_push_notifications": true, "msg": "", - "result": "success" - } + "result": "success", + } /streams: get: operationId: get_streams @@ -3761,213 +3677,214 @@ paths: `GET {{ api_url }}/v1/streams` parameters: - - name: include_public - in: query - description: | - Include all public streams. - schema: - type: boolean - default: true - example: false - - name: include_subscribed - in: query - description: | - Include all streams that the user is subscribed to. - schema: - type: boolean - default: true - example: false - - name: include_all_active - in: query - description: | - Include all active streams. The user must have administrative privileges - to use this parameter. - schema: - type: boolean - default: false - example: true - - name: include_default - in: query - description: | - Include all default streams for the user's realm. - schema: - type: boolean - default: false - example: true - - name: include_owner_subscribed - in: query - description: | - If the user is a bot, include all streams that the bot's owner is - subscribed to. - schema: - type: boolean - default: false - example: true + - name: include_public + in: query + description: | + Include all public streams. + schema: + type: boolean + default: true + example: false + - name: include_subscribed + in: query + description: | + Include all streams that the user is subscribed to. + schema: + type: boolean + default: true + example: false + - name: include_all_active + in: query + description: | + Include all active streams. The user must have administrative privileges + to use this parameter. + schema: + type: boolean + default: false + example: true + - name: include_default + in: query + description: | + Include all default streams for the user's realm. + schema: + type: boolean + default: false + example: true + - name: include_owner_subscribed + in: query + description: | + If the user is a bot, include all streams that the bot's owner is + subscribed to. + schema: + type: boolean + default: false + example: true responses: - '200': + "200": description: Success. content: application/json: schema: allOf: - - $ref: '#/components/schemas/JsonSuccess' - - properties: - streams: - description: | - A list of `stream` objects with details on the requested streams. - type: array - items: - type: object - additionalProperties: false - properties: - stream_id: - type: integer - description: | - The unique ID of the stream. - name: - type: string - description: | - The name of the stream. - description: - type: string - description: | - The short description of the stream in text/markdown format, - intended to be used to prepopulate UI for editing a stream's - description. - invite_only: - type: boolean - description: | - Specifies whether the stream is private or not. - Only people who have been invited can access a private stream. - rendered_description: - type: string - description: | - The short description of the stream rendered as HTML, intended to - be used when displaying the stream description in a UI. + - $ref: "#/components/schemas/JsonSuccess" + - properties: + streams: + description: | + A list of `stream` objects with details on the requested streams. + type: array + items: + type: object + additionalProperties: false + properties: + stream_id: + type: integer + description: | + The unique ID of the stream. + name: + type: string + description: | + The name of the stream. + description: + type: string + description: | + The short description of the stream in text/markdown format, + intended to be used to prepopulate UI for editing a stream's + description. + invite_only: + type: boolean + description: | + Specifies whether the stream is private or not. + Only people who have been invited can access a private stream. + rendered_description: + type: string + description: | + The short description of the stream rendered as HTML, intended to + be used when displaying the stream description in a UI. - One should use the standard Zulip rendered_markdown CSS when - displaying this content so that emoji, LaTeX, and other syntax - work correctly. And any client-side security logic for - user-generated message content should be applied when displaying - this HTML as though it were the body of a Zulip message. - is_web_public: - type: boolean - description: | - Whether the stream has been configured to allow unauthenticated - access to its message history from the web. - stream_post_policy: - type: integer - description: | - Policy for which users can post messages to the stream. + One should use the standard Zulip rendered_markdown CSS when + displaying this content so that emoji, LaTeX, and other syntax + work correctly. And any client-side security logic for + user-generated message content should be applied when displaying + this HTML as though it were the body of a Zulip message. + is_web_public: + type: boolean + description: | + Whether the stream has been configured to allow unauthenticated + access to its message history from the web. + stream_post_policy: + type: integer + description: | + Policy for which users can post messages to the stream. - * 1 => Any user can post. - * 2 => Only administrators can post. - * 3 => Only new members can post. + * 1 => Any user can post. + * 2 => Only administrators can post. + * 3 => Only new members can post. - **Changes**: New in Zulip 3.0, replacing the previous - `is_announcement_only` boolean. - message_retention_days: - type: integer - nullable: true - description: | - Number of days that messages sent to this stream will be stored - before being automatically deleted by the [message retention - policy](/help/message-retention-policy). There are two special values: + **Changes**: New in Zulip 3.0, replacing the previous + `is_announcement_only` boolean. + message_retention_days: + type: integer + nullable: true + description: | + Number of days that messages sent to this stream will be stored + before being automatically deleted by the [message retention + policy](/help/message-retention-policy). There are two special values: - * `null`, the default, means the stream will inherit the organization - level setting. - * `-1` encodes retaining messages in this stream forever. + * `null`, the default, means the stream will inherit the organization + level setting. + * `-1` encodes retaining messages in this stream forever. - **Changes**: New in Zulip 3.0 (feature level 17). - history_public_to_subscribers: - type: boolean - description: | - Whether the history of the stream is public to its subscribers. + **Changes**: New in Zulip 3.0 (feature level 17). + history_public_to_subscribers: + type: boolean + description: | + Whether the history of the stream is public to its subscribers. - Currently always true for public streams (i.e. invite_only=False implies - history_public_to_subscribers=True), but clients should not make that - assumption, as we may change that behavior in the future. - first_message_id: - type: integer - nullable: true - description: | - The id of the first message in the stream. + Currently always true for public streams (i.e. invite_only=False implies + history_public_to_subscribers=True), but clients should not make that + assumption, as we may change that behavior in the future. + first_message_id: + type: integer + nullable: true + description: | + The id of the first message in the stream. - Intended to help clients determine whether they need to display - UI like the "more topics" widget that would suggest the stream - has older history that can be accessed. + Intended to help clients determine whether they need to display + UI like the "more topics" widget that would suggest the stream + has older history that can be accessed. - Null is used for streams with no message history. - is_announcement_only: - type: boolean - deprecated: true - description: | - Whether the given stream is announcement only or not. + Null is used for streams with no message history. + is_announcement_only: + type: boolean + deprecated: true + description: | + Whether the given stream is announcement only or not. - **Changes**: Deprecated in Zulip 3.0 (feature level 1), use - `stream_post_policy` instead. - is_default: - type: boolean - description: | - Whether the given stream is a - [default stream](/help/set-default-streams-for-new-users). Only - returned if the `include_default` parameter is `true`. - - example: - { + **Changes**: Deprecated in Zulip 3.0 (feature level 1), use + `stream_post_policy` instead. + is_default: + type: boolean + description: | + Whether the given stream is a + [default stream](/help/set-default-streams-for-new-users). Only + returned if the `include_default` parameter is `true`. + - example: + { "msg": "", "result": "success", - "streams": [ + "streams": + [ { - "description": "A Scandinavian country", - "invite_only": false, - "name": "Denmark", - "stream_id": 1 + "description": "A Scandinavian country", + "invite_only": false, + "name": "Denmark", + "stream_id": 1, }, { - "description": "Yet another Italian city", - "invite_only": false, - "name": "Rome", - "stream_id": 2 + "description": "Yet another Italian city", + "invite_only": false, + "name": "Rome", + "stream_id": 2, }, { - "description": "Located in the United Kingdom", - "invite_only": false, - "name": "Scotland", - "stream_id": 3 + "description": "Located in the United Kingdom", + "invite_only": false, + "name": "Scotland", + "stream_id": 3, }, { - "description": "A northeastern Italian city", - "invite_only": false, - "name": "Venice", - "stream_id": 4 + "description": "A northeastern Italian city", + "invite_only": false, + "name": "Venice", + "stream_id": 4, }, { - "description": "A city in Italy", - "invite_only": false, - "name": "Verona", - "stream_id": 5 + "description": "A city in Italy", + "invite_only": false, + "name": "Verona", + "stream_id": 5, }, { - "description": "New stream for testing", - "invite_only": false, - "name": "new stream", - "stream_id": 6 - } - ] - } - '400': + "description": "New stream for testing", + "invite_only": false, + "name": "new stream", + "stream_id": 6, + }, + ], + } + "400": description: Bad request. content: application/json: schema: allOf: - - $ref: '#/components/schemas/CodedError' - - example: - { + - $ref: "#/components/schemas/CodedError" + - example: + { "code": "BAD_REQUEST", "msg": "User not authorized for this query", - "result": "error" - } + "result": "error", + } /streams/{stream_id}: delete: operationId: delete_stream @@ -3977,36 +3894,32 @@ paths: `DELETE {{ api_url }}/v1/streams/{stream_id}` parameters: - - $ref: '#/components/parameters/StreamIdInPath' + - $ref: "#/components/parameters/StreamIdInPath" responses: - '200': + "200": description: Success. content: application/json: schema: allOf: - - $ref: '#/components/schemas/JsonSuccess' - - example: - { - "msg": "", - "result": "success" - } - '400': + - $ref: "#/components/schemas/JsonSuccess" + - example: { "msg": "", "result": "success" } + "400": description: Bad request. content: application/json: schema: allOf: - - $ref: '#/components/schemas/JsonError' - - properties: - msg: - type: string - - example: - { + - $ref: "#/components/schemas/JsonError" + - properties: + msg: + type: string + - example: + { "code": "BAD_REQUEST", "msg": "Invalid stream id", - "result": "error" - } + "result": "error", + } patch: operationId: update_stream tags: ["streams"] @@ -4022,76 +3935,72 @@ paths: `PATCH {{ api_url }}/v1/streams/{stream_id}` parameters: - - $ref: '#/components/parameters/StreamIdInPath' - - name: description - in: query - description: | - The new description for the stream. - content: - application/json: - schema: - type: string - example: This stream is related to football dicsussions. - required: false - - name: new_name - in: query - description: | - The new name for the stream. - content: - application/json: - schema: - type: string - example: Italy - required: false - - name: is_private - in: query - description: | - Change whether the stream is a private stream. - schema: - type: boolean - example: true - required: false - - name: is_announcement_only - in: query - deprecated: true - description: | - Whether the stream is limited to announcements. + - $ref: "#/components/parameters/StreamIdInPath" + - name: description + in: query + description: | + The new description for the stream. + content: + application/json: + schema: + type: string + example: This stream is related to football dicsussions. + required: false + - name: new_name + in: query + description: | + The new name for the stream. + content: + application/json: + schema: + type: string + example: Italy + required: false + - name: is_private + in: query + description: | + Change whether the stream is a private stream. + schema: + type: boolean + example: true + required: false + - name: is_announcement_only + in: query + deprecated: true + description: | + Whether the stream is limited to announcements. - **Changes**: Deprecated in Zulip 3.0 (feature level 1), use - `stream_post_policy` instead. - schema: - type: boolean - example: true - required: false - - $ref: '#/components/parameters/StreamPostPolicy' - - $ref: '#/components/parameters/HistoryPublicToSubscribers' - - $ref: '#/components/parameters/MessageRetentionDays' + **Changes**: Deprecated in Zulip 3.0 (feature level 1), use + `stream_post_policy` instead. + schema: + type: boolean + example: true + required: false + - $ref: "#/components/parameters/StreamPostPolicy" + - $ref: "#/components/parameters/HistoryPublicToSubscribers" + - $ref: "#/components/parameters/MessageRetentionDays" responses: - '200': + "200": description: Success. content: application/json: schema: allOf: - - $ref: '#/components/schemas/JsonSuccess' - - example: - { - "msg": "", - "result": "success" - } - '400': + - $ref: "#/components/schemas/JsonSuccess" + - example: { "msg": "", "result": "success" } + "400": description: Bad request. content: application/json: schema: allOf: - - $ref: '#/components/schemas/JsonError' - - example: - { + - $ref: "#/components/schemas/JsonError" + - example: + { "code": "BAD_REQUEST", "msg": "Invalid stream id", - "result": "error" - } + "result": "error", + } /typing: post: operationId: set_typing_status @@ -4104,43 +4013,43 @@ paths: `POST {{ api_url }}/v1/typing` parameters: - - name: op - in: query - description: | - Whether the user has started (`start`) or stopped (`stop`) to type. - schema: - type: string - enum: - - start - - stop - example: start - required: true - - name: to - in: query - description: | - The user_ids of the recipients of the message being typed. Typing - notifications are only supported for private messages. Send a - JSON-encoded list of user_ids. (Use a list even if there is only one - recipient.). + - name: op + in: query + description: | + Whether the user has started (`start`) or stopped (`stop`) to type. + schema: + type: string + enum: + - start + - stop + example: start + required: true + - name: to + in: query + description: | + The user_ids of the recipients of the message being typed. Typing + notifications are only supported for private messages. Send a + JSON-encoded list of user_ids. (Use a list even if there is only one + recipient.). - **Changes**: Before Zulip 2.0, this parameter accepted only a JSON-encoded - list of email addresses. Support for the email address-based format was - removed in Zulip 3.0 (feature level 11). - content: - application/json: - schema: - type: array - items: - type: integer - example: [9, 10] - required: true + **Changes**: Before Zulip 2.0, this parameter accepted only a JSON-encoded + list of email addresses. Support for the email address-based format was + removed in Zulip 3.0 (feature level 11). + content: + application/json: + schema: + type: array + items: + type: integer + example: [9, 10] + required: true responses: - '200': + "200": description: Success. content: application/json: schema: - $ref: '#/components/schemas/JsonSuccess' + $ref: "#/components/schemas/JsonSuccess" /user_groups/create: post: @@ -4151,61 +4060,57 @@ paths: `POST {{ api_url }}/v1/user_groups/create` parameters: - - name: name - in: query - description: | - The name of the user group. - schema: - type: string - example: marketing - required: true - - name: description - in: query - description: | - The description of the user group. - schema: - type: string - example: The marketing team. - required: true - - name: members - in: query - description: | - An array containing the user IDs of the initial members for the - new user group. - content: - application/json: - schema: - type: array - items: - type: integer - example: [1, 2, 3, 4] - required: true + - name: name + in: query + description: | + The name of the user group. + schema: + type: string + example: marketing + required: true + - name: description + in: query + description: | + The description of the user group. + schema: + type: string + example: The marketing team. + required: true + - name: members + in: query + description: | + An array containing the user IDs of the initial members for the + new user group. + content: + application/json: + schema: + type: array + items: + type: integer + example: [1, 2, 3, 4] + required: true responses: - '200': + "200": description: Success. content: application/json: schema: allOf: - - $ref: '#/components/schemas/JsonSuccess' - - example: - { - "msg": "", - "result": "success" - } - '400': + - $ref: "#/components/schemas/JsonSuccess" + - example: { "msg": "", "result": "success" } + "400": description: Bad request. content: application/json: schema: allOf: - - $ref: '#/components/schemas/JsonError' - - example: - { - "result": "error", - "code": "BAD_REQUEST", - "msg": "Invalid user ID: 500" - } + - $ref: "#/components/schemas/JsonError" + - example: + { + "result": "error", + "code": "BAD_REQUEST", + "msg": "Invalid user ID: 500", + } /user_groups/{group_id}: patch: operationId: update_user_group @@ -4215,40 +4120,40 @@ paths: `PATCH {{ api_url }}/v1/user_groups/{group_id}` parameters: - - $ref: '#/components/parameters/GroupId' - - name: name - in: query - description: | - The new name of the group. - schema: - type: string - example: marketing team - required: true - - name: description - in: query - description: | - The new description of the group. - schema: - type: string - example: The marketing team. - required: true + - $ref: "#/components/parameters/GroupId" + - name: name + in: query + description: | + The new name of the group. + schema: + type: string + example: marketing team + required: true + - name: description + in: query + description: | + The new description of the group. + schema: + type: string + example: The marketing team. + required: true responses: - '200': - $ref: '#/components/responses/SimpleSuccess' + "200": + $ref: "#/components/responses/SimpleSuccess" - '400': + "400": description: Bad request. content: application/json: schema: allOf: - - $ref: '#/components/schemas/JsonError' - - example: - { + - $ref: "#/components/schemas/JsonError" + - example: + { "code": "BAD_REQUEST", "msg": "Invalid user group", - "result": "error" - } + "result": "error", + } delete: operationId: remove_user_group tags: ["users"] @@ -4257,34 +4162,30 @@ paths: `DELETE {{ api_url }}/v1/user_groups/{group_id}` parameters: - - $ref: '#/components/parameters/GroupId' + - $ref: "#/components/parameters/GroupId" responses: - '200': + "200": description: Success. content: application/json: schema: allOf: - - $ref: '#/components/schemas/JsonSuccess' - - example: - { - "result": "success", - "msg": "", - } + - $ref: "#/components/schemas/JsonSuccess" + - example: { "result": "success", "msg": "" } - '400': + "400": description: Bad request. content: application/json: schema: allOf: - - $ref: '#/components/schemas/JsonError' - - example: - { + - $ref: "#/components/schemas/JsonError" + - example: + { "code": "BAD_REQUEST", "msg": "Invalid user group", - "result": "error" - } + "result": "error", + } /user_groups: get: @@ -4295,60 +4196,61 @@ paths: `GET {{ api_url }}/v1/user_groups` responses: - '200': + "200": description: Success. content: application/json: schema: allOf: - - $ref: '#/components/schemas/JsonSuccess' - - properties: - user_groups: - type: array - items: - type: object - additionalProperties: false - properties: - description: - type: string - description: | - The human-readable description of the user group. - id: - type: integer - description: | - The user group's integer id. - members: - type: array - description: | - The integer User IDs of the user group members. - items: + - $ref: "#/components/schemas/JsonSuccess" + - properties: + user_groups: + type: array + items: + type: object + additionalProperties: false + properties: + description: + type: string + description: | + The human-readable description of the user group. + id: type: integer - name: - type: string - description: | - User group name. - description: | - A list of `user_group` objects, which contain a `description`, a `name`, - their `id` and the list of members of the user group. - - example: - { + description: | + The user group's integer id. + members: + type: array + description: | + The integer User IDs of the user group members. + items: + type: integer + name: + type: string + description: | + User group name. + description: | + A list of `user_group` objects, which contain a `description`, a `name`, + their `id` and the list of members of the user group. + - example: + { "msg": "", "result": "success", - "user_groups": [ + "user_groups": + [ { - "description": "Characters of Hamlet", - "id": 1, - "name": "hamletcharacters", - "members": [3, 4] + "description": "Characters of Hamlet", + "id": 1, + "name": "hamletcharacters", + "members": [3, 4], }, { - "description": "Other users", - "id": 2, - "name": "other users", - "members": [1, 2] - } - ] - } + "description": "Other users", + "id": 2, + "name": "other users", + "members": [1, 2], + }, + ], + } /real-time: # This entry is a hack; it exists to give us a place to put the text # documenting the parameters for call_on_each_event and friends. @@ -4357,14 +4259,14 @@ paths: description: | (Ignored) parameters: - - $ref: '#/components/parameters/Narrow' - - $ref: '#/components/parameters/Event_types' + - $ref: "#/components/parameters/Narrow" + - $ref: "#/components/parameters/Event_types" security: - - basicAuth: [] + - basicAuth: [] responses: - # Makeshift response for this hack entry. - '200': - description: Success + # Makeshift response for this hack entry. + "200": + description: Success /rest-error-handling: post: operationId: rest_error_handling @@ -4372,19 +4274,19 @@ paths: description: | Common error to many endpoints responses: - '400': + "400": description: | Bad request. content: application/json: schema: oneOf: - - allOf: - - $ref: '#/components/schemas/InvalidApiKeyError' - - allOf: - - $ref: '#/components/schemas/MissingArgumentError' - - allOf: - - $ref: '#/components/schemas/UserNotAuthorizedError' + - allOf: + - $ref: "#/components/schemas/InvalidApiKeyError" + - allOf: + - $ref: "#/components/schemas/MissingArgumentError" + - allOf: + - $ref: "#/components/schemas/UserNotAuthorizedError" /zulip-outgoing-webhook: post: operationId: zulip_outgoing_webhooks @@ -4393,7 +4295,7 @@ paths: Outgoing Webhooks allows to build or set up Zulip integrations which are notified when certain types of messages are sent in Zulip. responses: - '200': + "200": description: | Success content: @@ -4418,42 +4320,43 @@ paths: in the `zuliprc` file downloaded when creating the bot. message: allOf: - - description: | - A dict containing details on the message that triggered the - outgoing webhook, in the format used by [`GET /messages`](/api/get-messages). - - $ref: '#/components/schemas/Messages' + - description: | + A dict containing details on the message that triggered the + outgoing webhook, in the format used by [`GET /messages`](/api/get-messages). + - $ref: "#/components/schemas/Messages" bot_email: type: string description: | Email of the bot user. example: { - "data": "@**Outgoing Webhook Test** Zulip is the world\u2019s most productive group chat!", - "trigger": "mention", - "token": "xvOzfurIutdRRVLzpXrIIHXJvNfaJLJ0", - "message": { - "subject": "Verona2", - "sender_email": "iago@zulip.com", - "timestamp": 1527876931, - "client": "website", - "submessages": [], - "recipient_id": 20, - "topic_links": [], - "sender_full_name": "Iago", - "avatar_url": "https://secure.gravatar.com/avatar/1f4f1575bf002ae562fea8fc4b861b09?d=identicon&version=1", - "rendered_content": "

@Outgoing Webhook Test Zulip is the world\u2019s most productive group chat!

", - "sender_id": 5, - "stream_id": 5, - "content": "@**Outgoing Webhook Test** Zulip is the world\u2019s most productive group chat!", - "display_recipient": "Verona", - "type": "stream", - "id": 112, - "is_me_message": false, - "reactions": [], - "sender_realm_str": "zulip", - "sender_short_name": "iago" + "data": "@**Outgoing Webhook Test** Zulip is the world\u2019s most productive group chat!", + "trigger": "mention", + "token": "xvOzfurIutdRRVLzpXrIIHXJvNfaJLJ0", + "message": + { + "subject": "Verona2", + "sender_email": "iago@zulip.com", + "timestamp": 1527876931, + "client": "website", + "submessages": [], + "recipient_id": 20, + "topic_links": [], + "sender_full_name": "Iago", + "avatar_url": "https://secure.gravatar.com/avatar/1f4f1575bf002ae562fea8fc4b861b09?d=identicon&version=1", + "rendered_content": "

@Outgoing Webhook Test Zulip is the world\u2019s most productive group chat!

", + "sender_id": 5, + "stream_id": 5, + "content": "@**Outgoing Webhook Test** Zulip is the world\u2019s most productive group chat!", + "display_recipient": "Verona", + "type": "stream", + "id": 112, + "is_me_message": false, + "reactions": [], + "sender_realm_str": "zulip", + "sender_short_name": "iago", }, - "bot_email": "outgoing-bot@localhost" + "bot_email": "outgoing-bot@localhost", } /calls/bigbluebutton/create: @@ -4464,25 +4367,25 @@ paths: Create a video call url for a Big Blue Button video call. Requires Big Blue Button to be configured on the Zulip server. responses: - '200': + "200": description: Success. content: application/json: schema: allOf: - - $ref: '#/components/schemas/JsonSuccess' - - properties: - url: - description: | - The url for the Big Blue Button video call. - type: string - example: "/calls/bbb/join?meeting_id=%22zulip-something%22&password=%22something%22&checksum=%22somechecksum%22" - - example: - { + - $ref: "#/components/schemas/JsonSuccess" + - properties: + url: + description: | + The url for the Big Blue Button video call. + type: string + example: "/calls/bbb/join?meeting_id=%22zulip-something%22&password=%22something%22&checksum=%22somechecksum%22" + - example: + { "msg": "", "result": "success", - "url": "/calls/bbb/join?meeting_id=%22zulip-something%22&password=%22something%22&checksum=%22somechecksum%22" - } + "url": "/calls/bbb/join?meeting_id=%22zulip-something%22&password=%22something%22&checksum=%22somechecksum%22", + } components: ####################### @@ -4531,32 +4434,32 @@ components: whether `apply_markdown` was set. display_recipient: oneOf: - - type: string - - type: array - items: - type: object - additionalProperties: false - properties: - id: - type: integer - description: | - ID of the user. - email: - type: string - description: | - Email of the user. - full_name: - type: string - description: | - Full name of the user. - short_name: - type: string - description: | - Short name of the user. - is_mirror_dummy: - type: boolean - description: | - Whether the user is a mirror dummy. + - type: string + - type: array + items: + type: object + additionalProperties: false + properties: + id: + type: integer + description: | + ID of the user. + email: + type: string + description: | + Email of the user. + full_name: + type: string + description: | + Full name of the user. + short_name: + type: string + description: | + Short name of the user. + is_mirror_dummy: + type: boolean + description: | + Whether the user is a mirror dummy. description: | Data on the recipient of the message; either the name of a stream or a dictionary containing basic data on @@ -4683,9 +4586,9 @@ components: subject: type: string description: | - The `topic` of the message (only present for stream - messages). The field name is a legacy holdover from when topics were - called "subjects" and will eventually change. + The `topic` of the message (only present for stream + messages). The field name is a legacy holdover from when topics were + called "subjects" and will eventually change. topic_links: type: array items: @@ -4749,9 +4652,9 @@ components: If you do not have permission to view the email address of the target user, this will be a fake email address that is usable for the Zulip API but nothing else. is_bot: - type: boolean - description: | - A boolean specifying whether the user is a bot or full account. + type: boolean + description: | + A boolean specifying whether the user is a bot or full account. avatar_url: type: string nullable: true @@ -4831,7 +4734,7 @@ components: limited and you are an administrator with access to real email addresses under the configured policy. profile_data: - $ref: '#/components/schemas/profile_data' + $ref: "#/components/schemas/profile_data" profile_data: type: object description: | @@ -4868,95 +4771,91 @@ components: type: string JsonSuccess: allOf: - - $ref: '#/components/schemas/JsonResponse' - - required: - - result - - msg - - properties: - result: - enum: - - success - msg: - type: string - - example: - { - "msg": "", - "result": "success" - } + - $ref: "#/components/schemas/JsonResponse" + - required: + - result + - msg + - properties: + result: + enum: + - success + msg: + type: string + - example: { "msg": "", "result": "success" } JsonError: allOf: - - $ref: '#/components/schemas/JsonResponse' - - required: - - result - - msg - - properties: - result: - enum: - - error - msg: - type: string + - $ref: "#/components/schemas/JsonResponse" + - required: + - result + - msg + - properties: + result: + enum: + - error + msg: + type: string ApiKeyResponse: allOf: - - $ref: '#/components/schemas/JsonSuccess' - - required: - - api_key - - email - - properties: - api_key: - type: string - description: | - The API key that can be used to authenticate as the requested user. - email: - type: string - description: | - The email address of the user who owns the API key - - example: - { + - $ref: "#/components/schemas/JsonSuccess" + - required: + - api_key + - email + - properties: + api_key: + type: string + description: | + The API key that can be used to authenticate as the requested user. + email: + type: string + description: | + The email address of the user who owns the API key + - example: + { "api_key": "gjA04ZYcqXKalvYMA8OeXSfzUOLrtbZv", "email": "iago@zulip.com", "msg": "", - "result": "success" - } + "result": "success", + } CodedError: allOf: - - $ref: '#/components/schemas/JsonError' - - properties: - code: - type: string - description: | - A string that identifies the error. + - $ref: "#/components/schemas/JsonError" + - properties: + code: + type: string + description: | + A string that identifies the error. BadEventQueueIdError: allOf: - - $ref: '#/components/schemas/CodedError' - - properties: - queue_id: - type: string - description: | - The string that identifies the invalid event queue. - - example: - { + - $ref: "#/components/schemas/CodedError" + - properties: + queue_id: + type: string + description: | + The string that identifies the invalid event queue. + - example: + { "code": "BAD_EVENT_QUEUE_ID", "msg": "Bad event queue id: 1518820930:1", "queue_id": "1518820930:1", - "result": "error" - } + "result": "error", + } InvalidMessageError: allOf: - - $ref: '#/components/schemas/JsonSuccess' - - properties: - raw_content: - type: string - description: | - The raw content of the message. - - example: - { + - $ref: "#/components/schemas/JsonSuccess" + - properties: + raw_content: + type: string + description: | + The raw content of the message. + - example: + { "msg": "Invalid message(s)", "code": "BAD_REQUEST", - "result": "error" - } + "result": "error", + } NonExistingStreamError: allOf: - - $ref: '#/components/schemas/CodedError' + - $ref: "#/components/schemas/CodedError" - properties: stream: type: string @@ -4964,80 +4863,76 @@ components: The name of the stream that could not be found. - example: { - "code": "STREAM_DOES_NOT_EXIST", - "msg": "Stream 'nonexistent_stream' does not exist", - "result": "error", - "stream": "nonexistent_stream" + "code": "STREAM_DOES_NOT_EXIST", + "msg": "Stream 'nonexistent_stream' does not exist", + "result": "error", + "stream": "nonexistent_stream", } AddSubscriptionsResponse: allOf: - - $ref: '#/components/schemas/JsonSuccess' - - properties: - subscribed: - type: object - description: | - A dictionary where the key is the email address of the user/bot and the - value is a list of the names of the streams that were subscribed to as a - result of the query. - additionalProperties: + - $ref: "#/components/schemas/JsonSuccess" + - properties: + subscribed: + type: object description: | - `{email_address}`: List of the names of the streams that were subscribed - to as a result of the query. + A dictionary where the key is the email address of the user/bot and the + value is a list of the names of the streams that were subscribed to as a + result of the query. + additionalProperties: + description: | + `{email_address}`: List of the names of the streams that were subscribed + to as a result of the query. + type: array + items: + type: string + already_subscribed: + type: object + description: | + A dictionary where the key is the email address of the user/bot and the + value is a list of the names of the streams that the user/bot is already + subscribed to. + additionalProperties: + description: | + {email_address}`: List of the names of the streams that the user is + already subscribed to. + type: array + items: + type: string + unauthorized: type: array items: type: string - already_subscribed: - type: object - description: | - A dictionary where the key is the email address of the user/bot and the - value is a list of the names of the streams that the user/bot is already - subscribed to. - additionalProperties: description: | - {email_address}`: List of the names of the streams that the user is - already subscribed to. - type: array - items: - type: string - unauthorized: - type: array - items: - type: string - description: | - A list of names of streams that the requesting user/bot was not - authorized to subscribe to. Only present if `authorization_errors_fatal=false`. + A list of names of streams that the requesting user/bot was not + authorized to subscribe to. Only present if `authorization_errors_fatal=false`. InvalidApiKeyError: allOf: - - $ref: '#/components/schemas/JsonError' - - example: - { - "msg": "Invalid API key", - "result": "error" - } + - $ref: "#/components/schemas/JsonError" + - example: { "msg": "Invalid API key", "result": "error" } MissingArgumentError: allOf: - - $ref: '#/components/schemas/CodedError' - - properties: - var_name: - type: string - description: | - It contains the information about the missing parameter. - - example: - { + - $ref: "#/components/schemas/CodedError" + - properties: + var_name: + type: string + description: | + It contains the information about the missing parameter. + - example: + { "code": "REQUEST_VARIABLE_MISSING", "msg": "Missing 'content' argument", "result": "error", - "var_name": "content" - } + "var_name": "content", + } UserNotAuthorizedError: allOf: - - $ref: '#/components/schemas/CodedError' - - example: - { + - $ref: "#/components/schemas/CodedError" + - example: + { "code": "BAD_REQUEST", "msg": "User not authorized for this query", - "result": "error" - } + "result": "error", + } ################### # Shared responses @@ -5048,7 +4943,7 @@ components: content: application/json: schema: - $ref: '#/components/schemas/JsonSuccess' + $ref: "#/components/schemas/JsonSuccess" #################### # Shared parameters @@ -5077,7 +4972,7 @@ components: type: array items: type: string - example: ['message'] + example: ["message"] required: false Narrow: name: narrow @@ -5098,7 +4993,7 @@ components: items: type: string default: [] - example: [['stream', 'Denmark']] + example: [["stream", "Denmark"]] required: false GroupId: name: group_id @@ -5268,7 +5163,7 @@ components: emoji you want, and note that emoji's text name. schema: type: string - example: 'octopus' + example: "octopus" IncludeCustomProfileFields: name: include_custom_profile_fields in: query @@ -5300,7 +5195,7 @@ components: oneOf: - type: string - type: integer - example: ['ZOE@zulip.com'] + example: ["ZOE@zulip.com"] ReactionType: name: reaction_type in: query @@ -5320,7 +5215,7 @@ components: parameter was not specified. schema: type: string - example: 'unicode_emoji' + example: "unicode_emoji" required: false EmojiCode: name: emoji_code @@ -5342,7 +5237,7 @@ components: rather than a reaction with a "diffenent" emoji. schema: type: string - example: '1f419' + example: "1f419" required: false MessageRetentionDays: name: message_retention_days @@ -5361,5 +5256,5 @@ components: oneOf: - type: string - type: integer - example: '20' + example: "20" required: false