Kiteworks favorites API

openapi: 3.2.0
info:
  version: '28'
  title: Kiteworks API Documentation Favorites API
tags:
- name: favorites
paths:
  /rest/favorites:
    post:
      tags:
      - favorites
      summary: Add a favorite
      description: Marks the specified folder as a favorite for the current user.
      responses:
        '200':
          description: Favorite created successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Favorite'
              examples:
                FavoriteCreated:
                  summary: A newly created favorite
                  value:
                    id: 42
                    objectId: f0e1d2c3-b4a5-6789-0fed-cba987654321
                    userId: u1a2b3c4-d5e6-7890-abcd-ef1234567890
        '409':
          description: 'Conflict<br /><br /><i>Possible error codes: </i>ERR_ENTITY_EXISTS'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
              examples:
                ERR_ENTITY_EXISTS:
                  summary: Entity exists
                  description: Entity exists
                  value:
                    errors:
                      code: ERR_ENTITY_EXISTS
                      message: Entity exists
        '422':
          description: 'Unprocessable Content<br /><br /><i>Possible error codes: </i>ERR_INPUT_REQUIRED'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
              examples:
                ERR_INPUT_REQUIRED:
                  summary: Field is required
                  description: Field is required
                  value:
                    errors:
                      code: ERR_INPUT_REQUIRED
                      message: Field is required
        '490':
          description: Request blocked by WAF
      deprecated: false
      parameters:
      - in: query
        name: returnEntity
        description: If set to `true`, returns information about the newly created entity.
        schema:
          type: boolean
      - in: query
        name: mode
        description: Determines the detail level of the response body.
        schema:
          type: string
          enum:
          - full_with_links
          - full
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Favorite.Post'
    get:
      summary: List favorites
      description: "### Description:\n  Returns the list of favorites for the current user.\n### Precondition:\n  User must be authenticated.\n### Response:\n  The list of favorited files and folders is returned.\n"
      tags:
      - favorites
      parameters:
      - in: query
        name: returnEntity
        required: false
        description: If true, includes the entity in the response body.
        schema:
          type: boolean
      - in: query
        name: with
        required: false
        description: Specifies additional fields to include in the response.
        schema:
          type: string
      - in: query
        name: mode
        required: false
        description: Determines the detail level of the response body.
        schema:
          type: string
          enum:
          - compact
          - full_no_links
          - full_with_links
          - full
      - in: query
        name: parentId
        required: false
        description: Filter favorites by parent folder ID.
        schema:
          type: string
      - in: query
        name: parentId:in
        required: false
        explode: true
        style: form
        description: Filter favorites by parent folder ID. Search for results that contain any of the specified values.
        schema:
          type: array
          items:
            type: string
      - in: query
        name: excludeEc
        required: false
        description: If set to `true`, excludes Repositories Gateway folders from the results.
        schema:
          type: boolean
      - in: query
        name: orderBy
        required: false
        description: 'Sort order for the results. Default is `objects.created:asc`.<br>Allowed values: `objects.name:asc`, `objects.name:desc`, `objects.created:asc`, `objects.created:desc`, `objects.modified:asc`, `objects.modified:desc`.'
        schema:
          type: string
          enum:
          - objects.name:asc
          - objects.name:desc
          - objects.created:asc
          - objects.created:desc
          - objects.modified:asc
          - objects.modified:desc
      - in: query
        name: limit
        required: false
        description: Range limit.
        schema:
          type: integer
          minimum: 1
      - in: query
        name: offset
        required: false
        description: Range offset.
        schema:
          type: integer
          minimum: 0
      responses:
        '200':
          description: The list of favorites has been successfully returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FavoriteListOpenAPI2'
        '401':
          description: 'Unauthorized<br /><br /><i>Possible error codes: </i>ERR_ACCESS_USER, ERR_AUTH_INVALID_CSRF, ERR_AUTH_UNAUTHORIZED'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
              examples:
                ERR_ACCESS_USER:
                  summary: Insufficient access permissions
                  description: Insufficient access permissions
                  value:
                    errors:
                    - code: ERR_ACCESS_USER
                      message: Insufficient access permissions
                ERR_AUTH_INVALID_CSRF:
                  summary: Invalid CSRF Authentication
                  description: Invalid CSRF Authentication
                  value:
                    errors:
                    - code: ERR_AUTH_INVALID_CSRF
                      message: Invalid CSRF Authentication
                ERR_AUTH_UNAUTHORIZED:
                  summary: Unauthorized
                  description: Unauthorized
                  value:
                    errors:
                    - code: ERR_AUTH_UNAUTHORIZED
                      message: Unauthorized
        '403':
          description: 'Forbidden<br /><br /><i>Possible error codes: </i>ERR_ACCESS_DENIED'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
              examples:
                ERR_ACCESS_DENIED:
                  summary: Your access is denied.
                  description: Your access is denied.
                  value:
                    errors:
                    - code: ERR_ACCESS_DENIED
                      message: Your access is denied.
                      redirectUrl: /login?code=3317
        '490':
          description: Request blocked by WAF
  /rest/favorites/{id}:
    delete:
      tags:
      - favorites
      summary: Remove a favorite
      description: Removes the specified favorite from the current user's favorites list.
      responses:
        '204':
          description: Favorite removed successfully.
        '403':
          description: 'Forbidden<br /><br /><i>Possible error codes: </i>ERR_ACCESS_USER'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
              examples:
                ERR_ACCESS_USER:
                  summary: Insufficient access permissions
                  description: Insufficient access permissions
                  value:
                    errors:
                      code: ERR_ACCESS_USER
                      message: Insufficient access permissions
        '490':
          description: Request blocked by WAF
      deprecated: false
      parameters:
      - in: path
        name: id
        description: ID of the favorite to be removed
        required: true
        schema:
          type: integer
  /rest/folders/actions/favorite:
    post:
      tags:
      - favorites
      summary: Set multiple folders as favorite
      description: 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.
      responses:
        '200':
          description: Favorites created successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Favorite'
                  metadata:
                    $ref: '#/components/schemas/MetaData'
              examples:
                BulkFavoriteCreated:
                  summary: Newly created favorites for multiple folders
                  value:
                    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
        '409':
          description: 'Conflict<br /><br /><i>Possible error codes: </i>ERR_ENTITY_EXISTS'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
              examples:
                ERR_ENTITY_EXISTS:
                  summary: Entity exists
                  description: Entity exists
                  value:
                    errors:
                      code: ERR_ENTITY_EXISTS
                      message: Entity exists
        '490':
          description: Request blocked by WAF
      deprecated: false
      parameters:
      - in: query
        name: id:in
        description: 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.
        required: true
        schema:
          type: string
      - in: query
        name: partialSuccess
        description: If set to `true`, the operation will continue for the valid items even if some items result in failure.
        schema:
          type: boolean
      - in: query
        name: returnEntity
        description: If set to `true`, returns information about the newly created entity.
        schema:
          type: boolean
      - in: query
        name: mode
        description: Determines the detail level of the response body.
        schema:
          type: string
          enum:
          - full_with_links
          - full
    delete:
      tags:
      - favorites
      summary: Removes specified folders from favorites
      description: 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.
      responses:
        '204':
          description: Favorites removed successfully.
        '403':
          description: 'Forbidden<br /><br /><i>Possible error codes: </i>ERR_ACCESS_USER'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
              examples:
                ERR_ACCESS_USER:
                  summary: Insufficient access permissions
                  description: Insufficient access permissions
                  value:
                    errors:
                      code: ERR_ACCESS_USER
                      message: Insufficient access permissions
        '490':
          description: Request blocked by WAF
      deprecated: false
      parameters:
      - in: query
        name: id:in
        description: 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.
        required: true
        schema:
          type: string
      - in: query
        name: partialSuccess
        description: If set to `true`, the operation will continue for the valid items even if some items result in failure.
        schema:
          type: boolean
      - in: query
        name: mode
        description: Determines the detail level of the response body.
        schema:
          type: string
          enum:
          - full_with_links
          - full
