{
"openapi": "3.0.2",
"info": {
"version": "28",
"title": "Kiteworks API — groups Operations"
},
"paths": {
"/rest/groups": {
"get": {
"summary": "List Kiteworks groups",
"description": "### Description:\n Returns the list of Kiteworks groups for the current user, including the email address of each member in the group.\n### Precondition:\n User must be authenticated.\n### Response:\n Returns the list of groups.\n",
"tags": [
"groups"
],
"parameters": [
{
"in": "query",
"name": "name",
"required": false,
"description": "Filter results by the exact group name.",
"schema": {
"type": "string"
}
},
{
"in": "query",
"name": "name:contains",
"required": false,
"description": "Filter results to groups whose names contain the specified characters.",
"schema": {
"type": "string"
}
},
{
"in": "query",
"name": "orderBy",
"required": false,
"description": "Sort order for the results. Default is `name:asc`.
Allowed values: `id:asc`, `id:desc`, `name:asc`, `name:desc`.",
"schema": {
"type": "string",
"enum": [
"id:asc",
"id:desc",
"name:asc",
"name:desc"
]
}
},
{
"in": "query",
"name": "limit",
"required": false,
"description": "Maximum number of groups to return.",
"schema": {
"type": "integer"
}
},
{
"in": "query",
"name": "offset",
"required": false,
"description": "Number of groups to skip before returning results, for pagination.",
"schema": {
"type": "integer"
}
}
],
"responses": {
"200": {
"description": "The groups list has been successfully returned.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ContactList"
}
}
}
},
"400": {
"description": "Bad Request
Possible error codes: ERR_REQUEST_INVALID_FILTER",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Errors"
},
"examples": {
"ERR_REQUEST_INVALID_FILTER": {
"summary": "Filter validation failed",
"description": "Filter validation failed",
"value": {
"errors": [
{
"code": "ERR_REQUEST_INVALID_FILTER",
"message": "Filter validation failed"
}
]
}
}
}
}
}
},
"401": {
"description": "Unauthorized
Possible error codes: ERR_ACCESS_USER, ERR_AUTH_INVALID_CSRF, ERR_AUTH_UNAUTHORIZED",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Errors"
},
"examples": {
"ERR_ACCESS_USER": {
"summary": "Insufficient access permissions",
"description": "Insufficient access permissions",
"value": {
"errors": [
{
"code": "ERR_ACCESS_USER",
"message": "Insufficient access permissions"
}
]
}
},
"ERR_AUTH_INVALID_CSRF": {
"summary": "Invalid CSRF Authentication",
"description": "Invalid CSRF Authentication",
"value": {
"errors": [
{
"code": "ERR_AUTH_INVALID_CSRF",
"message": "Invalid CSRF Authentication"
}
]
}
},
"ERR_AUTH_UNAUTHORIZED": {
"summary": "Unauthorized",
"description": "Unauthorized",
"value": {
"errors": [
{
"code": "ERR_AUTH_UNAUTHORIZED",
"message": "Unauthorized"
}
]
}
}
}
}
}
},
"490": {
"description": "Request blocked by WAF"
}
},
"x-codeSamples": [
{
"lang": "Shell",
"label": "cURL",
"source": "curl -X GET \\\n \"https://{instance}.kiteworks.com/rest/groups\" \\\n -H \"Authorization: Bearer YOUR_TOKEN\""
},
{
"lang": "Python",
"label": "Python",
"source": "import requests\n\nurl = \"https://{instance}.kiteworks.com/rest/groups\"\nheaders = {\n \"Authorization\": \"Bearer YOUR_TOKEN\",\n}\nresponse = requests.get(url, headers=headers)\nprint(response.json())"
}
]
},
"post": {
"summary": "Create a group entry",
"description": "### Description:\n Creates a new Kiteworks group of users.\n### Precondition:\n User must be authenticated.\n### Response:\n Returns the newly created group.\n",
"tags": [
"groups"
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GroupCreate"
}
}
}
},
"responses": {
"201": {
"description": "The group has been successfully created.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Contact"
}
}
}
},
"401": {
"description": "Unauthorized
Possible error codes: ERR_ACCESS_USER, ERR_AUTH_INVALID_CSRF, ERR_AUTH_UNAUTHORIZED",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Errors"
},
"examples": {
"ERR_ACCESS_USER": {
"summary": "Insufficient access permissions",
"description": "Insufficient access permissions",
"value": {
"errors": [
{
"code": "ERR_ACCESS_USER",
"message": "Insufficient access permissions"
}
]
}
},
"ERR_AUTH_INVALID_CSRF": {
"summary": "Invalid CSRF Authentication",
"description": "Invalid CSRF Authentication",
"value": {
"errors": [
{
"code": "ERR_AUTH_INVALID_CSRF",
"message": "Invalid CSRF Authentication"
}
]
}
},
"ERR_AUTH_UNAUTHORIZED": {
"summary": "Unauthorized",
"description": "Unauthorized",
"value": {
"errors": [
{
"code": "ERR_AUTH_UNAUTHORIZED",
"message": "Unauthorized"
}
]
}
}
}
}
}
},
"409": {
"description": "Conflict
Possible error codes: 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
Possible error codes: ERR_INVALID_PARAMETER",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Errors"
},
"examples": {
"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"
}
},
"x-codeSamples": [
{
"lang": "Shell",
"label": "cURL",
"source": "curl -X POST \\\n \"https://{instance}.kiteworks.com/rest/groups\" \\\n -H \"Authorization: Bearer YOUR_TOKEN\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"name\": \"string\",\n \"items\": [\n {\n \"email\": \"string\"\n }\n ]\n }'"
},
{
"lang": "Python",
"label": "Python",
"source": "import requests\n\nurl = \"https://{instance}.kiteworks.com/rest/groups\"\nheaders = {\n \"Authorization\": \"Bearer YOUR_TOKEN\",\n \"Content-Type\": \"application/json\",\n}\npayload = {\n \"name\": \"string\",\n \"items\": [\n {\n \"email\": \"string\"\n}\n]\n}\nresponse = requests.post(url, headers=headers, json=payload)\nprint(response.json())"
}
]
}
},
"/rest/groups/{id}": {
"get": {
"summary": "Return users for the specified group",
"description": "### Description:\n Returns the list of users for the specified group.\n### Precondition:\n User must be authenticated.\n### Response:\n Returns the group details including its members.\n",
"tags": [
"groups"
],
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"description": "The unique identifier of the entity.",
"schema": {
"type": "integer"
}
}
],
"responses": {
"200": {
"description": "The group has been successfully returned.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Contact"
}
}
}
},
"401": {
"description": "Unauthorized
Possible error codes: 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
Possible error codes: 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"
}
},
"x-codeSamples": [
{
"lang": "Shell",
"label": "cURL",
"source": "curl -X GET \\\n \"https://{instance}.kiteworks.com/rest/groups/:id\" \\\n -H \"Authorization: Bearer YOUR_TOKEN\""
},
{
"lang": "Python",
"label": "Python",
"source": "import requests\n\nid = \"VALUE\" # The unique identifier of the entity.\n\nurl = f\"https://{{instance}}.kiteworks.com/rest/groups/{id}\"\nheaders = {\n \"Authorization\": \"Bearer YOUR_TOKEN\",\n}\nresponse = requests.get(url, headers=headers)\nprint(response.json())"
}
]
},
"put": {
"summary": "Update a group entry",
"description": "### Description:\n Updates the specified group's name and members.\n### Precondition:\n User must be the owner of the group.\n### Response:\n The group is updated.\n",
"tags": [
"groups"
],
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"description": "The unique identifier of the entity.",
"schema": {
"type": "integer"
}
}
],
"responses": {
"200": {
"description": "The group has been successfully updated."
},
"401": {
"description": "Unauthorized
Possible error codes: 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
Possible error codes: 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"
}
]
}
}
}
}
}
},
"409": {
"description": "Conflict
Possible error codes: 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
Possible error codes: ERR_INVALID_PARAMETER",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Errors"
},
"examples": {
"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"
}
},
"x-codeSamples": [
{
"lang": "Shell",
"label": "cURL",
"source": "curl -X PUT \\\n \"https://{instance}.kiteworks.com/rest/groups/:id\" \\\n -H \"Authorization: Bearer YOUR_TOKEN\""
},
{
"lang": "Python",
"label": "Python",
"source": "import requests\n\nid = \"VALUE\" # The unique identifier of the entity.\n\nurl = f\"https://{{instance}}.kiteworks.com/rest/groups/{id}\"\nheaders = {\n \"Authorization\": \"Bearer YOUR_TOKEN\",\n}\nresponse = requests.put(url, headers=headers)\nprint(response.json())"
}
]
},
"delete": {
"summary": "Delete a group entry",
"description": "### Description:\n Deletes the specified group.\n### Precondition:\n User must be the owner of the group.\n### Response:\n The group is deleted.\n",
"tags": [
"groups"
],
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"description": "The unique identifier of the entity.",
"schema": {
"type": "integer"
}
}
],
"responses": {
"204": {
"description": "The group has been successfully deleted."
},
"401": {
"description": "Unauthorized
Possible error codes: 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
Possible error codes: 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"
}
},
"x-codeSamples": [
{
"lang": "Shell",
"label": "cURL",
"source": "curl -X DELETE \\\n \"https://{instance}.kiteworks.com/rest/groups/:id\" \\\n -H \"Authorization: Bearer YOUR_TOKEN\""
},
{
"lang": "Python",
"label": "Python",
"source": "import requests\n\nid = \"VALUE\" # The unique identifier of the entity.\n\nurl = f\"https://{{instance}}.kiteworks.com/rest/groups/{id}\"\nheaders = {\n \"Authorization\": \"Bearer YOUR_TOKEN\",\n}\nresponse = requests.delete(url, headers=headers)\nprint(response.json())"
}
]
}
}
},
"components": {
"schemas": {
"ContactList": {
"type": "object",
"properties": {
"metadata": {
"description": "Pagination metadata for the result set.",
"allOf": [
{
"$ref": "#/components/schemas/MetaData"
}
]
},
"data": {
"type": "array",
"description": "List of contacts.",
"items": {
"$ref": "#/components/schemas/Contact"
}
}
}
},
"Errors": {
"type": "object",
"properties": {
"error": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"GroupCreate": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "The name of the group."
},
"items": {
"type": "array",
"minItems": 1,
"description": "List of group members, each specified by their email address. At least one member is required.",
"items": {
"$ref": "#/components/schemas/GroupEmail"
}
}
},
"required": [
"items",
"name"
]
},
"Contact": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"description": "Unique identifier of the contact."
},
"userId": {
"type": "string"
},
"name": {
"type": "string",
"description": "Display name of the contact."
},
"created": {
"type": "string",
"format": "date",
"description": "Date and time when the contact was created."
},
"modified": {
"type": "string",
"format": "date",
"description": "Date and time when the contact was last modified."
},
"lastContactDate": {
"type": "string",
"format": "date",
"description": "Date and time of the most recent interaction with this contact."
},
"items": {
"type": "array",
"description": "List of email addresses or distribution lists for this contact.",
"items": {
"$ref": "#/components/schemas/ContactItem"
}
}
}
},
"ContactItem": {
"type": "object",
"properties": {
"email": {
"type": "string",
"description": "Email address of the contact."
},
"isDistributionList": {
"type": "boolean",
"description": "Indicates whether the contact is a distribution list."
},
"profileIcon": {
"type": "string",
"description": "URL or identifier of the contact's profile icon."
}
}
},
"GroupEmail": {
"type": "object",
"properties": {
"email": {
"type": "string",
"format": "email",
"description": "Email address of the group member."
}
},
"required": [
"email"
]
},
"Error": {
"type": "object",
"properties": {
"code": {
"type": "string",
"description": "Error code"
},
"message": {
"type": "string",
"description": "Error message"
}
}
},
"MetaData": {
"type": "object",
"properties": {
"total": {
"type": "integer",
"description": "Total number of items available."
},
"limit": {
"type": "integer",
"description": "Maximum number of items returned per page."
},
"offset": {
"type": "integer",
"description": "Number of items skipped before the current page."
}
}
}
}
}
}