{
"openapi": "3.0.2",
"info": {
"version": "28",
"title": "Kiteworks API — notifications Operations"
},
"paths": {
"/rest/folders/{id}/actions/setNotifications": {
"put": {
"tags": [
"notifications"
],
"summary": "Set/Update notifications",
"description": "Creates or updates the current user's notification subscription for the specified folder. Optionally applies the same settings to all nested subfolders. Returns HTTP 201 if a new subscription was created, or HTTP 200 if an existing one was updated.",
"responses": {
"200": {
"description": "Notification subscription set successfully.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UserNotification"
},
"examples": {
"NotificationSet": {
"summary": "Notification subscription after create or update",
"value": {
"objectId": "f0e1d2c3-b4a5-6789-0fed-cba987654321",
"userId": "u1a2b3c4-d5e6-7890-abcd-ef1234567890",
"fileAdded": 1,
"commentAdded": 1
}
}
}
}
}
},
"422": {
"description": "Unprocessable Content
Possible error codes: ERR_INPUT_NOT_INTEGER",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Errors"
},
"examples": {
"ERR_INPUT_NOT_INTEGER": {
"summary": "Input is not a valid integer",
"description": "Input is not a valid integer",
"value": {
"errors": {
"code": "ERR_INPUT_NOT_INTEGER",
"message": "Input is not a valid integer"
}
}
}
}
}
}
},
"490": {
"description": "Request blocked by WAF"
}
},
"deprecated": false,
"parameters": [
{
"in": "path",
"name": "id",
"description": "The unique identifier of the folder.",
"required": true,
"schema": {
"type": "string"
}
},
{
"in": "query",
"name": "includeNested",
"description": "Set notification for nested folders as well",
"schema": {
"type": "boolean"
}
},
{
"in": "query",
"name": "offset",
"description": "Offset",
"schema": {
"type": "integer"
}
},
{
"in": "query",
"name": "limit",
"description": "Limit",
"schema": {
"type": "integer"
}
},
{
"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/UserNotification.Post"
}
}
}
},
"x-codeSamples": [
{
"lang": "Shell",
"label": "cURL",
"source": "curl -X PUT \\\n \"https://{instance}.kiteworks.com/rest/folders/:id/actions/setNotifications\" \\\n -H \"Authorization: Bearer YOUR_TOKEN\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"fileAdded\": 1,\n \"commentAdded\": 1,\n \"addLinks\": true\n }'"
},
{
"lang": "Python",
"label": "Python",
"source": "import requests\n\nid = \"VALUE\" # The unique identifier of the folder.\n\nurl = f\"https://{{instance}}.kiteworks.com/rest/folders/{id}/actions/setNotifications\"\nheaders = {\n \"Authorization\": \"Bearer YOUR_TOKEN\",\n \"Content-Type\": \"application/json\",\n}\npayload = {\n \"fileAdded\": 1,\n \"commentAdded\": 1,\n \"addLinks\": true\n}\nresponse = requests.put(url, headers=headers, json=payload)\nprint(response.json())"
}
]
}
},
"/rest/notifications": {
"get": {
"tags": [
"notifications"
],
"summary": "List notifications",
"description": "Returns a paginated list of notification subscriptions for the current user, including the folder each subscription is for and the enabled notification types.",
"responses": {
"200": {
"description": "List of notification subscriptions retrieved successfully.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/UserNotification"
}
},
"metadata": {
"$ref": "#/components/schemas/MetaData"
}
}
},
"examples": {
"NotificationList": {
"summary": "Paginated list of notification subscriptions",
"value": {
"data": [
{
"objectId": "f0e1d2c3-b4a5-6789-0fed-cba987654321",
"userId": "u1a2b3c4-d5e6-7890-abcd-ef1234567890",
"fileAdded": 1,
"commentAdded": 0
}
],
"metadata": {
"total": 1,
"limit": 50,
"offset": 0
}
}
}
}
}
}
},
"490": {
"description": "Request blocked by WAF"
}
},
"deprecated": false,
"parameters": [
{
"in": "query",
"name": "userId",
"description": "Filter notifications by the ID of the user who receives them.",
"schema": {
"type": "string"
}
},
{
"in": "query",
"name": "userId:in",
"description": "Filter notifications by the ID of the user who receives them.. Search for results that match any of the specified values for this parameter.",
"schema": {
"type": "string"
}
},
{
"in": "query",
"name": "objectId",
"description": "Filter notifications by the ID of the folder they are associated with.",
"schema": {
"type": "string"
}
},
{
"in": "query",
"name": "objectId:in",
"description": "Filter notifications by the ID of the folder they are associated with.. Search for results that match any of the specified values for this parameter.",
"schema": {
"type": "string"
}
},
{
"in": "query",
"name": "fileAdded",
"description": "Filter notifications triggered when a file is added.",
"schema": {
"type": "boolean"
}
},
{
"in": "query",
"name": "commentAdded",
"description": "Filter notifications triggered when a comment is added.",
"schema": {
"type": "boolean"
}
},
{
"in": "query",
"name": "orderBy",
"description": "Sorting options",
"schema": {
"type": "array",
"items": {
"type": "string"
},
"enum": [
"userId:asc",
"userId:desc",
"objectId:asc",
"objectId:desc",
"fileAdded:asc",
"fileAdded:desc",
"commentAdded:asc",
"commentAdded: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"
]
}
}
],
"x-codeSamples": [
{
"lang": "Shell",
"label": "cURL",
"source": "curl -X GET \\\n \"https://{instance}.kiteworks.com/rest/notifications\" \\\n -H \"Authorization: Bearer YOUR_TOKEN\""
},
{
"lang": "Python",
"label": "Python",
"source": "import requests\n\nurl = \"https://{instance}.kiteworks.com/rest/notifications\"\nheaders = {\n \"Authorization\": \"Bearer YOUR_TOKEN\",\n}\nresponse = requests.get(url, headers=headers)\nprint(response.json())"
}
]
}
},
"/rest/notifications/{object_id}": {
"delete": {
"tags": [
"notifications"
],
"summary": "Remove notification options",
"description": "Unsubscribes the current user from all notifications for the specified folder.",
"responses": {
"204": {
"description": "Notification subscription removed successfully."
},
"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"
}
},
"deprecated": false,
"parameters": [
{
"in": "path",
"name": "object_id",
"description": "Object ID of the folder to remove notification options",
"required": true,
"schema": {
"type": "integer"
}
}
],
"x-codeSamples": [
{
"lang": "Shell",
"label": "cURL",
"source": "curl -X DELETE \\\n \"https://{instance}.kiteworks.com/rest/notifications/:object_id\" \\\n -H \"Authorization: Bearer YOUR_TOKEN\""
},
{
"lang": "Python",
"label": "Python",
"source": "import requests\n\nobject_id = \"VALUE\" # Object ID of the folder to remove notification options\n\nurl = f\"https://{{instance}}.kiteworks.com/rest/notifications/{object_id}\"\nheaders = {\n \"Authorization\": \"Bearer YOUR_TOKEN\",\n}\nresponse = requests.delete(url, headers=headers)\nprint(response.json())"
}
]
}
}
},
"components": {
"schemas": {
"UserNotification": {
"description": "Class Notification",
"required": [
"userId"
],
"properties": {
"objectId": {
"description": "Unique identifier of the folder included in the notification",
"type": "string"
},
"fileAdded": {
"description": "Number of files added to the notification",
"type": "integer"
},
"commentAdded": {
"description": "Number of comments added to the notification",
"type": "integer"
},
"links": {
"description": "HATEOAS links associated with the entity",
"type": "array",
"items": {
"type": "string"
}
},
"userId": {
"description": "Unique identifier of the user who receives the notification",
"type": "string"
}
}
},
"Errors": {
"type": "object",
"properties": {
"error": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"UserNotification.Post": {
"description": "Class Notification",
"properties": {
"fileAdded": {
"description": "Number of files added to the notification",
"type": "integer"
},
"commentAdded": {
"description": "Number of comments added to the notification",
"type": "integer"
},
"addLinks": {
"description": "Indicates whether HATEOAS links should be included in the response",
"type": "boolean"
}
}
},
"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."
}
}
},
"Error": {
"type": "object",
"properties": {
"code": {
"type": "string",
"description": "Error code"
},
"message": {
"type": "string",
"description": "Error message"
}
}
}
}
}
}