favorites

5 endpoints

GET/rest/favorites

List favorites

Description:

Returns the list of favorites for the current user.

Precondition:

User must be authenticated.

Response:

The list of favorited files and folders is returned.

Parameters

Query Parameters

returnEntity

Optional

boolean

If true, includes the entity in the response body.

with

Optional

string

Specifies additional fields to include in the response.

mode

Optional

string

Determines the detail level of the response body.

parentId

Optional

string

Filter favorites by parent folder ID.

parentId:in

Optional

string[]

Filter favorites by parent folder ID. Search for results that contain any of the specified values.

excludeEc

Optional

boolean

If set to true, excludes Repositories Gateway folders from the results.

orderBy

Optional

string

Sort order for the results. Default is objects.created:asc.
Allowed values: objects.name:asc, objects.name:desc, objects.created:asc, objects.created:desc, objects.modified:asc, objects.modified:desc.

limit

Optional

integer

Range limit.

offset

Optional

integer

Range offset.

Responses

The list of favorites has been successfully returned.

data

FavoriteOpenAPI2[]

List of favorite entries.

integer

Unique identifier of the favorite entry.

userId

string

objectId

string

Unique identifier (UUID) of the favorited object.

object

Details of the favorited object (folder or external content folder).

string

Unique identifier (UUID) of the folder.

parentId

string

Unique identifier (UUID) of the parent object.

name

string

Name of the object.

type

string

Type of the object.
f – File.
d – Folder.

userId

string

Unique identifier (UUID) who created the folder.

creator

object

Details of the user who created the object.

string

Unique identifier (UUID) for the user.

string

Email address associated with the user.

name

string

Full name of the user.

profileIcon

string

URL or identifier for the user's profile icon.

created

string

The date and time when the object was created.

modified

string

The date and time when the object was last modified.

expire

string

Expiration timestamp of the object, if applicable.

permissions

Permission[]

List of permissions associated with the object.

integer

Unique identifier for the permission.

name

string

Name of the permission.

allowed

boolean

Indicates whether the permission is granted (True) or denied (False).

deleted

boolean

Indicates whether the object has been deleted.

permDeleted

boolean

Indicates whether the object has been permanently deleted.

permalink

string

Permanent URL link to access the object.

path

string

Path to the folder in the hierarchy.

members

Member[]

List of members who have access to the object.

objectId

string

Unique identifier (UUID) of the associated object (file or folder).

roleId

integer

Role assigned to the member.

userId

string

Unique identifier (UUID) of the user.

groupId

integer

Unique identifier of the LDAP group.

user

object

User details of the member.

role

object

Role details assigned to the member.

group

object

Group details if the member belongs to a group.

sharedBy

object

Details of the user who shared the file or folder.

created

string

Date when the file or folder was shared.

inheritRoleId

integer

Inherited role ID from the parent folder, if applicable.

allowedFolderRoleId

integer[]

List of allowed folder role IDs.

string

Email associated with the member.

rank

integer

Rank of the member role.

originFolder

any

vendorDocId

string

Vendor document ID associated with the object.

vendorDocName

string

Name of the vendor document associated with the object.

secure

boolean

Indicates whether the folder or the parent folder containing the file is marked as secure.

source

integer

ID representing the source of the object (1 - Salesforce, 2 - Teams).

isShared

boolean

Indicates if the folder is shared with other users.

syncable

boolean

Indicates if the folder can be synced by Desktop Sync Client.

fileLifetime

integer

Time duration (in days) for which the files in this folder are kept after being added to the folder.

description

string

The description of the folder.

parent

object

The parent folder of the current folder.

string

Unique identifier (UUID) of the folder.

parentId

string

Unique identifier (UUID) of the parent object.

name

string

Name of the object.

type

string

Type of the object.
f – File.
d – Folder.

userId

string

Unique identifier (UUID) who created the folder.

creator

object

Details of the user who created the object.

created

string

The date and time when the object was created.

modified

string

The date and time when the object was last modified.

expire

string

Expiration timestamp of the object, if applicable.

permissions

Permission[]

List of permissions associated with the object.

deleted

boolean

Indicates whether the object has been deleted.

permDeleted

