Kiteworks admin API

openapi: 3.2.0
info:
  version: '28'
  title: Kiteworks API Documentation Admin API
tags:
- name: admin
paths:
  /rest/admin/hostnames:
    get:
      tags:
      - admin
      summary: List hostnames
      description: Returns a paginated list of all alias hostnames, including their hostname, disabled state, and deletion status.
      responses:
        '200':
          description: List of hostnames retrieved successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Hostname'
                  metadata:
                    $ref: '#/components/schemas/MetaData'
              examples:
                HostnameList:
                  summary: Paginated list of hostnames
                  value:
                    data:
                    - id: 1
                      hostname: alias.example.com
                      deleted: false
                      disabled: false
                    metadata:
                      total: 1
                      limit: 50
                      offset: 0
        '490':
          description: Request blocked by WAF
      deprecated: false
      parameters:
      - in: query
        name: alias_name
        description: Alias name
        schema:
          type: string
      - in: query
        name: alias_name:contains
        description: Alias name. Search for results that contain the specified characters in this parameter.
        schema:
          type: string
      - in: query
        name: tenant_id
        description: Tenant ID
        schema:
          type: integer
      - in: query
        name: tenant_id:gt
        description: Tenant ID. Search for results where this parameter value is greater than the specified value.
        schema:
          type: integer
      - in: query
        name: tenant_id:gte
        description: Tenant ID. Search for results where this parameter value is greater than or equal to the specified value.
        schema:
          type: integer
      - in: query
        name: tenant_id:lt
        description: Tenant ID. Search for results where this parameter value is less than the specified value.
        schema:
          type: integer
      - in: query
        name: tenant_id:lte
        description: Tenant ID. Search for results where this parameter value is less than or equal to the specified value.
        schema:
          type: integer
      - in: query
        name: deleted
        description: Filter by whether the hostname is deleted.
        schema:
          type: boolean
      - in: query
        name: disabled
        description: Filter by whether the hostname is disabled.
        schema:
          type: boolean
      - in: query
        name: orderBy
        description: Sorting options
        schema:
          type: array
          items:
            type: string
          enum:
          - id:asc
          - id:desc
          - alias_name:asc
          - alias_name:desc
          - tenant_id:asc
          - tenant_id:desc
          - deleted:asc
          - deleted:desc
          - disabled:asc
          - disabled: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
    delete:
      tags:
      - admin
      summary: Deletes list of hostnames
      description: Soft-deletes a list of hostnames in a single request. Supports partial success, meaning valid items are processed even if some fail.
      responses:
        '204':
          description: Hostnames deleted 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
    post:
      tags:
      - admin
      summary: Create an alias hostname
      description: Creates a new alias hostname for the current tenant. The hostname must be a valid subdomain of the configured site domain and must not already exist.
      responses:
        '200':
          description: Hostname created successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Hostname'
              examples:
                HostnameCreated:
                  summary: A newly created hostname
                  value:
                    id: 2
                    hostname: newteam.example.com
                    deleted: false
                    disabled: false
        '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, ERR_INPUT_NOT_BOOLEAN'
          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
                ERR_INPUT_NOT_BOOLEAN:
                  summary: Input is not a valid boolean
                  description: Input is not a valid boolean
                  value:
                    errors:
                      code: ERR_INPUT_NOT_BOOLEAN
                      message: Input is not a valid boolean
        '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/Hostname.Post'
  /rest/admin/hostnames/{id}:
    get:
      tags:
      - admin
      summary: Returns the details of hostname of the specified ID.
      description: Returns the hostname record identified by the given ID, including its hostname value, disabled state, and deletion status.
      responses:
        '200':
          description: Hostname details retrieved successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Hostname'
              examples:
                HostnameInfo:
                  summary: Details of a single hostname record
                  value:
                    id: 1
                    hostname: alias.example.com
                    deleted: false
                    disabled: false
        '490':
          description: Request blocked by WAF
      deprecated: false
      parameters:
      - in: path
        name: id
        description: ID of the hostname to be retrieved
        required: true
        schema:
          type: integer
    put:
      tags:
      - admin
      summary: Disable / enable alias hostname
      description: Updates the disabled state of the specified hostname, allowing it to be enabled or disabled.
      responses:
        '200':
          description: Hostname updated successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Hostname'
              examples:
                HostnameDisabled:
                  summary: Hostname after being disabled
                  value:
                    id: 1
                    hostname: alias.example.com
                    deleted: false
                    disabled: true
                HostnameEnabled:
                  summary: Hostname after being re-enabled
                  value:
                    id: 1
                    hostname: alias.example.com
                    deleted: false
                    disabled: false
        '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 hostname to disable
        required: true
        schema:
          type: integer
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Hostname.Put'
    delete:
      tags:
      - admin
      summary: Mark specified hostname as deleted.
      description: Soft-deletes the specified hostname by marking it as deleted. The record is retained but treated as inactive.
      responses:
        '204':
          description: Hostname marked as deleted 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 hostname
        required: true
        schema:
          type: integer
  /rest/admin/mail:
    get:
      tags:
      - admin
      summary: List emails
      description: Returns a list of emails for any user in the system. This includes sent emails, received emails, draft emails, and request a file emails. Requires admin privileges.
      responses:
        '200':
          description: Returns a paginated list of emails matching the specified filters.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Email'
                  metadata:
                    $ref: '#/components/schemas/MetaData'
              examples:
                AdminEmailList:
                  summary: A page of emails
                  value:
                  - id: eml12345abc67890de
                    senderId: usr98765cba43210fe
                    templateId: 1
                    status: sent
                    type: sendfile
                    date: '2024-06-15'
                    deleted: false
                    emailPackageId: pkg12345abc67890de
                    isRead: true
                    bucket: inbox
                    subject: Q2 Reports
        '490':
          description: Request blocked by WAF
      deprecated: false
      parameters:
      - in: query
        name: senderId
        description: Unique identifier of User who sent Email
        schema:
          type: string
      - in: query
        name: senderId:in
        description: Unique identifier of User who sent Email. Search for results that match any of the specified values for this parameter.
        schema:
          type: string
      - in: query
        name: date
        description: Email creation date
        schema:
          type: string
          format: date
      - in: query
        name: date:gt
        description: Email creation date. Search for results where this parameter value is greater than the specified value.
        schema:
          type: string
          format: date
      - in: query
        name: date:gte
        description: Email 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: date:lt
        description: Email creation date. Search for results where this parameter value is less than the specified value.
        schema:
          type: string
          format: date
      - in: query
        name: date:lte
        description: Email 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_date
        description: Email modification date
        schema:
          type: string
          format: date
      - in: query
        name: modified_date:gt
        description: Email modification date. Search for results where this parameter value is greater than the specified value.
        schema:
          type: string
          format: date
      - in: query
        name: modified_date:gte
        description: Email 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_date:lt
        description: Email modification date. Search for results where this parameter value is less than the specified value.
        schema:
          type: string
          format: date
      - in: query
        name: modified_date:lte
        description: Email 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: Filter emails based on whether they have been deleted.
        schema:
          type: boolean
      - in: query
        name: emailPackageId
        description: Email Package unique identifier
        schema:
          type: string
      - in: query
        name: emailPackageId:in
        description: Email Package unique identifier. Search for results that match any of the specified values for this parameter.
        schema:
          type: string
      - in: query
        name: templateId
        description: Email Template unique identifier
        schema:
          type: integer
      - in: query
        name: templateId:in
        description: Email Template unique identifier. Search for results that match any of the specified values for this parameter.
        schema:
          type: integer
      - in: query
        name: status
        description: 'Filter emails by status. Accepted values: `sent`, `draft`, `queued`, `error`, `self_send`, `transferring`.'
        schema:
          type: array
          items:
            type: string
          enum:
          - sent
          - draft
          - queued
          - error
          - self_send
          - transferring
      - in: query
        name: isPreview
        description: Whether the email is a preview email
        schema:
          type: boolean
      - in: query
        name: isUserSent
        description: Whether the email was sent by some user
        schema:
          type: boolean
      - in: query
        name: webFormId
        description: Email web form ID
        schema:
          type: string
      - in: query
        name: webFormId:contains
        description: Email web form ID. Search for results that contain the specified characters in this parameter.
        schema:
          type: string
      - in: query
        name: orderBy
        description: Sorting options
        schema:
          type: array
          items:
            type: string
          enum:
          - id:asc
          - id:desc
          - date:asc
          - date:desc
          - status:asc
          - status:desc
      - in: query
        name: offset
        description: Offset
        schema:
          type: integer
      - in: query
        name: limit
        description: Limit
        schema:
          type: integer
  /rest/admin/mail/actions/withdrawFiles/users/{userId}:
    delete:
      tags:
      - admin
      summary: Withdraw all files from the emails of deleted or demoted users
      description: Withdraws all files from the emails of users who have been deleted or demoted.
      responses:
        '204':
          description: The files were successfully withdrawn from the specified emails. No content is returned.
        '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: userId
        description: The unique identifier of the user from whom to withdraw files.
        required: true
        schema:
          type: string
      - in: query
        name: emailId:in
        description: A list of email IDs to be processed.
        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/admin/profiles:
    get:
      tags:
      - admin
      summary: List user types (profiles)
      description: Returns a paginated list of user type profiles configured in the system (e.g., Standard and Restricted), including each profile's name, built-in status, and cloneability.
      responses:
        '200':
          description: List of user type profiles retrieved successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Profile'
                  metadata:
                    $ref: '#/components/schemas/MetaData'
              examples:
                ProfileList:
                  summary: Paginated list of user type profiles
                  value:
                    data:
                    - id: 1
                      name: Standard
                      builtIn: 1
                      cloneable: 1
                    metadata:
                      total: 2
                      limit: 50
                      offset: 0
        '490':
          description: Request blocked by WAF
      deprecated: false
      parameters:
      - in: query
        name: name
        description: Profile name
        schema:
          type: string
      - in: query
        name: name:contains
        description: Profile name. Search for results that contain the specified characters in this parameter.
        schema:
          type: string
      - in: query
        name: orderBy
        description: Sorting options
        schema:
          type: array
          items:
            type: string
          enum:
          - id:asc
          - id:desc
          - name:asc
          - name: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/admin/profiles/mappingOrder:
    get:
      tags:
      - admin
      summary: Get profile mapping order
      description: Returns the current ordering of user type profiles used to determine which profile is applied to a user on login when multiple mapping rules match.
      responses:
        '200':
          description: Profile mapping order retrieved successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProfileMappingOrder'
              examples:
                MappingOrder:
                  summary: Current profile mapping order
                  value:
                    order:
                    - 1
                    - 3
                    - 2
        '490':
          description: Request blocked by WAF
      deprecated: false
    put:
      tags:
      - admin
      summary: Update profile mapping order
      description: Updates the ordering of user type profiles used to determine which profile is applied to a user on login when multiple mapping rules match. When the peek parameter is set, returns the projected impact without applying changes.
      responses:
        '200':
          description: Profile mapping order updated successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProfileMappingOrder'
              examples:
                MappingOrderUpdated:
                  summary: Profile mapping order after update
                  value:
                    order:
                    - 3
                    - 1
                    - 2
        '422':
          description: 'Unprocessable Content<br /><br /><i>Possible error codes: </i>ERR_INPUT_NOT_BOOLEAN, ERR_INPUT_NOT_ARRAY_OF_INTEGERS, ERR_INPUT_REQUIRED'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
              examples:
                ERR_INPUT_NOT_BOOLEAN:
                  summary: Input is not a valid boolean
                  description: Input is not a valid boolean
                  value:
                    errors:
                      code: ERR_INPUT_NOT_BOOLEAN
                      message: Input is not a valid boolean
                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: 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
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProfileMappingOrder.Put'
  /rest/admin/profiles/mappings:
    get:
      tags:
      - admin
      summary: Get profile mapping results for user
      description: Simulates profile mapping evaluation for the specified user and returns which profile mapping rules would match, without applying any changes.
      responses:
        '200':
          description: Profile mapping test results retrieved successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProfileMappingsTest'
              examples:
                MappingTestResult:
                  summary: Profile mapping evaluation for a user
                  value:
                    result:
                    - id: ldap1
                      name: Engineering LDAP
                      filter: (memberOf=cn=Engineering)
        '490':
          description: Request blocked by WAF
      deprecated: false
      parameters:
      - in: query
        name: user
        description: Username or email of the user to test mappings for
        required: true
        schema:
          type: string
  /rest/admin/profiles/{id}:
    get:
      tags:
      - admin
      summary: Return a user type
      description: Returns the details of the specified user type profile, including its name, built-in status, and cloneability.
      responses:
        '200':
          description: User type profile details retrieved successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Profile'
              examples:
                ProfileInfo:
                  summary: Details of a single user type profile
                  value:
                    id: 1
                    name: Standard
                    builtIn: 1
                    cloneable: 1
        '490':
          description: Request blocked by WAF
      deprecated: false
      parameters:
      - in: path
        name: id
        description: ID of the user type (profile) to be retrieved
        required: true
        schema:
          type: integer
  /rest/admin/profiles/{id}/mappings:
    get:
      tags:
      - admin
      summary: Get profile mapping details
      description: Returns the identity provider mapping rules configured for the specified profile, including LDAP, SSO, and kiteworks-based filter policies.
      responses:
        '200':
          description: Profile mapping details retrieved successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProfileMappings'
              examples:
                ProfileMappings:
                  summary: Mapping rules for a profile
                  value:
                    ldap:
                    - id: ldap1
                      name: Corp LDAP
                      filter: (memberOf=cn=Engineering)
                    sso: []
                    kiteworks:
                    - id: kiteworks
                      filter: example.com
        '490':
          description: Request blocked by WAF
      deprecated: false
      parameters:
      - in: path
        name: id
        description: ID of the profile to get mapping details for
        required: true
        schema:
          type: integer
    put:
      tags:
      - admin
      summary: Update profile mapping details
      description: Updates the identity provider mapping rules for the specified profile. When the peek parameter is set, returns the projected impact of the changes without applying them.
      responses:
        '200':
          description: Profile mapping details updated successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProfileMappingChanges'
              examples:
                ProfileMappingUpdated:
                  summary: Profile mapping after update
                  value:
                    impact: []
        '422':
          description: 'Unprocessable Content<br /><br /><i>Possible error codes: </i>ERR_INPUT_NOT_BOOLEAN'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
              examples:
                ERR_INPUT_NOT_BOOLEAN:
                  summary: Input is not a valid boolean
                  description: Input is not a valid boolean
                  value:
                    errors:
                      code: ERR_INPUT_NOT_BOOLEAN
                      message: Input is not a valid boolean
        '490':
          description: Request blocked by WAF
      deprecated: false
      parameters:
      - in: path
        name: id
        description: ID of the profile to update mapping details for
        required: true
        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
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProfileMappingChanges.Put'
  /rest/admin/profiles/{id}/users:
    get:
      tags:
      - admin
      summary: Return list of users with the specified types
      description: Returns a paginated list of users assigned to the specified user type profile (e.g., all Restricted users), including their names and email addresses.
      responses:
        '200':
          description: List of users with the specified profile retrieved successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/User'
                  metadata:
                    $ref: '#/components/schemas/MetaData'
              examples:
                ProfileUserList:
                  summary: Users assigned to a profile
                  value:
                    data:
                    - id: 42
                      name: Jane Doe
                      email: jane.doe@example.com
                    metadata:
                      total: 1
                      limit: 50
                      offset: 0
        '403':
          description: 'Forbidden<br /><br /><i>Possible error codes: </i>ERR_ACCESS_USER'
          content:
            application

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