Kiteworks

Kiteworks folders API

The folders API from Kiteworks — 30 operation(s) for folders.

GitHub OpenAPI

Documentation

📖
Documentation
https://developer.kiteworks.com/api-endpoints.html
📖
APIReference
https://developer.kiteworks.com/api-reference.html
📖
Documentation
https://developer.kiteworks.com/pubsub-quick-start.html

Specifications

⚙
OpenAPI
https://raw.githubusercontent.com/api-evangelist/kiteworks/refs/heads/main/openapi/kiteworks-folders-api-openapi.yml

OpenAPI Specification

kiteworks-folders-api-openapi.yml Raw ↑ 
openapi: 3.0.2
info:
  version: '28'
  title: Kiteworks API Documentation activities folders API
tags:
- name: folders
paths:
  /rest/folders:
    delete:
      tags:
      - folders
      summary: Delete a list of folders
      description: Deletes multiple folders specified in the request.
      responses:
        '204':
          description: The specified folders were deleted. No content is returned.
        '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
  /rest/folders/actions/favorite:
    post:
      tags:
      - folders
      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:
      - folders
      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
  /rest/folders/actions/permanent:
    delete:
      tags:
      - folders
      summary: Permanently delete the specified folders
      description: "Permanently delete the specified folders.\n               These folders will no longer be accessible by any means."
      responses:
        '204':
          description: The specified folders were permanently deleted. No content is returned.
        '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
  /rest/folders/actions/recover:
    patch:
      tags:
      - folders
      summary: Recover deleted folders
      description: Recover deleted folders and their children files and folders.
      responses:
        '200':
          description: Returns the list of recovered folders with their updated metadata.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Folder'
                  metadata:
                    $ref: '#/components/schemas/MetaData'
              examples:
                RecoveredFolders:
                  summary: Folders successfully recovered
                  value:
                  - id: abc12345def67890ab
                    name: Reports
                    type: d
                    parent_id: xyz98765cba43210fe
                    deleted: false
                    modified: 2024-07-01T10:00:00+0000
                    avStatus: clean
                    dlpStatus: clean
        '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
  /rest/folders/actions/scan:
    post:
      tags:
      - folders
      summary: Triggers on demand AV/DLP scan on multiple folders
      description: Attempts to trigger an AV/DLP scan on requested folders.
      responses:
        '200':
          description: Returns the list of folders with their scan status updated to reflect that scans have been triggered.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Folder'
                  metadata:
                    $ref: '#/components/schemas/MetaData'
              examples:
                BulkScanTriggered:
                  summary: Scans triggered — statuses are pending
                  value:
                  - id: abc12345def67890ab
                    name: Reports
                    type: d
                    parent_id: xyz98765cba43210fe
                    deleted: false
                    avStatus: pending
                    dlpStatus: pending
                  - id: def67890abc12345fe
                    name: Archives
                    type: d
                    parent_id: xyz98765cba43210fe
                    deleted: false
                    avStatus: pending
                    dlpStatus: pending
        '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: id:in
        description: List of IDs of entities to scan. Search for results that match any of the specified values for this parameter.
        required: true
        schema:
          type: string
      - in: query
        name: with
        description: With parameters
        schema:
          type: string
      - in: query
        name: mode
        description: Determines the detail level of the response body.
        schema:
          type: string
          enum:
          - full_with_links
          - full
          - compact
  /rest/folders/shared:
    get:
      tags:
      - folders
      summary: List top level shared folders
      description: Return the list of top level shared folders.
      responses:
        '200':
          description: Returns a paginated list of top-level folders shared with the current user.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Folder'
                  metadata:
                    $ref: '#/components/schemas/MetaData'
              examples:
                SharedFolderList:
                  summary: A page of shared folders
                  value:
                  - id: abc12345def67890ab
                    name: Team Workspace
                    description: Shared team files
                    type: d
                    parent_id: xyz98765cba43210fe
                    deleted: false
                    created: 2024-01-10T09:00:00+0000
                    modified: 2024-06-20T11:30:00+0000
                    syncable: false
                    secure: false
                    isFavorite: true
                    isShared: true
                    totalFilesCount: 25
                    totalFoldersCount: 5
                    totalMembersCount: 8
                    avStatus: clean
                    dlpStatus: clean
        '490':
          description: Request blocked by WAF
      deprecated: false
      parameters:
      - in: query
        name: name
        description: Folder name
        schema:
          type: string
      - in: query
        name: name:contains
        description: Folder name. Search for results that contain the specified characters in this parameter.
        schema:
          type: string
      - in: query
        name: userId
        description: Unique identifier of Object creator
        schema:
          type: string
      - in: query
        name: userId:in
        description: Unique identifier of Object creator. Search for results that match any of the specified values for this parameter.
        schema:
          type: string
      - in: query
        name: created
        description: Object creation date
        schema:
          type: string
          format: date
      - in: query
        name: created:gt
        description: Object creation date. Search for results where this parameter value is greater than the specified value.
        schema:
          type: string
          format: date
      - in: query
        name: created:gte
        description: Object creation date. Search for results where this parameter value is greater than or equal to the specified value.
        schema:
          type: string
          format: date
      - in: query
        name: created:lt
        description: Object creation date. Search for results where this parameter value is less than the specified value.
        schema:
          type: string
          format: date
      - in: query
        name: created:lte
        description: Object creation date. Search for results where this parameter value is less than or equal to the specified value.
        schema:
          type: string
          format: date
      - in: query
        name: modified
        description: Object modification date
        schema:
          type: string
          format: date
      - in: query
        name: modified:gt
        description: Object modification date. Search for results where this parameter value is greater than the specified value.
        schema:
          type: string
          format: date
      - in: query
        name: modified:gte
        description: Object modification date. Search for results where this parameter value is greater than or equal to the specified value.
        schema:
          type: string
          format: date
      - in: query
        name: modified:lt
        description: Object modification date. Search for results where this parameter value is less than the specified value.
        schema:
          type: string
          format: date
      - in: query
        name: modified:lte
        description: Object modification date. Search for results where this parameter value is less than or equal to the specified value.
        schema:
          type: string
          format: date
      - in: query
        name: deleted
        description: Indicates whether the object is deleted.
        schema:
          type: boolean
      - in: query
        name: expire
        description: Expiration date
        schema:
          type: integer
      - in: query
        name: expire:gt
        description: Expiration date. Search for results where this parameter value is greater than the specified value.
        schema:
          type: integer
      - in: query
        name: expire:gte
        description: Expiration date. Search for results where this parameter value is greater than or equal to the specified value.
        schema:
          type: integer
      - in: query
        name: expire:lt
        description: Expiration date. Search for results where this parameter value is less than the specified value.
        schema:
          type: integer
      - in: query
        name: expire:lte
        description: Expiration date. Search for results where this parameter value is less than or equal to the specified value.
        schema:
          type: integer
      - in: query
        name: fileLifetime
        description: Folder lifetime
        schema:
          type: integer
      - in: query
        name: fileLifetime:gt
        description: Folder lifetime. Search for results where this parameter value is greater than the specified value.
        schema:
          type: integer
      - in: query
        name: fileLifetime:gte
        description: Folder lifetime. Search for results where this parameter value is greater than or equal to the specified value.
        schema:
          type: integer
      - in: query
        name: fileLifetime:lt
        description: Folder lifetime. Search for results where this parameter value is less than the specified value.
        schema:
          type: integer
      - in: query
        name: fileLifetime:lte
        description: Folder lifetime. Search for results where this parameter value is less than or equal to the specified value.
        schema:
          type: integer
      - in: query
        name: secure
        description: Folder secure flag
        schema:
          type: boolean
      - in: query
        name: description:contains
        description: Folder description. Search for results that contain the specified characters in this parameter.
        schema:
          type: string
      - in: query
        name: sharedByMe
        description: Filter shared folders by direction. Use `true` to return only folders shared by me, `false` for folders shared with me, or omit to return both.
        schema:
          type: boolean
      - in: query
        name: orderBy
        description: Sorting options
        schema:
          type: array
          items:
            type: string
          enum:
          - name:asc
          - name:desc
          - created:asc
          - created:desc
          - modified:asc
          - modified:desc
      - in: query
        name: offset
        description: Offset
        schema:
          type: integer
      - in: query
        name: limit
        description: Limit
        schema:
          type: integer
      - in: query
        name: with
        description: With parameters
        schema:
          type: string
      - in: query
        name: mode
        description: Determines the detail level of the response body.
        schema:
          type: string
          enum:
          - full_with_links
          - full
          - compact
  /rest/folders/{id}/actions/move:
    post:
      summary: Move a folder
      description: "### Description:\n  Moves the specified folder to a new destination folder.\n### Precondition:\n  User must have `folder_move` permission for the folder being moved.\n  User must have `folder_add` permission for the destination folder.\n### Response:\n  The folder is moved to the destination folder.\n"
      tags:
      - folders
      parameters:
      - in: path
        name: id
        required: true
        description: The unique identifier (UUID) of the entity.
        schema:
          type: string
          format: uuid
      - 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
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DestinationFolderIdRequest'
      responses:
        '201':
          description: Folder successfully moved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Folder1'
        '401':
          description: 'Unauthorized<br /><br /><i>Possible error codes: </i>ERR_AUTH_INVALID_CSRF, ERR_AUTH_UNAUTHORIZED'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
              examples:
                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_USER, ERR_ENTITY_CONTAINS_LOCKED_FILES, ERR_ENTITY_IS_BASE_DIR, ERR_ENTITY_IS_MY_DIR, ERR_ENTITY_IS_SECURE_FOLDER, ERR_ENTITY_IS_SYNC_DIR'
          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_ENTITY_CONTAINS_LOCKED_FILES:
                  summary: Folder contains locked files
                  description: Folder contains locked files
                  value:
                    errors:
                    - code: ERR_ENTITY_CONTAINS_LOCKED_FILES
                      message: Folder contains locked files
                ERR_ENTITY_IS_BASE_DIR:
                  summary: Operation not permitted on Base Folder
                  description: Operation not permitted on Base Folder
                  value:
                    errors:
                    - code: ERR_ENTITY_IS_BASE_DIR
                      message: Operation not permitted on Base Folder
                ERR_ENTITY_IS_MY_DIR:
                  summary: Operation not permitted on Tray Folder
                  description: Operation not permitted on Tray Folder
                  value:
                    errors:
                    - code: ERR_ENTITY_IS_MY_DIR
                      message: Operation not permitted on Tray Folder
                ERR_ENTITY_IS_SECURE_FOLDER:
                  summary: Operation not permitted on restricted Folder.
                  description: Operation not permitted on restricted Folder.
                  value:
                    errors:
                    - code: ERR_ENTITY_IS_SECURE_FOLDER
                      message: Operation not permitted on restricted Folder.
                ERR_ENTITY_IS_SYNC_DIR:
                  summary: Operation not permitted on My Folder
                  description: Operation not permitted on My Folder
                  value:
                    errors:
                    - code: ERR_ENTITY_IS_SYNC_DIR
                      message: Operation not permitted on My Folder
        '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
        '413':
          description: 'Content Too Large<br /><br /><i>Possible error codes: </i>ERR_SYSTEM_NO_STORAGE_AVAILABLE'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
              examples:
                ERR_SYSTEM_NO_STORAGE_AVAILABLE:
                  summary: Folder owner's remaining storage quota does not permit for a file upload of this size.
                  description: Folder owner's remaining storage quota does not permit for a file upload of this size.
                  value:
                    errors:
                    - code: ERR_SYSTEM_NO_STORAGE_AVAILABLE
                      message: Folder owner's remaining storage quota does not permit for a file upload of this size.
        '422':
          description: 'Unprocessable Content<br /><br /><i>Possible error codes: </i>ERR_CANNOT_MOVE_FOLDER_TO_SELF, ERR_CANNOT_MOVE_TO_CHILD, ERR_INVALID_PARAMETER'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
              examples:
                ERR_CANNOT_MOVE_FOLDER_TO_SELF:
                  summary: Cannot move folder to itself
                  description: Cannot move folder to itself
                  value:
                    errors:
                    - code: ERR_CANNOT_MOVE_FOLDER_TO_SELF
                      message: Cannot move folder to itself
                ERR_CANNOT_MOVE_TO_CHILD:
                  summary: Cannot move folder to its child
                  description: Cannot move folder to its child
                  value:
                    errors:
                    - code: ERR_CANNOT_MOVE_TO_CHILD
                      message: Cannot move folder to its child
                ERR_INVALID_PARAMETER:
                  summary: Invalid Parameter Exception
                  description: Invalid Parameter Exception
                  value:
                    errors:
                    - code: ERR_INVALID_PARAMETER
                      message: Invalid Parameter Exception
        '490':
          description: Request blocked by WAF
  /rest/folders/{id}/actions/permanent:
    delete:
      tags:
      - folders
      summary: Permanently delete the specified folder
      description: "Permanently delete the specified folder.\n               This folder will no longer be accessible by any means."
      responses:
        '204':
          description: The folder was permanently deleted. No content is returned.
        '490':
          description: Request blocked by WAF
      deprecated: false
      parameters:
      - in: path
        name: id
        description: The unique identifier (UUID) of the folder.
        required: true
        schema:
          type: string
  /rest/folders/{id}/actions/recover:
    patch:
      tags:
      - folders
      summary: Recover deleted folder
      description: Recover the specified folder. This un-marks the folder for deletion.
      responses:
        '200':
          description: Returns the recovered folder with its updated metadata.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Folder'
              examples:
                RecoveredFolder:
                  summary: Folder successfully recovered
                  value:
                    id: abc12345def67890ab
                    name: Reports
                    description: Quarterly reports
                    type: d
                    parent_id: xyz98765cba43210fe
                    deleted: false
                    created: 2024-03-01T08:00:00+0000
                    modified: 2024-07-01T10:00:00+0000
                    syncable: false
                    secure: false
                    isFavorite: false
                    isShared: false
                    totalFilesCount: 5
                    totalFoldersCount: 1
                    totalMembersCount: 0
                    avStatus: clean
                    dlpStatus: clean
        '490':
          description: Request blocked by WAF
      deprecated: false
      parameters:
      - in: path
        name: id
        description: The unique identifier (UUID) of the folder.
        required: true
        schema:
          type: string
      - 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
  /rest/folders/{id}/actions/scan:
    post:
      tags:
      - folders
      summary: Triggers on demand AV/DLP folder scan
      description: Attempts to trigger an AV/DLP scan on requested folder.
      responses:
        '200':
          description: Returns the folder with its scan status updated to reflect that a scan has been triggered.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Folder'
              examples:
                ScanTriggered:
                  summary: Scan triggered — status is pending
                  value:
                    id: abc12345def67890ab
                    name: Reports
                    type: d
                    parent_id: xyz98765cba43210fe
                    deleted: false
                    avStatus: pending
                    dlpStatus: pending
        '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: The unique identifier (UUID) of the folder.
        required: true
        schema:
          type: string
      - in: query
        name: returnEntity
        description: If set to `true`, returns information about the newly created entity.
        schema:
          type: boolean
      - in: query
        name: folderId:in
        description: List of folder IDs of entities to scan. Search for results that match any of the specified values for this parameter.
        schema:
          type: string
      - in: query
        name: fileId:in
        description: List of file IDs of entities to scan. Search for results that match any of the specified values for this parameter.
        schema:
          type: string
      - in: query
        name: with
        description: With parameters
        schema:
          type: string
      - in: query
        name: mode
        description: Determines the detail level of the response body.
        schema:
          type: string
          enum:
          - full_with_links
          - full
          - compact
  /rest/folders/{id}/actions/sendMessage:
    post:
      summary: Send message from a folder
      description: '### Description:

        Sends a message from the specified folder to members of the folder.


        ### Precondition:

        The user must be a member of the folder.


        ### Response:

        The message has been successfully sent to members.

        '
      tags:
      - folders
      parameters:
      - in: path
        name: id
        required: true
        description: The unique identifier (UUID) of the entity.
        schema:
          type: string
          format: uuid
      requestBody:
        content:
          application/json:
    

# --- truncated at 32 KB (246 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/kiteworks/refs/heads/main/openapi/kiteworks-folders-api-openapi.yml