locations

4 endpoints
GET/rest/locations

Get locations

Description:

Returns a paginated list of available locations.

Precondition:

User must be authenticated.

Response:

Returns the list of locations.
Parameters
Query Parameters
limit
Optional
integer

Maximum number of locations to return. Must be between 1 and 10000.

offset
Optional
integer

Number of locations to skip before returning results, for pagination.

orderBy
Optional
string

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

Responses

The locations have been successfully returned.

id
integer

Location ID

name
string

Location name

dns
string

Location DNS

tenantId
integer

Tenant ID

total
integer

Total number of items available.

limit
integer

Maximum number of items returned per page.

offset
integer

Number of items skipped before the current page.

Unauthorized

Possible error codes: ERR_AUTH_INVALID_CSRF, ERR_AUTH_UNAUTHORIZED

code
string

Error code

message
string

Error message

Unprocessable Content

Possible error codes: ERR_INPUT_INVALID_FORMAT

code
string

Error code

message
string

Error message

Request blocked by WAF

Empty response body.
Shell
curl -X GET \
  "https://{instance}.kiteworks.com/rest/locations" \
  -H "Authorization: Bearer YOUR_TOKEN"
Python
import requests

url = "https://{instance}.kiteworks.com/rest/locations"
headers = {
    "Authorization": "Bearer YOUR_TOKEN",
}
response = requests.get(url, headers=headers)
print(response.json())
Responses
{ "data": [ { "id": 1, "name": "string", "dns": "string", "tenantId": 1 } ], "metadata": { "total": 1, "limit": 1, "offset": 1 } }
{ "errors": [ { "code": "ERR_AUTH_INVALID_CSRF", "message": "Invalid CSRF Authentication" } ] }
{ "errors": [ { "code": "ERR_AUTH_UNAUTHORIZED", "message": "Unauthorized" } ] }
{ "errors": [ { "code": "ERR_INPUT_INVALID_FORMAT", "message": "The input is invalid." } ] }
// Error - No Body
POST/rest/locations

Create a location entry.

Creates a new location entry with a name and optional domain. Requires system admin privileges.

Parameters
Query Parameters
returnEntity
Optional
boolean

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

mode
Optional
string

Determines the detail level of the response body.

Request Body
name
Required
string

Location name. Ask administrator for location names for your server

domain
Required
string

A URL domain that can be used to access the servers in this location,
e.g. location.domain.com.
The domain should be registered in a DNS to point to the servers.

addLinks
boolean

Indicates whether HATEOAS links should be included in the response

Responses

Location created successfully.

id
integer

Location ID

name
string

Location name

dns
string

Location DNS

tenantId
integer

Tenant ID

Forbidden

Possible error codes: ERR_ACCESS_SYSTEM_ADMIN

code
string

Error code

message
string

Error message

Conflict

Possible error codes: ERR_ENTITY_EXISTS

code
string

Error code

message
string

Error message

Unprocessable Content

Possible error codes: ERR_INPUT_INVALID_FORMAT, ERR_INPUT_REQUIRED

code
string

Error code

message
string

Error message

Request blocked by WAF

Empty response body.
Shell
curl -X POST \
  "https://{instance}.kiteworks.com/rest/locations" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
         "name": "string",
         "domain": "string",
         "addLinks": true
       }'
Python
import requests

url = "https://{instance}.kiteworks.com/rest/locations"
headers = {
    "Authorization": "Bearer YOUR_TOKEN",
    "Content-Type": "application/json",
}
payload = {
  "name": "string",
  "domain": "string",
  "addLinks": true
}
response = requests.post(url, headers=headers, json=payload)
print(response.json())
Responses
{ "id": 3, "name": "EU Central", "dns": "eucentral.example.com" }
{ "errors": { "code": "ERR_ACCESS_SYSTEM_ADMIN", "message": "Authenticated user is not a System Admin" } }
{ "errors": { "code": "ERR_ENTITY_EXISTS", "message": "Entity exists" } }
{ "errors": { "code": "ERR_INPUT_REQUIRED", "message": "Field is required" } }
// Error - No Body
GET/rest/locations/{id}

Return location name.

Returns the details of the specified location, including its name and DNS URL.

Parameters
Path Parameters
id
Required
integer

ID of the location to be retrieved

Responses

Location details retrieved successfully.

id
integer

Location ID

name
string

Location name

dns
string

Location DNS

tenantId
integer

Tenant ID

Request blocked by WAF

Empty response body.
Shell
curl -X GET \
  "https://{instance}.kiteworks.com/rest/locations/:id" \
  -H "Authorization: Bearer YOUR_TOKEN"
Python
import requests

id = "VALUE"  # ID of the location to be retrieved

url = f"https://{{instance}}.kiteworks.com/rest/locations/{id}"
headers = {
    "Authorization": "Bearer YOUR_TOKEN",
}
response = requests.get(url, headers=headers)
print(response.json())
Responses
{ "id": 1, "name": "US West", "dns": "uswest.example.com" }
// Error - No Body
DELETE/rest/locations/{id}

Delete a location.

Permanently deletes the specified location. Requires system admin privileges.

Parameters
Path Parameters
id
Required
integer

ID of the location to remove from

Responses

Location deleted successfully.

Empty response body.

Forbidden

Possible error codes: ERR_ACCESS_SYSTEM_ADMIN, ERR_ACCESS_USER

code
string

Error code

message
string

Error message

Request blocked by WAF

Empty response body.
Shell
curl -X DELETE \
  "https://{instance}.kiteworks.com/rest/locations/:id" \
  -H "Authorization: Bearer YOUR_TOKEN"
Python
import requests

id = "VALUE"  # ID of the location to remove from

url = f"https://{{instance}}.kiteworks.com/rest/locations/{id}"
headers = {
    "Authorization": "Bearer YOUR_TOKEN",
}
response = requests.delete(url, headers=headers)
print(response.json())
Responses
// Request successful - No Body
{ "errors": { "code": "ERR_ACCESS_SYSTEM_ADMIN", "message": "Authenticated user is not a System Admin" } }
{ "errors": { "code": "ERR_ACCESS_USER", "message": "Insufficient access permissions" } }
// Error - No Body
PreviousldapGroups
Nextmail