1Update User Preferences

Overview

This API updates User preferences using the details provided.

Method: PUT

Request URL: {kyvos-url}/rest/v2/users/preferences

Authorization

API Key: `sessionid`

This method authenticates requests using a session ID which acts like an API key.

BasicAuth: HTTP Authorization Scheme

This method authenticates requests using a username and password sent in the HTTP Authorization header.

Headers

Header Name	Type	Description	Possible Values

Header Name

Type

Description

Possible Values

Content-Type (Required)

String

Specifies the media type of the request body.

application/x-www-form-urlencoded

sessionid

String

The session ID is the token received from the login API.

Note: Session ID is required for token-based authentication.

–

Request Body

Parameter Name	Type	Description	Possible Values

Parameter Name	Type	Description	Possible Values
userName	String	Name of the user whose preferences need to be updated. Note: At least one of the following parameters must be provided: userId, userName, or groupName.	–
userId	String	ID of the user whose preferences need to be updated.	–
preferences (Required)	String	JSON string containing details of User preferences. Note: An example JSON is provided under the Resources section below.	–
groupName	String	Group name to update the preferences of all users belonging to that group.	–
updateType	String	Applicable only when updating user preferences by groupName. The default value is COMPLETE.	–

Responses

200 Success

{
  "code": 0,
  "message": "Successfully updated user preferences: Admin"
}

Status Code	Description

Status Code	Description
401	Authorization information is missing or invalid.
404	Connection, database, schema, or table not found.
412	Precondition failed. Required parameter missing.
500	Internal Server Error

Resources

Below is an example of JSON structure which can be used as a reference for the preferences parameter in the request body.

{
    "preferences":{
        "navigation":"temporary",
        "sortEntityListBy":"",
        "scaleInterface":true,
        "landingPage":{
            "workbookName":"",
            "itemType":"",
            "usecase":"",
            "workBookId":"",
            "name":"",
            "id":"",
            "folderName":"",
            "type":"",
            "catObj":""
        },
        "theme":"softGray",
        "workbookTabPosition":"top",
        "languageKey":"en_US"
    },
    "homePageConfig":{
        "widgets":[
            {
                "visible":true,
                "sortOrder":"DESC",
                "viewType":"LIST",
                "sortBy":"TIME",
                "id":"home_wgt_recent"
            },
            {
                "visible":true,
                "visitedStepsId":[
                    
                ],
                "id":"home_wgt_documentation"
            }
        ]
    },
    "userDetails":{
        
    }
}

JSON Fields Description:

Field	Type	Description	Possible Values	Example

Field	Type	Description	Possible Values	Example
`preferences`	Object	UI-level preferences for the user.	—	See nested fields below
`preferences.navigation`	String	Navigation panel behavior.	`"temporary"`, `"permanent"`	`"temporary"`
`preferences.sortEntityListBy`	String	Default sort field for entity lists.	Any valid sort field name or `""`	`""`
`preferences.scaleInterface`	Boolean	Whether to scale the interface for smaller screens.	`true`, `false`	`true`
`preferences.theme`	String	UI color theme.	`"softGray"`, `"dark"`, `"light"`	`"softGray"`
`preferences.workbookTabPosition`	String	Position of workbook tabs in the UI.	`"top"`, `"bottom"`	`"top"`
`preferences.languageKey`	String	Locale/language setting for the UI.	Any valid locale key	`"en_US"`, `"fr_FR"`
`preferences.landingPage`	Object	Landing page configuration shown after login.	—	See nested fields below
`preferences.landingPage.name`	String	Name of the landing page entity.	Any string or `""`	`""`
`preferences.landingPage.id`	String	ID of the landing page entity.	Any string or `""`	`""`
`preferences.landingPage.type`	String	Type of the landing page entity.	Any valid entity type or `""`	`""`
`preferences.landingPage.itemType`	String	Item type for the landing page.	Any string or `""`	`""`
`preferences.landingPage.workbookName`	String	Workbook name to open as landing page.	Any workbook name or `""`	`""`
`preferences.landingPage.workBookId`	String	Workbook ID to open as landing page.	Any workbook ID or `""`	`""`
`preferences.landingPage.folderName`	String	Folder containing the landing page entity.	Any folder name or `""`	`""`
`preferences.landingPage.usecase`	String	Use case context for the landing page.	Any string or `""`	`""`
`preferences.landingPage.catObj`	String	Category object for the landing page.	Any string or `""`	`""`
`homePageConfig`	Object	Home page widget layout configuration.	—	See nested fields below
`homePageConfig.widgets`	Array	Ordered list of widget configurations displayed on the home page.	Array of widget objects	See widget fields below
`homePageConfig.widgets[].id`	String	Unique identifier of the widget.	`"home_wgt_recent"`, `"home_wgt_documentation"`, and other valid widget IDs	`"home_wgt_recent"`
`homePageConfig.widgets[].visible`	Boolean	Whether the widget is visible on the home page.	`true`, `false`	`true`
`homePageConfig.widgets[].sortOrder`	String	Sort direction for widget content. Applicable to list-type widgets.	`"ASC"`, `"DESC"`	`"DESC"`
`homePageConfig.widgets[].viewType`	String	Display format of the widget.	`"LIST"`, `"GRID"`	`"LIST"`
`homePageConfig.widgets[].sortBy`	String	Field to sort widget content by.	`"TIME"`, `"NAME"`	`"TIME"`
`homePageConfig.widgets[].visitedStepsId`	Array	Tracks visited documentation steps. Used by the documentation widget.	Array of step ID strings	`[]`
`userDetails`	Object	Additional user detail configuration. Passed as-is to the backend.	Any object or `{}`	`{}`