Kiteworks admin API
The admin API from Kiteworks — 19 operation(s) for admin.
OpenAPI Specification
openapi: 3.0.2
info:
version: '28'
title: Kiteworks API Documentation activities 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:
# --- 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