boolean

Indicates whether the object has been permanently deleted.

permalink

string

Permanent URL link to access the object.

path

string

Path to the folder in the hierarchy.

members

Member[]

List of members who have access to the object.

vendorDocId

string

Vendor document ID associated with the object.

vendorDocName

string

Name of the vendor document associated with the object.

secure

boolean

Indicates whether the folder or the parent folder containing the file is marked as secure.

source

integer

ID representing the source of the object (1 - Salesforce, 2 - Teams).

isShared

boolean

Indicates if the folder is shared with other users.

syncable

boolean

Indicates if the folder can be synced by Desktop Sync Client.

fileLifetime

integer

Time duration (in days) for which the files in this folder are kept after being added to the folder.

description

string

The description of the folder.

isFavorite

boolean

Indicates if the folder is marked as a favorite by the user.

pushedFilesCount

integer

The number of files that have been pushed to mobile apps in this folder.

currentUserRole

object

The role of the current user in this folder.

avStatus

string

The Antivirus (AV) status of the folder.

dlpStatus

string

The Data Loss Prevention (DLP) status of the folder.

totalMembersCount

integer

Total number of members who have access to this folder.

totalFoldersCount

integer

Total number of subfolders within this folder.

totalFilesCount

integer

Total number of files within this folder.

maxFolderExpiration

string

The maximum expiration date allowed for files in this folder.

maxFileLifetime

integer

The maximum duration (in days) that files in this folder can be kept after being added to the folder.

isLdapGroupMember

boolean

Indicates if the folder is part of an LDAP group.

isUnderMyFolder

boolean

Indicates if this folder is a subfolder of the user's "My Folder".

pathIds

string

A list of IDs representing the path of the folder within the folder hierarchy.

isRoot

boolean

Indicates if this folder is a root folder.

rootId

string

The ID of the root folder if this is a subfolder.

useFolderQuota

boolean

Indicates if a folder quota is applied to this folder.

quota

integer

The storage quota for the folder (in bytes).

size

integer

The total storage size used by the folder (in bytes).

freeSpace

integer

The amount of free space available in the folder (in bytes).

inheritanceEnabled

boolean

Indicates if a folder inherits permissions from the parent folder

isFavorite

boolean

Indicates if the folder is marked as a favorite by the user.

pushedFilesCount

integer

The number of files that have been pushed to mobile apps in this folder.

currentUserRole

object

The role of the current user in this folder.

integer

Role ID

name

string

Role name

rank

integer

Role rank

type

string

Role type

avStatus

string

The Antivirus (AV) status of the folder.

dlpStatus

string

The Data Loss Prevention (DLP) status of the folder.

totalMembersCount

integer

Total number of members who have access to this folder.

totalFoldersCount

integer

Total number of subfolders within this folder.

totalFilesCount

integer

Total number of files within this folder.

maxFolderExpiration

string

The maximum expiration date allowed for files in this folder.

maxFileLifetime

integer

The maximum duration (in days) that files in this folder can be kept after being added to the folder.

isLdapGroupMember

boolean

Indicates if the folder is part of an LDAP group.

isUnderMyFolder

boolean

Indicates if this folder is a subfolder of the user's "My Folder".

pathIds

string

A list of IDs representing the path of the folder within the folder hierarchy.

isRoot

boolean

Indicates if this folder is a root folder.

rootId

string

The ID of the root folder if this is a subfolder.

useFolderQuota

boolean

Indicates if a folder quota is applied to this folder.

quota

integer

The storage quota for the folder (in bytes).

size

integer

The total storage size used by the folder (in bytes).

freeSpace

integer

The amount of free space available in the folder (in bytes).

inheritanceEnabled

boolean

Indicates if a folder inherits permissions from the parent folder

metadata

object

Pagination metadata for the result set.

total

integer

Total number of items available.

limit

integer

Maximum number of items returned per page.

offset

integer

Number of items skipped before the current page.

Unauthorized

Possible error codes: ERR_ACCESS_USER, ERR_AUTH_INVALID_CSRF, ERR_AUTH_UNAUTHORIZED

error

Error[]

code

string

Error code

message

string

Error message

Forbidden

