Zulip navigation_views API
The navigation_views API from Zulip — 2 operation(s) for navigation_views.
OpenAPI Specification
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.
'