components:
  schemas:
    UserBasicInfo:
      required:
      - email
      - id
      - name
      properties:
        id:
          description: The unique identifier of the user
          type: string
        name:
          description: The name of the user
          type: string
        email:
          description: The user's email
          type: string
        profileIcon:
          description: URL to the user's profile icon image
          type: string
    Folder:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Unique identifier (UUID) of the folder.
        parentId:
          type: string
          format: uuid
          description: Unique identifier (UUID) of the parent object.
        name:
          type: string
          description: Name of the object.
        type:
          type: string
          description: Type of the object.<br>`f` – File.<br>`d` – Folder.
        userId:
          type: string
          format: uuid
          description: Unique identifier (UUID) who created the folder.
        creator:
          description: Details of the user who created the object.
          allOf:
          - $ref: '#/components/schemas/UserBasic'
        created:
          type: string
          format: date
          description: The date and time when the object was created.
        modified:
          type: string
          format: date
          description: The date and time when the object was last modified.
        expire:
          type: string
          format: date
          description: Expiration timestamp of the object, if applicable.
        permissions:
          description: List of permissions associated with the object.
          type: array
          items:
            $ref: '#/components/schemas/Permission'
        deleted:
          type: boolean
          description: Indicates whether the object has been deleted.
        permDeleted:
          type: boolean
          description: Indicates whether the object has been permanently deleted.
        permalink:
          type: string
          description: Permanent URL link to access the object.
        path:
          type: string
          description: Path to the folder in the hierarchy.
        members:
          description: List of members who have access to the object.
          type: array
          items:
            $ref: '#/components/schemas/Member'
        vendorDocId:
          type: string
          description: Vendor document ID associated with the object.
        vendorDocName:
          type: string
          description: Name of the vendor document associated with the object.
        secure:
          type: boolean
          description: Indicates whether the folder or the parent folder containing the file is marked as secure.
        source:
          type: integer
          description: ID representing the source of the object (1 - Salesforce, 2 - Teams).
        isShared:
          type: boolean
          description: Indicates if the folder is shared with other users.
        syncable:
          type: boolean
          description: Indicates if the folder can be synced by Desktop Sync Client.
        fileLifetime:
          type: integer
          description: Time duration (in days) for which the files in this folder are kept after being added to the folder.
        description:
          type: string
          description: The description of the folder.
        isFavorite:
          type: boolean
          description: Indicates if the folder is marked as a favorite by the user.
        pushedFilesCount:
          type: integer
          description: The number of files that have been pushed to mobile apps in this folder.
        currentUserRole:
          description: The role of the current user in this folder.
          allOf:
          - $ref: '#/components/schemas/Role'
        avStatus:
          type: string
          description: The Antivirus (AV) status of the folder.
        dlpStatus:
          type: string
          description: The Data Loss Prevention (DLP) status of the folder.
        totalMembersCount:
          type: integer
          description: Total number of members who have access to this folder.
        totalFoldersCount:
          type: integer
          description: Total number of subfolders within this folder.
        totalFilesCount:
          type: integer
          description: Total number of files within this folder.
        maxFolderExpiration:
          type: string
          format: date
          description: The maximum expiration date allowed for files in this folder.
        maxFileLifetime:
          type: integer
          description: The maximum duration (in days) that files in this folder can be kept after being added to the folder.
        isLdapGroupMember:
          type: boolean
          description: Indicates if the folder is part of an LDAP group.
        isUnderMyFolder:
          type: boolean
          description: Indicates if this folder is a subfolder of the user's "My Folder".
        pathIds:
          type: string
          description: A list of IDs representing the path of the folder within the folder hierarchy.
        isRoot:
          type: boolean
          description: Indicates if this folder is a root folder.
        rootId:
          type: string
          format: uuid
          description: The ID of the root folder if this is a subfolder.
        useFolderQuota:
          type: boolean
          description: Indicates if a folder quota is applied to this folder.
        quota:
          type: integer
          description: The storage quota for the folder (in bytes).
        size:
          type: integer
          description: The total storage size used by the folder (in bytes).
        freeSpace:
          type: integer
          description: The amount of free space available in the folder (in bytes).
        inheritanceEnabled:
          type: boolean
          description: Indicates if a folder inherits permissions from the parent folder
    Favorite:
      description: Class Favorite
      required:
      - id
      - objectId
      - userId
      properties:
        id:
          description: Unique identifier of Favorite
          type: integer
        objectId:
          description: Unique identifier of the favorited folder or file
          type: string
        userId:
          description: Unique identifier of the user who created this favorite
          type: string
        creator:
          description: User who created this favorite (Explicit field. May be retrieved only if mentioned in "with" parameter)
          $ref: '#/components/schemas/UserBasicInfo'
        object:
          description: Favorited folder object (Explicit field. May be retrieved only if mentioned in "with" parameter)
          $ref: '#/components/schemas/Folder'
        links:
          description: HATEOAS links associated with the entity
          type: array
          items:
            type: string
    Member:
      type: object
      properties:
        objectId:
          type: string
          description: Unique identifier (UUID) of the associated object (file or folder).
        roleId:
          type: integer
          description: Role assigned to the member.
        userId:
          type: string
          description: Unique identifier (UUID) of the user.
        groupId:
          type: integer
          description: Unique identifier of the LDAP group.
        user:
          description: User details of the member.
          allOf:
          - $ref: '#/components/schemas/UserBasic'
        role:
          description: Role details assigned to the member.
          allOf:
          - $ref: '#/components/schemas/Role'
        group:
          description: Group details if the member belongs to a group.
          allOf:
          - $ref: '#/components/schemas/Group'
        sharedBy:
          description: Details of the user who shared the file or folder.
          allOf:
          - $ref: '#/components/schemas/UserBasic'
        created:
          type: string
          format: date
          description: Date when the file or folder was shared.
        inheritRoleId:
          type: integer
          description: Inherited role ID from the parent folder, if applicable.
        allowedFolderRoleId:
          type: array
          description: List of allowed folder role IDs.
          items:
            type: integer
        email:
          type: string
          description: Email associated with the member.
        rank:
          type: integer
          description: Rank of the member role.
        originFolder:
          readOnly: true
    Group:
      type: object
      properties:
        id:
          type: integer
          description: LDAP Group ID
        name:
          type: string
          description: LDAP Group name
        dn:
          type: string
          description: LDAP Group domain name
        email:
          type: string
          description: LDAP Group email
        description:
          type: string
          description: LDAP Group description
    Favorite.Post:
      description: Class Favorite
      required:
      - objectId
      properties:
        objectId:
          description: Unique identifier of the favorited folder or file
          type: integer
        addLinks:
          description: Indicates whether HATEOAS links should be included in the response
          type: boolean
    FavoriteOpenAPI2:
      type: object
      properties:
        id:
          type: integer
          description: Unique identifier of the favorite entry.
        userId:
          type: string
        objectId:
          type: string
          format: uuid
          description: Unique identifier (UUID) of the favorited object.
        object:
          description: Details of the favorited object (folder or external content folder).
          allOf:
          - $ref: '#/components/schemas/Folder1'
    Permission:
      type: object
      properties:
        id:
          type: integer
          description: Unique identifier for the permission.
        name:
          type: string
          description: Name of the permission.
        allowed:
          type: boolean
          description: Indicates whether the permission is granted (True) or denied (False).
    Error:
      type: object
      properties:
        code:
          type: string
          description: Error code
        message:
          type: string
          description: Error message
    Errors:
      type: object
      properties:
        error:
          type: array
          items:
            $ref: '#/components/schemas/Error'
    Role:
      type: object
      properties:
        id:
          type: integer
          description: Role ID
        name:
          type: string
          description: Role name
        rank:
          type: integer
          description: Role rank
        type:
          type: string
          description: Role type
    MetaData:
      type: object
      properties:
        total:
          type: integer
          description: Total number of items available.
        limit:
          type: integer
          description: Maximum number of items returned per page.
        offset:
          type: integer
          description: Number of items skipped before the current page.
    UserBasic:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier (UUID) for the user.
        email:
          type: string
          description: Email address associated with the user.
        name:
          type: string
          description: Full name of the user.
        profileIcon:
          type: string
          description: URL or identifier for the user's profile icon.
    FavoriteListOpenAPI2:
      type: object
      properties:
        data:
          description: List of favorite entries.
          type: array
          items:
            $ref: '#/components/schemas/FavoriteOpenAPI2'
        metadata:
          description: Pagination metadata for the result set.
          allOf:
          - $ref: '#/components/schemas/MetaData'
    Folder1:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Unique identifier (UUID) of the folder.
        parentId:
          type: string
          format: uuid
          description: Unique identifier (UUID) of the parent object.
        name:
          type: string
          description: Name of the object.
        type:
          type: string
          description: Type of the object.<br>`f` – File.<br>`d` – Folder.
        userId:
          type: string
          format: uuid
          description: Unique identifier (UUID) who created the folder.
        creator:
          description: Details of the user who created the object.
          allOf:
          - $ref: '#/components/schemas/UserBasic'
        created:
          type: string
          format: date
          description: The date and time when the object was created.
        modified:
          type: string
          format: date
          description: The date and time when the object was last modified.
        expire:
          type: string
          format: date
          description: Expiration timestamp of the object, if applicable.
        permissions:
          description: List of permissions associated with the object.
          type: array
          items:
            $ref: '#/components/schemas/Permission'
        deleted:
          type: boolean
          description: Indicates whether the object has been deleted.
        permDeleted:
          type: boolean
          description: Indicates whether the object has been permanently deleted.
        permalink:
          type: string
          description: Permanent URL link to access the object.
        path:
          type: string
          description: Path to the folder in the hierarchy.
        members:
          description: List of members who have access to the object.
          type: array
          items:
            $ref: '#/components/schemas/Member'
        vendorDocId:
          type: string
          description: Vendor document ID associated with the object.
        vendorDocName:
          type: string
          description: Name of the vendor document associated with the object.
        secure:
          type: boolean
          description: Indicates whether the folder or the parent folder containing the file is marked as secure.
        source:
          type: integer
          description: ID representing the source of the object (1 - Salesforce, 2 - Teams).
        isShared:
          type: boolean
          description: Indicates if the folder is shared with other users.
        syncable:
          type: boolean
          description: Indicates if the folder can be synced by Desktop Sync Client.
        fileLifetime:
          type: integer
          description: Time duration (in days) for which the files in this folder are kept after being added to the folder.
        description:
          type: string
          description: The description of the folder.
        parent:
          description: The parent folder of the current folder.
          allOf:
          - $ref: '#/components/schemas/Folder'
        isFavorite:
          type: boolean
          description: Indicates if the folder is marked as a favorite by the user.
        pushedFilesCount:
          type: integer
          description: The number of files that have been pushed to mobile apps in this folder.
        currentUserRole:
          description: The role of the current user in this folder.
          allOf:
          - $ref: '#/components/schemas/Role'
        avStatus:
          type: string
          description: The Antivirus (AV) status of the folder.
        dlpStatus:
          type: string
          description: The Data Loss Prevention (DLP) status of the folder.
        totalMembersCount:
          type: integer
          description: Total number of members who have access to this folder.
        totalFoldersCount:
          type: integer
          description: Total number of subfolders within this folder.
        totalFilesCount:
          type: integer
          description: Total number of files within this folder.
        maxFolderExpiration:
          type: string
          format: date
          description: The maximum expiration date allowed for files in this folder.
        maxFileLifetime:
          type: integer
          description: The maximum duration (in days) that files in this folder can be kept after being added to the folder.
        isLdapGroupMember:
          type: boolean
          description: Indicates if the folder is part of an LDAP group.
        isUnderMyFolder:
          type: boolean
          description: Indicates if this folder is a subfolder of the user's "My Folder".
        pathIds:
          type: string
          description: A list of IDs representing the path of the folder within the folder hierarchy.
        isRoot:
          type: boolean
          description: Indicates if this folder is a root folder.
        rootId:
          type: string
          format: uuid
          description: The ID of the root folder if this is a subfolder.
        useFolderQuota:
          type: boolean
          description: Indicates if a folder quota is applied to this folder.
        quota:
          type: integer
          description: The storage quota for the folder (in bytes).
        size:
          type: integer
          description: The total storage size used by the folder (in bytes).
        freeSpace:
          type: integer
          description: The amount of free space available in the folder (in bytes).
        inheritanceEnabled:
          type: boolean
          description: Indicates if a folder inherits permissions from the parent folder