Possible error codes: ERR_ACCESS_DENIED

error

Error[]

code

string

Error code

message

string

Error message

Request blocked by WAF

Empty response body.

Shell

curl -X GET \
  "https://{instance}.kiteworks.com/rest/favorites" \
  -H "Authorization: Bearer YOUR_TOKEN"

Python

import requests

url = "https://{instance}.kiteworks.com/rest/favorites"
headers = {
    "Authorization": "Bearer YOUR_TOKEN",
}
response = requests.get(url, headers=headers)
print(response.json())

Responses

{ "data": [ { "id": 1, "userId": "string", "objectId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "object": {} } ], "metadata": {} }

{ "errors": [ { "code": "ERR_ACCESS_USER", "message": "Insufficient access permissions" } ] }

{ "errors": [ { "code": "ERR_AUTH_INVALID_CSRF", "message": "Invalid CSRF Authentication" } ] }

{ "errors": [ { "code": "ERR_AUTH_UNAUTHORIZED", "message": "Unauthorized" } ] }

{ "errors": [ { "code": "ERR_ACCESS_DENIED", "message": "Your access is denied.", "redirectUrl": "/login?code=3317" } ] }

// Error - No Body

POST/rest/favorites

Add a favorite

Marks the specified folder as a favorite for the current user.

Parameters

Query Parameters

returnEntity

Optional

boolean

If set to true, returns information about the newly created entity.

mode

Optional

string

Determines the detail level of the response body.

Request Body

objectId

Required

integer

Unique identifier of the favorited folder or file

addLinks

boolean

Indicates whether HATEOAS links should be included in the response

Responses

Favorite created successfully.

Required

integer

Unique identifier of Favorite

objectId

Required

string

Unique identifier of the favorited folder or file

userId

Required

string

Unique identifier of the user who created this favorite

creator

UserBasicInfo

User who created this favorite (Explicit field. May be retrieved only if mentioned in "with" parameter)

Required

string

The unique identifier of the user

name

Required

string

The name of the user

Required

string

The user's email

profileIcon

string

URL to the user's profile icon image

object

Folder

Favorited folder object (Explicit field. May be retrieved only if mentioned in "with" parameter)

string

Unique identifier (UUID) of the folder.

parentId

string

Unique identifier (UUID) of the parent object.

name

string

Name of the object.

type

string

Type of the object.
f – File.
d – Folder.

userId

string

Unique identifier (UUID) who created the folder.

creator

object

Details of the user who created the object.

string

Unique identifier (UUID) for the user.

string

Email address associated with the user.

name

string

Full name of the user.

profileIcon

string

URL or identifier for the user's profile icon.

created

string

The date and time when the object was created.

modified

string

The date and time when the object was last modified.

expire

string

Expiration timestamp of the object, if applicable.

permissions

Permission[]

List of permissions associated with the object.

integer

Unique identifier for the permission.

name

string

Name of the permission.

allowed

boolean

Indicates whether the permission is granted (True) or denied (False).

deleted

boolean

Indicates whether the object has been deleted.

permDeleted

boolean

Indicates whether the object has been permanently deleted.

permalink

string

Permanent URL link to access the object.

path

string

Path to the folder in the hierarchy.

members

Member[]

List of members who have access to the object.

objectId

string

Unique identifier (UUID) of the associated object (file or folder).

roleId

integer

Role assigned to the member.

userId

string

Unique identifier (UUID) of the user.

groupId

integer

Unique identifier of the LDAP group.

user

object

User details of the member.

string

Unique identifier (UUID) for the user.

string

Email address associated with the user.

name

string

Full name of the user.

profileIcon

string

URL or identifier for the user's profile icon.

role

object

Role details assigned to the member.

integer

Role ID

name

string

Role name

rank

integer

Role rank

type

string

Role type

group

object

Group details if the member belongs to a group.

integer

LDAP Group ID

name

string

LDAP Group name

string

LDAP Group domain name

string

LDAP Group email

description

string

LDAP Group description

sharedBy

object

Details of the user who shared the file or folder.

string

Unique identifier (UUID) for the user.

string

Email address associated with the user.

name

string

Full name of the user.

profileIcon

string

URL or identifier for the user's profile icon.

created

string

Date when the file or folder was shared.

inheritRoleId

integer

Inherited role ID from the parent folder, if applicable.

allowedFolderRoleId

integer[]

List of allowed folder role IDs.

string

Email associated with the member.

rank

integer

Rank of the member role.

originFolder

any

vendorDocId

string

Vendor document ID associated with the object.

vendorDocName

string

Name of the vendor document associated with the object.

secure

boolean

Indicates whether the folder or the parent folder containing the file is marked as secure.

source

integer

ID representing the source of the object (1 - Salesforce, 2 - Teams).

isShared

boolean

Indicates if the folder is shared with other users.

syncable

boolean

Indicates if the folder can be synced by Desktop Sync Client.

fileLifetime

integer

Time duration (in days) for which the files in this folder are kept after being added to the folder.

description

string

The description of the folder.

isFavorite

boolean

Indicates if the folder is marked as a favorite by the user.

pushedFilesCount

integer

The number of files that have been pushed to mobile apps in this folder.

currentUserRole

object

The role of the current user in this folder.

integer

Role ID

name

string

Role name

rank

integer

Role rank

type

string

Role type

avStatus

string

The Antivirus (AV) status of the folder.

dlpStatus

string

The Data Loss Prevention (DLP) status of the folder.

totalMembersCount

integer

Total number of members who have access to this folder.

totalFoldersCount

integer

Total number of subfolders within this folder.

totalFilesCount

integer

Total number of files within this folder.

maxFolderExpiration

string

The maximum expiration date allowed for files in this folder.

maxFileLifetime

integer

The maximum duration (in days) that files in this folder can be kept after being added to the folder.

isLdapGroupMember

boolean

Indicates if the folder is part of an LDAP group.

isUnderMyFolder

boolean

Indicates if this folder is a subfolder of the user's "My Folder".

pathIds

string

A list of IDs representing the path of the folder within the folder hierarchy.

isRoot

boolean

Indicates if this folder is a root folder.

rootId

string

The ID of the root folder if this is a subfolder.

useFolderQuota

boolean

Indicates if a folder quota is applied to this folder.

quota

integer

The storage quota for the folder (in bytes).

size

integer

The total storage size used by the folder (in bytes).

freeSpace

integer

The amount of free space available in the folder (in bytes).

inheritanceEnabled

boolean

Indicates if a folder inherits permissions from the parent folder

links

string[]

HATEOAS links associated with the entity

Conflict

Possible error codes: ERR_ENTITY_EXISTS

error

Error[]

code

string

Error code

message

string

Error message

Unprocessable Content

Possible error codes: ERR_INPUT_REQUIRED

error

Error[]

code

string

Error code

message

string

Error message

Request blocked by WAF

Empty response body.

Shell

curl -X POST \
  "https://{instance}.kiteworks.com/rest/favorites" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
         "objectId": 1,
         "addLinks": true
       }'

Python

import requests

url = "https://{instance}.kiteworks.com/rest/favorites"
headers = {
    "Authorization": "Bearer YOUR_TOKEN",
    "Content-Type": "application/json",
}
payload = {
  "objectId": 1,
  "addLinks": true
}
response = requests.post(url, headers=headers, json=payload)
print(response.json())

Responses

{ "id": 42, "objectId": "f0e1d2c3-b4a5-6789-0fed-cba987654321", "userId": "u1a2b3c4-d5e6-7890-abcd-ef1234567890" }

{ "errors": { "code": "ERR_ENTITY_EXISTS", "message": "Entity exists" } }

{ "errors": { "code": "ERR_INPUT_REQUIRED", "message": "Field is required" } }

// Error - No Body

DELETE/rest/favorites/{id}

Remove a favorite

Removes the specified favorite from the current user's favorites list.

Parameters

Path Parameters

Required

integer

ID of the favorite to be removed

Responses

Favorite removed successfully.

Empty response body.

Forbidden

Possible error codes: ERR_ACCESS_USER

error

Error[]

code

string

Error code

message

string

Error message

Request blocked by WAF

Empty response body.

Shell

curl -X DELETE \
  "https://{instance}.kiteworks.com/rest/favorites/:id" \
  -H "Authorization: Bearer YOUR_TOKEN"

Python

import requests

id = "VALUE"  # ID of the favorite to be removed

url = f"https://{{instance}}.kiteworks.com/rest/favorites/{id}"
headers = {
    "Authorization": "Bearer YOUR_TOKEN",
}
response = requests.delete(url, headers=headers)
print(response.json())

Responses

// Request successful - No Body

{ "errors": { "code": "ERR_ACCESS_USER", "message": "Insufficient access permissions" } }

// Error - No Body

POST/rest/folders/actions/favorite

Set multiple folders as favorite

Marks multiple folders as favorites for the current user in a single request. Supports partial success, meaning valid items are processed even if some fail.

Parameters

Query Parameters

id:in

Required

string

A comma-separated list of unique identifiers for the entities to be processed.. A comma-separated list of unique identifiers for the entities to be processed.

partialSuccess

Optional

boolean

If set to true, the operation will continue for the valid items even if some items result in failure.

returnEntity

Optional

boolean

If set to true, returns information about the newly created entity.

mode

Optional

string

Determines the detail level of the response body.

Responses

Favorites created successfully.

data

Favorite[]

Required

integer

Unique identifier of Favorite

objectId

Required

string

Unique identifier of the favorited folder or file

userId

Required

string

Unique identifier of the user who created this favorite

creator

UserBasicInfo

User who created this favorite (Explicit field. May be retrieved only if mentioned in "with" parameter)

Required

string

The unique identifier of the user

name

Required

string

The name of the user

Required

string

The user's email

profileIcon

string

URL to the user's profile icon image

object

Folder

Favorited folder object (Explicit field. May be retrieved only if mentioned in "with" parameter)

string

Unique identifier (UUID) of the folder.

parentId

string

Unique identifier (UUID) of the parent object.

name

string

Name of the object.

type

string

Type of the object.
f – File.
d – Folder.

userId

string

Unique identifier (UUID) who created the folder.

creator

object

Details of the user who created the object.

string

Unique identifier (UUID) for the user.

string

Email address associated with the user.

name

string

Full name of the user.

profileIcon

string

URL or identifier for the user's profile icon.

created

string

The date and time when the object was created.

modified

string

The date and time when the object was last modified.

expire

string

Expiration timestamp of the object, if applicable.

permissions

Permission[]

List of permissions associated with the object.

integer

Unique identifier for the permission.

name

string

Name of the permission.

allowed

boolean

Indicates whether the permission is granted (True) or denied (False).

deleted

boolean

Indicates whether the object has been deleted.

permDeleted

boolean

Indicates whether the object has been permanently deleted.

permalink

string

Permanent URL link to access the object.

path

string

Path to the folder in the hierarchy.

members

Member[]

List of members who have access to the object.

objectId

string

Unique identifier (UUID) of the associated object (file or folder).

roleId

integer

Role assigned to the member.

userId

string

Unique identifier (UUID) of the user.

groupId

integer

Unique identifier of the LDAP group.

user

object

User details of the member.

role

object

Role details assigned to the member.

group

object

Group details if the member belongs to a group.

sharedBy

object

Details of the user who shared the file or folder.

created

string

Date when the file or folder was shared.

inheritRoleId

integer

Inherited role ID from the parent folder, if applicable.

allowedFolderRoleId

integer[]

List of allowed folder role IDs.

string

Email associated with the member.

rank

integer

Rank of the member role.

originFolder

any

vendorDocId

string

Vendor document ID associated with the object.

vendorDocName

string

Name of the vendor document associated with the object.

secure

boolean

Indicates whether the folder or the parent folder containing the file is marked as secure.

source

integer

ID representing the source of the object (1 - Salesforce, 2 - Teams).

isShared

boolean

Indicates if the folder is shared with other users.

syncable

boolean

Indicates if the folder can be synced by Desktop Sync Client.

fileLifetime

integer

Time duration (in days) for which the files in this folder are kept after being added to the folder.

description

string

The description of the folder.

isFavorite

boolean

Indicates if the folder is marked as a favorite by the user.

pushedFilesCount

integer

The number of files that have been pushed to mobile apps in this folder.

currentUserRole

object

The role of the current user in this folder.

integer

Role ID

name

string

Role name

rank

integer

Role rank

type

string

Role type

avStatus

string

The Antivirus (AV) status of the folder.

dlpStatus

string

The Data Loss Prevention (DLP) status of the folder.

totalMembersCount

integer

Total number of members who have access to this folder.

totalFoldersCount

integer

Total number of subfolders within this folder.

totalFilesCount

integer

Total number of files within this folder.

maxFolderExpiration

string

The maximum expiration date allowed for files in this folder.

maxFileLifetime

integer

The maximum duration (in days) that files in this folder can be kept after being added to the folder.

isLdapGroupMember

boolean

Indicates if the folder is part of an LDAP group.

isUnderMyFolder

boolean

Indicates if this folder is a subfolder of the user's "My Folder".

pathIds

string

A list of IDs representing the path of the folder within the folder hierarchy.

isRoot

boolean

Indicates if this folder is a root folder.

rootId

string

The ID of the root folder if this is a subfolder.

useFolderQuota

boolean

Indicates if a folder quota is applied to this folder.

quota

integer

The storage quota for the folder (in bytes).

size

integer

The total storage size used by the folder (in bytes).

freeSpace

integer

The amount of free space available in the folder (in bytes).

inheritanceEnabled

boolean

Indicates if a folder inherits permissions from the parent folder

links

string[]

HATEOAS links associated with the entity

metadata

MetaData

total

integer

Total number of items available.

limit

integer

Maximum number of items returned per page.

offset

integer

Number of items skipped before the current page.

Conflict

Possible error codes: ERR_ENTITY_EXISTS

error

Error[]

code

string

Error code

message

string

Error message

Request blocked by WAF

Empty response body.

Shell

curl -X POST \
  "https://{instance}.kiteworks.com/rest/folders/actions/favorite?id:in=VALUE" \
  -H "Authorization: Bearer YOUR_TOKEN"

Python

import requests

url = "https://{instance}.kiteworks.com/rest/folders/actions/favorite"
headers = {
    "Authorization": "Bearer YOUR_TOKEN",
}
params = {
    "id:in": "VALUE",
}
response = requests.post(url, params=params, headers=headers)
print(response.json())

Responses

{ "data": [ { "id": 42, "objectId": "f0e1d2c3-b4a5-6789-0fed-cba987654321", "userId": "u1a2b3c4-d5e6-7890-abcd-ef1234567890" }, { "id": 43, "objectId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "userId": "u1a2b3c4-d5e6-7890-abcd-ef1234567890" } ] }

{ "errors": { "code": "ERR_ENTITY_EXISTS", "message": "Entity exists" } }

// Error - No Body

DELETE/rest/folders/actions/favorite

Removes specified folders from favorites

Removes multiple folders from the current user's favorites list in a single request. Supports partial success, meaning valid items are processed even if some fail.

Parameters

Query Parameters

id:in

Required

string

A comma-separated list of unique identifiers for the entities to be processed.. A comma-separated list of unique identifiers for the entities to be processed.

partialSuccess

Optional

boolean

If set to true, the operation will continue for the valid items even if some items result in failure.

mode

Optional

string

Determines the detail level of the response body.

Responses

Favorites removed successfully.

Empty response body.

Forbidden

Possible error codes: ERR_ACCESS_USER

error

Error[]

code

string

Error code

message

string

Error message

Request blocked by WAF

Empty response body.

Shell

curl -X DELETE \
  "https://{instance}.kiteworks.com/rest/folders/actions/favorite?id:in=VALUE" \
  -H "Authorization: Bearer YOUR_TOKEN"

Python

import requests

url = "https://{instance}.kiteworks.com/rest/folders/actions/favorite"
headers = {
    "Authorization": "Bearer YOUR_TOKEN",
}
params = {
    "id:in": "VALUE",
}
response = requests.delete(url, params=params, headers=headers)
print(response.json())

Responses

// Request successful - No Body

{ "errors": { "code": "ERR_ACCESS_USER", "message": "Insufficient access permissions" } }

// Error - No Body

PreviousexternalDL

Nextfiles