openapi: 3.0.1
info:
  version: 1.0.0
  title: Zulip REST authentication navigation_views API
  description: 'Powerful open source group chat

    '
  contact:
    url: https://zulip.com
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0.html
servers:
- url: https://{subdomain}.zulipchat.com/api/v1
  variables:
    subdomain:
      default: example
- url: '{server}/api/v1'
  variables:
    server:
      default: https://
- url: https://chat.zulip.org/api/v1
- url: http://localhost:9991/api/v1
- url: http://{subdomain}.testserver/json
security:
- basicAuth: []
tags:
- name: navigation_views
paths:
  /navigation_views:
    get:
      operationId: get-navigation-views
      tags:
      - navigation_views
      summary: Get all navigation views
      description: 'Fetch all configured custom navigation views for the current user.


        **Changes**: New in Zulip 11.0 (feature level 390).

        '
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/JsonSuccessBase'
                - additionalProperties: false
                  properties:
                    result: {}
                    msg: {}
                    navigation_views:
                      type: array
                      description: 'An array of dictionaries containing the user''s navigation views.

                        '
                      items:
                        $ref: '#/components/schemas/NavigationView'
                  example:
                    result: success
                    msg: ''
                    navigation_views:
                    - fragment: narrow/is/alerted
                      is_pinned: false
                      name: Alert Words
    post:
      operationId: add-navigation-view
      tags:
      - navigation_views
      summary: Add a navigation view
      description: 'Adds a new custom left sidebar navigation view configuration

        for the current user.


        This can be used both to configure built-in navigation views,

        or to add new navigation views.


        **Changes**: New in Zulip 11.0 (feature level 390).

        '
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/NavigationView'
      responses:
        '200':
          description: Request succeeded.
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/JsonSuccessBase'
                - type: object
                  additionalProperties: false
                  properties:
                    result: {}
                    msg: {}
                  example:
                    result: success
                    msg: ''
        '400':
          description: Bad request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CodedError'
              examples:
                invalid_parameters:
                  value:
                    code: BAD_REQUEST
                    msg: fragment cannot be blank
                    result: error
  /navigation_views/{fragment}:
    patch:
      operationId: edit-navigation-view
      tags:
      - navigation_views
      summary: Update the navigation view
      description: 'Update the details of an existing configured navigation view,

        such as its name or whether it''s pinned.


        **Changes**: New in Zulip 11.0 (feature level 390).

        '
      parameters:
      - name: fragment
        in: path
        required: true
        schema:
          type: string
        description: 'The unique URL hash of the navigation view to be updated.


          This also serves as the identifier for the navigation view.

          '
        example: narrow/is/alerted
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                is_pinned:
                  type: boolean
                  description: 'Determines whether the view is pinned (true) or hidden in

                    the menu (false).

                    '
                  example: true
                name:
                  type: string
                  description: 'The user-facing name for custom navigation views. Omit this

                    field for built-in views.

                    '
                  example: Watched Phrases
              anyOf:
              - required:
                - is_pinned
              - required:
                - name
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/JsonSuccessBase'
                - additionalProperties: false
                  properties:
                    result: {}
                    msg: {}
                  example:
                    result: success
                    msg: ''
        '400':
          description: Bad request.
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/CodedError'
                - example:
                    code: BAD_REQUEST
                    msg: Built-in views cannot have a custom name
                    result: error
                description: 'A typical failed JSON response for invalid parameters.

                  '
        '404':
          description: Not Found.
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/CodedError'
                - description: 'A typical failed JSON response when no navigation view

                    exists with the provided fragment:

                    '
                  example:
                    code: NOT_FOUND
                    result: error
                    msg: Navigation view does not exist.
    delete:
      operationId: remove-navigation-view
      tags:
      - navigation_views
      summary: Remove a navigation view
      description: 'Remove a navigation view.


        **Changes**: New in Zulip 11.0 (feature level 390).

        '
      parameters:
      - name: fragment
        in: path
        schema:
          type: string
        description: 'The unique URL hash of the navigation view to be removed.


          This also serves as the identifier for the navigation view.

          '
        example: narrow/is/alerted
        required: true
      responses:
        '200':
          $ref: '#/components/responses/SimpleSuccess'
        '404':
          description: Not Found.
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/CodedError'
                - description: 'A typical failed JSON response for when no navigation

                    view exists with the provided fragment:

                    '
                  example:
                    code: BAD_REQUEST
                    result: error
                    msg: Navigation view does not exist.
components:
  schemas:
    JsonSuccessBase:
      description: '**Changes**: As of Zulip 7.0 (feature level 167), if any

        parameters sent in the request are not supported by this

        endpoint, a successful JSON response will include an

        [`ignored_parameters_unsupported`][ignored_params] array.


        A typical successful JSON response may look like:


        [ignored_params]: /api/rest-error-handling#ignored-parameters

        '
      allOf:
      - $ref: '#/components/schemas/JsonResponseBase'
      - required:
        - result
        - msg
        properties:
          result:
            enum:
            - success
          msg:
            type: string
          ignored_parameters_unsupported:
            $ref: '#/components/schemas/IgnoredParametersUnsupported'
    JsonSuccess:
      allOf:
      - $ref: '#/components/schemas/JsonSuccessBase'
      - additionalProperties: false
        properties:
          result: {}
          msg: {}
          ignored_parameters_unsupported: {}
        example:
          msg: ''
          result: success
    IgnoredParametersUnsupported:
      type: array
      items:
        type: string
      description: 'An array of any parameters sent in the request that are not

        supported by the endpoint.


        See [error handling](/api/rest-error-handling#ignored-parameters) documentation

        for details on this and its change history.

        '
    JsonResponseBase:
      type: object
      properties:
        result:
          type: string
    NavigationView:
      type: object
      description: 'Represents a user''s personal configuration for a specific

        navigation view (displayed most visibly at the top of the web

        application''s left sidebar).


        Navigation views can be either an override to the default

        behavior of a built-in view, or a custom view.


        **Changes**: New in Zulip 11.0 (feature level 390).

        '
      additionalProperties: false
      required:
      - fragment
      - is_pinned
      properties:
        fragment:
          type: string
          description: 'A unique identifier for the view, used to determine navigation

            behavior when clicked.


            Clients should use this value to navigate to the corresponding URL hash.

            '
          example: narrow/is/alerted
        is_pinned:
          type: boolean
          description: 'Determines whether the view appears directly in the sidebar or

            is hidden in the "More Views" menu.


            - `true` - Pinned and visible in the sidebar.

            - `false` - Hidden and accessible via the "More Views" menu.

            '
          example: true
        name:
          type: string
          nullable: true
          description: 'The user-facing name for custom navigation views. Omit this

            field for built-in views.

            '
          example: Alert Words
    CodedError:
      allOf:
      - $ref: '#/components/schemas/CodedErrorBase'
      - additionalProperties: false
        properties:
          result: {}
          msg: {}
          code: {}
    CodedErrorBase:
      allOf:
      - $ref: '#/components/schemas/JsonResponseBase'
      - required:
        - result
        - msg
        - code
        properties:
          result:
            enum:
            - error
          msg:
            type: string
          code:
            type: string
            description: 'A string that identifies the error.

              '
  responses:
    SimpleSuccess:
      description: Success.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/JsonSuccess'
  securitySchemes:
    BasicAuth:
      type: http
      scheme: basic
      description: 'Basic authentication, with the user''s email as the username, and the API

        key as the password. The API key can be fetched using the

        `/fetch_api_key` or `/dev_fetch_api_key` endpoints.

        '