Download OpenAPI specification:Download
The middleware API of ${PRODUCT_NAME} allows to manipulate the user accounts, filter profiles, devices, and all notifications of the user stored in the notification center.
Authenticates a user, and creates a new server session for the user specified in the request body. The session
identifier will be stored in the response cookie protect-sid
. If the user has two-factor authentication
enabled, a token will be sent to the email address or phone number. That token needs to be sent with the route
/session/login/token
to fully authenticate the user.
The identifier of the user and the password needed for authentication.
password required | string >= 6 characters The password of the user. |
username required | string [ 1 .. 50 ] characters The middleware identifier of the user. |
{- "password": "string",
- "username": "string"
}
{ }
If the user authenticated with the route /session/login
has two-factor authentication enabled, a token has
been sent to the email address or phone number. This route allows to generate and send another token to the
user which will be expected to be returned with the route /session/login/token
afterwards.
{ }
If the user authenticated with the route /session/login
has two-factor authentication enabled, a token has
been sent to the email address or phone number. That token needs to be sent with this route to fully
authenticate the user.
The token needed for authentication.
token required | string >= 4 characters The authentication token that has been sent to the user. |
{- "token": "string"
}
{ }
Returns the static configuration (classification platforms, categories, and presets) of an existing user account, according to the device mode.
user_id required | string The middleware identifier of the user. The API supports several ways to identify the user sending a request:
|
{- "categories": [
- {
- "name": "string",
- "title": "string"
}
], - "device_mode": true,
- "engines": [
- {
- "name": "string",
- "title": "string"
}
], - "platforms": [
- {
- "name": "string",
- "title": "string"
}
], - "presets": [
- {
- "categories": [
- "string"
], - "name": "string",
- "title": "string"
}
]
}
Returns the settings of an existing user account.
user_id required | string The middleware identifier of the user. The API supports several ways to identify the user sending a request:
|
{- "email_2fa": "string",
- "has_2fa": true,
- "locale": "string",
- "phone_2fa": "string",
- "profile_wizard_shown": true,
- "user_id": "string"
}
Modifies the settings of an existing user account.
user_id required | string The middleware identifier of the user. The API supports several ways to identify the user sending a request:
|
The properties to be changed for the user account. Omitted properties will not be modified.
email_2fa | string [ 1 .. 100 ] characters The email address used to send an email with the token for two-factor authentication. |
has_2fa | boolean Whether the user will use two-factor authentication with an additional token sent to an email address or to a phone number. |
locale | string [ 1 .. 32 ] characters The locale of the user, e.g. en-US. |
phone_2fa | string [ 1 .. 40 ] characters The phone number used to send an SMS with the token for two-factor authentication. |
profile_wizard_shown | boolean Whether the initial profile wizard has been shown in the web application. |
user_id required | string [ 1 .. 50 ] characters The middleware identifier of the user (used in the URLs of the middleware API). |
{- "email_2fa": "string",
- "has_2fa": true,
- "locale": "string",
- "phone_2fa": "string",
- "profile_wizard_shown": true,
- "user_id": "string"
}
{- "email_2fa": "string",
- "has_2fa": true,
- "locale": "string",
- "phone_2fa": "string",
- "profile_wizard_shown": true,
- "user_id": "string"
}
Changes the internal password of an existing user account. If the user has been identified by URL parameter, or
via identity server, this command allows to set the new password without having to know the current password
(the property old_password
in the request body will be ignored and can be omitted).
user_id required | string The middleware identifier of the user. The API supports several ways to identify the user sending a request:
|
The new password to be set for the user.
old_password | string >= 6 characters The current password. |
password required | string >= 6 characters The new password. |
{- "old_password": "string",
- "password": "string"
}
{ }
Creates a new filter profile in an existing user account. The identifier of the new filter profile will be set to the first available free profile identifier in the user account.
user_id required | string The middleware identifier of the user. The API supports several ways to identify the user sending a request:
|
oneway | boolean If set to true, the server response will not contain the complete settings of the filter profile but a JSON
object containing the property |
The properties to be set for a new profile, or to be changed in an existing filter profile. Omitted properties will be set to their default values when creating a new profile, and will not be modified when patching an existing profile.
It is possible to partially create or update embedded objects by only specifying the properties inside the embedded objects to be modified. Other properties not mentioned in the request body remain unmodified. The following methods for partial updates are supported:
Specify a JSON object with embedded objects containing only the properties to be updated. This method is not
applicable for application/www-form-urlencoded
body data (see next list item).
{"homework_schedule":{"enabled":true}}
to enable the homework time schedule.{"bedtime_workdays":{"days":{"fr":true}}}
to enable Friday in the bedtime schedule for
workdays.Specify the properties to be modified with dot notation in the root object.
{"homework_schedule.enabled":true}
(or homework_schedule.enabled=true
for
application/www-form-urlencoded
body data) to enable the homework time schedule.{"bedtime_workdays.days.fr":true}
to enable Friday in the bedtime schedule for workdays.It is possible to patch existing string arrays by inserting or removing individual array elements, instead of replacing the entire array.
Specify a JSON object with insert
and delete
properties (both optional). Property values can be single
strings, or string arrays. The values will be inserted into or deleted from the existing array respectively.
{"whitelist":{"insert":["example.org","example.com"],"delete":"example.net"}}
to patch the
whitelist string array.{"homework_schedule":{"categories":{"insert":"C1","delete":"C2"}}}
to patch the category
list of the homework schedule.Specify the path to the string array property with dot notation, and the property value as JSON object with
insert
and delete
properties.
{"homework_schedule.categories":{"insert":"C1","delete":"C2"}}
to patch the category list of
the homework schedule.Specify the insert
and delete
properties together with the path to the array property with dot notation.
{"whitelist.insert":["example.org","example.com"],"whitelist.delete":"example.net"}
to patch
the whitelist string array.{"homework_schedule.categories.insert":"C1","homework_schedule.categories.delete":"C2"}
to
patch the category list of the homework schedule.It is possible to patch existing string arrays by toggling array elements with a patch set notation, instead of replacing the entire array.
Specify a JSON object with a patch
property. Property keys are the array elements to be inserted or
deleted, property values are booleans specifying whether to insert (true), or remove (false) the key value.
{"whitelist":{"patch":{"example.org":true,"example.net":false}}}
to patch the whitelist
string array.{"homework_schedule":{"categories":{"patch":{"C1":true,"C2":false}}}}
to patch the category
list of the homework schedule.Specify the path to the string array property with dot notation, and the property value as JSON object with a
patch
property.
{"homework_schedule.categories":{"patch":{"C1":true,"C2":false}}}
to patch the category list
of the homework schedule.Specify the patch
property together with the path to the array property with dot notation.
{"whitelist.patch":{"example.org":true,"example.net":false}}
to patch the whitelist string
array.{"homework_schedule.categories.patch":{"C1":true,"C2":false}}
to patch the category list of
the homework schedule.Specify the array elements to be inserted and deleted together with the path to the array property with dot-at notation. Use the at character "@" to separate property path and array element value. Everything after the first at character will be used as array element (including additional periods and at characters).
{"whitelist@example.org":true,"whitelist@example.net":false}
to patch the whitelist string
array.{"homework_schedule.categories@C1":true,"homework_schedule.categories@C2":false}
to patch
the category list of the homework schedule.avatar_version | integer >= 0 A unique positive integer for the current avatar image (can be used to bypass browser cache when getting
the avatar image). Will be zero, if there is no avatar image available for the profile. Otherwise, the
value of this property does not matter, especially it cannot be used to get older versions of an avatar
image. This property is constant, it cannot be changed in an existing profile, and it cannot be specified
to create a new profile. See route |
object Bedtime settings in weekend nights (Friday to Saturday, and Saturday to Sunday). Only the keys | |
object Bedtime settings in nights before workdays (Sunday to Monday, ..., Thursday to Friday). Only the keys | |
blacklist | Array of strings[ items non-empty ] A list with domain names that will always be blocked, regardless of other filtering settings in the profile
(except the domains listed in teh property |
categories | Array of strings[ items non-empty ] The identifiers of all classification categories to be blocked, and of all platforms to be allowed. If this
property will be set, the property |
disabled_duration | integer >= 0 Content-based filtering will be manually disabled temporarily for this duration from now, in seconds. If
set to zero, content-based filtering has not been disabled temporarily. Changing this property will
automatically change the value of the property |
disabled_until | integer >= 0 Content-based filtering has been manually disabled temporarily until this date and time, as UNIX timestamp
in seconds (UTC, zero is 1970-01-01 at midnight). Changing this property will automatically change the
value of the property |
filter_content | boolean Whether content-based filtering is enabled.
|
filter_security | boolean Whether virus/malware filtering is enabled. |
object Homework time settings with categories to be blocked, and platforms to be allowed while activated. | |
name | string <= 50 characters The user-defined name of the filter profile. |
Array of objects (OfftimeSchedule) [ items ] All existing offtime settings, as a dynamic array with unlimited number of elements. | |
pause_internet | boolean Whether internet access is currently disabled completely. |
preset | string non-empty The identifier of a predefined set of classification categories, or "custom" for a user-defined set, or
"none", if content filtering is disabled (property
|
profile_id required | integer >= 0 The unique identifier of the filter profile (used in the URLs of the middleware API). This property is constant, it cannot be changed in an existing profile, and it cannot be specified to create a new profile (the profile identifier will be set automatically). |
user_id required | string [ 1 .. 50 ] characters The middleware identifier of the user owning the filter profile. This property is constant, it cannot be changed in an existing profile, and it cannot be specified to create a new profile (user will be identified via URL or session). |
whitelist | Array of strings[ items non-empty ] A list with domain names that will never be blocked, regardless of other filtering settings in the profile. |
{- "avatar_version": 0,
- "bedtime_weekend": {
- "days": {
- "fr": true,
- "mo": true,
- "sa": true,
- "su": true,
- "th": true,
- "tu": true,
- "we": true
}, - "enabled": true,
- "end": 86399,
- "name": "string",
- "start": 86399
}, - "bedtime_workdays": {
- "days": {
- "fr": true,
- "mo": true,
- "sa": true,
- "su": true,
- "th": true,
- "tu": true,
- "we": true
}, - "enabled": true,
- "end": 86399,
- "name": "string",
- "start": 86399
}, - "blacklist": [
- "string"
], - "categories": [
- "string"
], - "disabled_duration": 0,
- "disabled_until": 0,
- "filter_content": true,
- "filter_security": true,
- "homework_schedule": {
- "days": {
- "fr": true,
- "mo": true,
- "sa": true,
- "su": true,
- "th": true,
- "tu": true,
- "we": true
}, - "enabled": true,
- "end": 86399,
- "name": "string",
- "start": 86399,
- "categories": [
- "string"
], - "preset": "string"
}, - "name": "string",
- "offtime_schedules": [
- {
- "days": {
- "fr": true,
- "mo": true,
- "sa": true,
- "su": true,
- "th": true,
- "tu": true,
- "we": true
}, - "enabled": true,
- "end": 86399,
- "name": "string",
- "start": 86399
}
], - "pause_internet": true,
- "preset": "string",
- "profile_id": 0,
- "user_id": "string",
- "whitelist": [
- "string"
]
}
{- "avatar_version": 0,
- "bedtime_weekend": {
- "days": {
- "fr": true,
- "mo": true,
- "sa": true,
- "su": true,
- "th": true,
- "tu": true,
- "we": true
}, - "enabled": true,
- "end": 86399,
- "name": "string",
- "start": 86399
}, - "bedtime_workdays": {
- "days": {
- "fr": true,
- "mo": true,
- "sa": true,
- "su": true,
- "th": true,
- "tu": true,
- "we": true
}, - "enabled": true,
- "end": 86399,
- "name": "string",
- "start": 86399
}, - "blacklist": [
- "string"
], - "categories": [
- "string"
], - "disabled_duration": 0,
- "disabled_until": 0,
- "filter_content": true,
- "filter_security": true,
- "homework_schedule": {
- "days": {
- "fr": true,
- "mo": true,
- "sa": true,
- "su": true,
- "th": true,
- "tu": true,
- "we": true
}, - "enabled": true,
- "end": 86399,
- "name": "string",
- "start": 86399,
- "categories": [
- "string"
], - "preset": "string"
}, - "name": "string",
- "offtime_schedules": [
- {
- "days": {
- "fr": true,
- "mo": true,
- "sa": true,
- "su": true,
- "th": true,
- "tu": true,
- "we": true
}, - "enabled": true,
- "end": 86399,
- "name": "string",
- "start": 86399
}
], - "pause_internet": true,
- "preset": "string",
- "profile_id": 0,
- "user_id": "string",
- "whitelist": [
- "string"
]
}
Deletes the settings of an existing filter profile.
user_id required | string The middleware identifier of the user. The API supports several ways to identify the user sending a request:
|
profile_id required | integer >= 0 The unique identifier of a filter profile. The profile identifier 0 (zero) always refers to the default filter profile of the user account. |
{ }
Returns the settings of an existing filter profile.
user_id required | string The middleware identifier of the user. The API supports several ways to identify the user sending a request:
|
profile_id required | integer >= 0 The unique identifier of a filter profile. The profile identifier 0 (zero) always refers to the default filter profile of the user account. |
{- "avatar_version": 0,
- "bedtime_weekend": {
- "days": {
- "fr": true,
- "mo": true,
- "sa": true,
- "su": true,
- "th": true,
- "tu": true,
- "we": true
}, - "enabled": true,
- "end": 86399,
- "name": "string",
- "start": 86399
}, - "bedtime_workdays": {
- "days": {
- "fr": true,
- "mo": true,
- "sa": true,
- "su": true,
- "th": true,
- "tu": true,
- "we": true
}, - "enabled": true,
- "end": 86399,
- "name": "string",
- "start": 86399
}, - "blacklist": [
- "string"
], - "categories": [
- "string"
], - "disabled_duration": 0,
- "disabled_until": 0,
- "filter_content": true,
- "filter_security": true,
- "homework_schedule": {
- "days": {
- "fr": true,
- "mo": true,
- "sa": true,
- "su": true,
- "th": true,
- "tu": true,
- "we": true
}, - "enabled": true,
- "end": 86399,
- "name": "string",
- "start": 86399,
- "categories": [
- "string"
], - "preset": "string"
}, - "name": "string",
- "offtime_schedules": [
- {
- "days": {
- "fr": true,
- "mo": true,
- "sa": true,
- "su": true,
- "th": true,
- "tu": true,
- "we": true
}, - "enabled": true,
- "end": 86399,
- "name": "string",
- "start": 86399
}
], - "pause_internet": true,
- "preset": "string",
- "profile_id": 0,
- "user_id": "string",
- "whitelist": [
- "string"
]
}
Modifies the settings of an existing filter profile.
user_id required | string The middleware identifier of the user. The API supports several ways to identify the user sending a request:
|
profile_id required | integer >= 0 The unique identifier of a filter profile. The profile identifier 0 (zero) always refers to the default filter profile of the user account. |
oneway | boolean If set to true, the server response will not contain the specified JSON data but an empty object only. This can be used to reduce network traffic, and allows the server to perform optimizations in specific cases. |
The properties to be set for a new profile, or to be changed in an existing filter profile. Omitted properties will be set to their default values when creating a new profile, and will not be modified when patching an existing profile.
It is possible to partially create or update embedded objects by only specifying the properties inside the embedded objects to be modified. Other properties not mentioned in the request body remain unmodified. The following methods for partial updates are supported:
Specify a JSON object with embedded objects containing only the properties to be updated. This method is not
applicable for application/www-form-urlencoded
body data (see next list item).
{"homework_schedule":{"enabled":true}}
to enable the homework time schedule.{"bedtime_workdays":{"days":{"fr":true}}}
to enable Friday in the bedtime schedule for
workdays.Specify the properties to be modified with dot notation in the root object.
{"homework_schedule.enabled":true}
(or homework_schedule.enabled=true
for
application/www-form-urlencoded
body data) to enable the homework time schedule.{"bedtime_workdays.days.fr":true}
to enable Friday in the bedtime schedule for workdays.It is possible to patch existing string arrays by inserting or removing individual array elements, instead of replacing the entire array.
Specify a JSON object with insert
and delete
properties (both optional). Property values can be single
strings, or string arrays. The values will be inserted into or deleted from the existing array respectively.
{"whitelist":{"insert":["example.org","example.com"],"delete":"example.net"}}
to patch the
whitelist string array.{"homework_schedule":{"categories":{"insert":"C1","delete":"C2"}}}
to patch the category
list of the homework schedule.Specify the path to the string array property with dot notation, and the property value as JSON object with
insert
and delete
properties.
{"homework_schedule.categories":{"insert":"C1","delete":"C2"}}
to patch the category list of
the homework schedule.Specify the insert
and delete
properties together with the path to the array property with dot notation.
{"whitelist.insert":["example.org","example.com"],"whitelist.delete":"example.net"}
to patch
the whitelist string array.{"homework_schedule.categories.insert":"C1","homework_schedule.categories.delete":"C2"}
to
patch the category list of the homework schedule.It is possible to patch existing string arrays by toggling array elements with a patch set notation, instead of replacing the entire array.
Specify a JSON object with a patch
property. Property keys are the array elements to be inserted or
deleted, property values are booleans specifying whether to insert (true), or remove (false) the key value.
{"whitelist":{"patch":{"example.org":true,"example.net":false}}}
to patch the whitelist
string array.{"homework_schedule":{"categories":{"patch":{"C1":true,"C2":false}}}}
to patch the category
list of the homework schedule.Specify the path to the string array property with dot notation, and the property value as JSON object with a
patch
property.
{"homework_schedule.categories":{"patch":{"C1":true,"C2":false}}}
to patch the category list
of the homework schedule.Specify the patch
property together with the path to the array property with dot notation.
{"whitelist.patch":{"example.org":true,"example.net":false}}
to patch the whitelist string
array.{"homework_schedule.categories.patch":{"C1":true,"C2":false}}
to patch the category list of
the homework schedule.Specify the array elements to be inserted and deleted together with the path to the array property with dot-at notation. Use the at character "@" to separate property path and array element value. Everything after the first at character will be used as array element (including additional periods and at characters).
{"whitelist@example.org":true,"whitelist@example.net":false}
to patch the whitelist string
array.{"homework_schedule.categories@C1":true,"homework_schedule.categories@C2":false}
to patch
the category list of the homework schedule.avatar_version | integer >= 0 A unique positive integer for the current avatar image (can be used to bypass browser cache when getting
the avatar image). Will be zero, if there is no avatar image available for the profile. Otherwise, the
value of this property does not matter, especially it cannot be used to get older versions of an avatar
image. This property is constant, it cannot be changed in an existing profile, and it cannot be specified
to create a new profile. See route |
object Bedtime settings in weekend nights (Friday to Saturday, and Saturday to Sunday). Only the keys | |
object Bedtime settings in nights before workdays (Sunday to Monday, ..., Thursday to Friday). Only the keys | |
blacklist | Array of strings[ items non-empty ] A list with domain names that will always be blocked, regardless of other filtering settings in the profile
(except the domains listed in teh property |
categories | Array of strings[ items non-empty ] The identifiers of all classification categories to be blocked, and of all platforms to be allowed. If this
property will be set, the property |
disabled_duration | integer >= 0 Content-based filtering will be manually disabled temporarily for this duration from now, in seconds. If
set to zero, content-based filtering has not been disabled temporarily. Changing this property will
automatically change the value of the property |
disabled_until | integer >= 0 Content-based filtering has been manually disabled temporarily until this date and time, as UNIX timestamp
in seconds (UTC, zero is 1970-01-01 at midnight). Changing this property will automatically change the
value of the property |
filter_content | boolean Whether content-based filtering is enabled.
|
filter_security | boolean Whether virus/malware filtering is enabled. |
object Homework time settings with categories to be blocked, and platforms to be allowed while activated. | |
name | string <= 50 characters The user-defined name of the filter profile. |
Array of objects (OfftimeSchedule) [ items ] All existing offtime settings, as a dynamic array with unlimited number of elements. | |
pause_internet | boolean Whether internet access is currently disabled completely. |
preset | string non-empty The identifier of a predefined set of classification categories, or "custom" for a user-defined set, or
"none", if content filtering is disabled (property
|
profile_id required | integer >= 0 The unique identifier of the filter profile (used in the URLs of the middleware API). This property is constant, it cannot be changed in an existing profile, and it cannot be specified to create a new profile (the profile identifier will be set automatically). |
user_id required | string [ 1 .. 50 ] characters The middleware identifier of the user owning the filter profile. This property is constant, it cannot be changed in an existing profile, and it cannot be specified to create a new profile (user will be identified via URL or session). |
whitelist | Array of strings[ items non-empty ] A list with domain names that will never be blocked, regardless of other filtering settings in the profile. |
{- "avatar_version": 0,
- "bedtime_weekend": {
- "days": {
- "fr": true,
- "mo": true,
- "sa": true,
- "su": true,
- "th": true,
- "tu": true,
- "we": true
}, - "enabled": true,
- "end": 86399,
- "name": "string",
- "start": 86399
}, - "bedtime_workdays": {
- "days": {
- "fr": true,
- "mo": true,
- "sa": true,
- "su": true,
- "th": true,
- "tu": true,
- "we": true
}, - "enabled": true,
- "end": 86399,
- "name": "string",
- "start": 86399
}, - "blacklist": [
- "string"
], - "categories": [
- "string"
], - "disabled_duration": 0,
- "disabled_until": 0,
- "filter_content": true,
- "filter_security": true,
- "homework_schedule": {
- "days": {
- "fr": true,
- "mo": true,
- "sa": true,
- "su": true,
- "th": true,
- "tu": true,
- "we": true
}, - "enabled": true,
- "end": 86399,
- "name": "string",
- "start": 86399,
- "categories": [
- "string"
], - "preset": "string"
}, - "name": "string",
- "offtime_schedules": [
- {
- "days": {
- "fr": true,
- "mo": true,
- "sa": true,
- "su": true,
- "th": true,
- "tu": true,
- "we": true
}, - "enabled": true,
- "end": 86399,
- "name": "string",
- "start": 86399
}
], - "pause_internet": true,
- "preset": "string",
- "profile_id": 0,
- "user_id": "string",
- "whitelist": [
- "string"
]
}
{- "avatar_version": 0,
- "bedtime_weekend": {
- "days": {
- "fr": true,
- "mo": true,
- "sa": true,
- "su": true,
- "th": true,
- "tu": true,
- "we": true
}, - "enabled": true,
- "end": 86399,
- "name": "string",
- "start": 86399
}, - "bedtime_workdays": {
- "days": {
- "fr": true,
- "mo": true,
- "sa": true,
- "su": true,
- "th": true,
- "tu": true,
- "we": true
}, - "enabled": true,
- "end": 86399,
- "name": "string",
- "start": 86399
}, - "blacklist": [
- "string"
], - "categories": [
- "string"
], - "disabled_duration": 0,
- "disabled_until": 0,
- "filter_content": true,
- "filter_security": true,
- "homework_schedule": {
- "days": {
- "fr": true,
- "mo": true,
- "sa": true,
- "su": true,
- "th": true,
- "tu": true,
- "we": true
}, - "enabled": true,
- "end": 86399,
- "name": "string",
- "start": 86399,
- "categories": [
- "string"
], - "preset": "string"
}, - "name": "string",
- "offtime_schedules": [
- {
- "days": {
- "fr": true,
- "mo": true,
- "sa": true,
- "su": true,
- "th": true,
- "tu": true,
- "we": true
}, - "enabled": true,
- "end": 86399,
- "name": "string",
- "start": 86399
}
], - "pause_internet": true,
- "preset": "string",
- "profile_id": 0,
- "user_id": "string",
- "whitelist": [
- "string"
]
}
Deletes the avatar image from an existing filter profile.
user_id required | string The middleware identifier of the user. The API supports several ways to identify the user sending a request:
|
profile_id required | integer >= 0 The unique identifier of a filter profile. The profile identifier 0 (zero) always refers to the default filter profile of the user account. |
{ }
Returns the avatar image of an existing filter profile.
user_id required | string The middleware identifier of the user. The API supports several ways to identify the user sending a request:
|
profile_id required | integer >= 0 The unique identifier of a filter profile. The profile identifier 0 (zero) always refers to the default filter profile of the user account. |
{- "error": "string"
}
Uploads a new avatar image for an existing filter profile. An existing avatar image will be replaced.
user_id required | string The middleware identifier of the user. The API supports several ways to identify the user sending a request:
|
profile_id required | integer >= 0 The unique identifier of a filter profile. The profile identifier 0 (zero) always refers to the default filter profile of the user account. |
The binary image data.
{- "avatar_version": 1
}
Creates a new offtime schedule in an existing filter profile, and appends it to the array of existing offtime
schedules in the profile's array property offtime_schedules
.
user_id required | string The middleware identifier of the user. The API supports several ways to identify the user sending a request:
|
profile_id required | integer >= 0 The unique identifier of a filter profile. The profile identifier 0 (zero) always refers to the default filter profile of the user account. |
The properties to be set for a new offtime schedule, or to be changed in an existing offtime schedule. Omitted properties will be set to their default values when creating a new offtime schedule, and will not be modified when patching an existing offtime schedule.
It is possible to partially create or update embedded objects by only specifying the properties inside the embedded objects to be modified. Other properties not mentioned in the request body remain unmodified. The following methods for partial updates are supported:
Specify a JSON object with embedded objects containing only the properties to be updated. This method is not
applicable for application/www-form-urlencoded
body data (see next list item).
{"days":{"fr":true}}
to enable Friday in the offtime schedule.Specify the properties to be modified with dot notation in the root object.
{"days.fr":true}
(or days.fr=true
for application/www-form-urlencoded
body data) to
enable Friday in the offtime schedule.object The weekday pattern with boolean values specifying whether the offtime schedule is active for the respective day of the week. | |
enabled | boolean Whether the offtime represented by this object is activated. Setting this property to false allows to disable this schedule without losing its time settings. |
end | integer [ 0 .. 86399 ] Time of the day when offtime ends, as number of seconds from midnight. |
name | string The user-defined name for this offtime schedule. |
start | integer [ 0 .. 86399 ] Time of the day when offtime starts, as number of seconds from midnight. |
{- "days": {
- "fr": true,
- "mo": true,
- "sa": true,
- "su": true,
- "th": true,
- "tu": true,
- "we": true
}, - "enabled": true,
- "end": 86399,
- "name": "string",
- "start": 86399
}
{- "days": {
- "fr": true,
- "mo": true,
- "sa": true,
- "su": true,
- "th": true,
- "tu": true,
- "we": true
}, - "enabled": true,
- "end": 86399,
- "name": "string",
- "start": 86399
}
Deletes the settings of an existing offtime schedule. Deleting offtime schedules shrinks the array (following offtime schedules will decrease their array indexes).
user_id required | string The middleware identifier of the user. The API supports several ways to identify the user sending a request:
|
profile_id required | integer >= 0 The unique identifier of a filter profile. The profile identifier 0 (zero) always refers to the default filter profile of the user account. |
index required | integer >= 0 The array index of the offtime schedule in the profile's array property |
{ }
Returns the settings of an existing offtime schedule.
user_id required | string The middleware identifier of the user. The API supports several ways to identify the user sending a request:
|
profile_id required | integer >= 0 The unique identifier of a filter profile. The profile identifier 0 (zero) always refers to the default filter profile of the user account. |
index required | integer >= 0 The array index of the offtime schedule in the profile's array property |
{- "days": {
- "fr": true,
- "mo": true,
- "sa": true,
- "su": true,
- "th": true,
- "tu": true,
- "we": true
}, - "enabled": true,
- "end": 86399,
- "name": "string",
- "start": 86399
}
Modifies the settings of an existing offtime schedule.
user_id required | string The middleware identifier of the user. The API supports several ways to identify the user sending a request:
|
profile_id required | integer >= 0 The unique identifier of a filter profile. The profile identifier 0 (zero) always refers to the default filter profile of the user account. |
index required | integer >= 0 The array index of the offtime schedule in the profile's array property |
The properties to be set for a new offtime schedule, or to be changed in an existing offtime schedule. Omitted properties will be set to their default values when creating a new offtime schedule, and will not be modified when patching an existing offtime schedule.
It is possible to partially create or update embedded objects by only specifying the properties inside the embedded objects to be modified. Other properties not mentioned in the request body remain unmodified. The following methods for partial updates are supported:
Specify a JSON object with embedded objects containing only the properties to be updated. This method is not
applicable for application/www-form-urlencoded
body data (see next list item).
{"days":{"fr":true}}
to enable Friday in the offtime schedule.Specify the properties to be modified with dot notation in the root object.
{"days.fr":true}
(or days.fr=true
for application/www-form-urlencoded
body data) to
enable Friday in the offtime schedule.object The weekday pattern with boolean values specifying whether the offtime schedule is active for the respective day of the week. | |
enabled | boolean Whether the offtime represented by this object is activated. Setting this property to false allows to disable this schedule without losing its time settings. |
end | integer [ 0 .. 86399 ] Time of the day when offtime ends, as number of seconds from midnight. |
name | string The user-defined name for this offtime schedule. |
start | integer [ 0 .. 86399 ] Time of the day when offtime starts, as number of seconds from midnight. |
{- "days": {
- "fr": true,
- "mo": true,
- "sa": true,
- "su": true,
- "th": true,
- "tu": true,
- "we": true
}, - "enabled": true,
- "end": 86399,
- "name": "string",
- "start": 86399
}
{- "days": {
- "fr": true,
- "mo": true,
- "sa": true,
- "su": true,
- "th": true,
- "tu": true,
- "we": true
}, - "enabled": true,
- "end": 86399,
- "name": "string",
- "start": 86399
}
Deletes the settings of an existing device.
user_id required | string The middleware identifier of the user. The API supports several ways to identify the user sending a request:
|
device_id required | string [ 16 .. 20 ] characters The unique identifier of a device (the EDNS client identifier of the device encoding its MAC address). |
{ }
Returns the settings of an existing device.
user_id required | string The middleware identifier of the user. The API supports several ways to identify the user sending a request:
|
device_id required | string [ 16 .. 20 ] characters The unique identifier of a device (the EDNS client identifier of the device encoding its MAC address). |
{- "created_ts": 0,
- "device_id": "stringstringstri",
- "mac": "string",
- "name": "string",
- "name_auto": "string",
- "notify": true,
- "producer": "string",
- "profile_id": 0,
- "type": "phone",
- "user_id": "string",
- "visited": true
}
Modifies the settings of an existing device.
user_id required | string The middleware identifier of the user. The API supports several ways to identify the user sending a request:
|
device_id required | string [ 16 .. 20 ] characters The unique identifier of a device (the EDNS client identifier of the device encoding its MAC address). |
oneway | boolean If set to true, the server response will not contain the specified JSON data but an empty object only. This can be used to reduce network traffic, and allows the server to perform optimizations in specific cases. |
The properties to be changed for the device. Omitted properties will not be modified.
created_ts | integer >= 0 The timestamp of registration of the device in the PowerDNS filter platform (Unix timestamp in seconds). |
device_id | string [ 16 .. 20 ] characters The unique identifier of the device (used in the URLs of the middleware API). This value is the EDNS client identifier of the device encoding its MAC address. This property is constant, it cannot be changed in an existing device. |
mac | string The MAC address of the device, in lower-case hexadecimal notation with colons as separator characters (for example "12:34:56:78:9a:bc"). This property is constant, it cannot be changed in an existing device. |
name | string <= 50 characters The user-defined name of the device. |
name_auto | string The built-in name of the device as reported by the device itself. This property is constant, it cannot be changed in an existing device. |
notify | boolean Specifies whether to send push notifications to the user if a request from this device has been blocked. |
producer | string The name of the manufacturer of the device, if available. This property is constant, it cannot be changed in an existing device. |
profile_id | integer >= 0 The unique identifier of the filter profile this device is associated to. Determines which internet traffic will be filtered on the device. |
type | string Default: "desktop" Enum: "phone" "tablet" "desktop" The type of the device. |
user_id | string [ 1 .. 50 ] characters The middleware identifier of the user owning the device. This property is constant, it cannot be changed in an existing device. |
visited | boolean Specifies whether the user has seen the device in the web application. Can be used to highlight new devices detected by the PowerDNS filter platform. |
{- "created_ts": 0,
- "device_id": "stringstringstri",
- "mac": "string",
- "name": "string",
- "name_auto": "string",
- "notify": true,
- "producer": "string",
- "profile_id": 0,
- "type": "phone",
- "user_id": "string",
- "visited": true
}
{- "created_ts": 0,
- "device_id": "stringstringstri",
- "mac": "string",
- "name": "string",
- "name_auto": "string",
- "notify": true,
- "producer": "string",
- "profile_id": 0,
- "type": "phone",
- "user_id": "string",
- "visited": true
}
Returns the settings of all existing devices.
user_id required | string The middleware identifier of the user. The API supports several ways to identify the user sending a request:
|
[- {
- "created_ts": 0,
- "device_id": "stringstringstri",
- "mac": "string",
- "name": "string",
- "name_auto": "string",
- "notify": true,
- "producer": "string",
- "profile_id": 0,
- "type": "phone",
- "user_id": "string",
- "visited": true
}
]
Deletes the settings of multiple existing devices. Device identifiers passed in the URL that do not refer to existing devices will be ignored.
user_id required | string The middleware identifier of the user. The API supports several ways to identify the user sending a request:
|
device_ids required | Array of strings[ items [ 16 .. 20 ] characters ] The unique identifiers of one or more devices (the EDNS client identifier of the devices encoding their MAC addresses), separated with commas. |
{ }
Returns the settings of multiple existing devices. Device identifiers passed in the URL that do not refer to existing devices will be ignored.
user_id required | string The middleware identifier of the user. The API supports several ways to identify the user sending a request:
|
device_ids required | Array of strings[ items [ 16 .. 20 ] characters ] The unique identifiers of one or more devices (the EDNS client identifier of the devices encoding their MAC addresses), separated with commas. |
[- {
- "created_ts": 0,
- "device_id": "stringstringstri",
- "mac": "string",
- "name": "string",
- "name_auto": "string",
- "notify": true,
- "producer": "string",
- "profile_id": 0,
- "type": "phone",
- "user_id": "string",
- "visited": true
}
]
Returns the contents of an existing message.
user_id required | string The middleware identifier of the user. The API supports several ways to identify the user sending a request:
|
msg_id required | string non-empty The unique identifier of a message. |
{- "app": "string",
- "broadcast": true,
- "categories": [
- "string"
], - "code": 0,
- "device_id": "string",
- "device_ip": "string",
- "domain": "string",
- "hidden": true,
- "msg_id": "string",
- "severity": "LOW",
- "text": "string",
- "timestamp": 0,
- "url": "string",
- "user_id": "string"
}
Modifies the contents of an existing message.
user_id required | string The middleware identifier of the user. The API supports several ways to identify the user sending a request:
|
msg_id required | string non-empty The unique identifier of a message. |
oneway | boolean If set to true, the server response will not contain the specified JSON data but an empty object only. This can be used to reduce network traffic, and allows the server to perform optimizations in specific cases. |
The properties to be changed in the message. Omitted properties will not be modified.
app | string The identifier of the application that generated the message. This property is constant, it cannot be changed in an existing message. |
broadcast | boolean Whether the message has been broadcasted to all users. This property is constant, it cannot be changed in an existing message. |
categories | Array of strings[ items non-empty ] The names of all classification categories that caused to block the request. This property is constant, it cannot be changed in an existing message. |
code | integer >= 0 Integral message type identifier:
This property is constant, it cannot be changed in an existing message. |
device_id | string The unique identifier of the device this message is associated to. Will be the empty string, if the message does not belong to a specific device. This property is constant, it cannot be changed in an existing message. |
device_ip | string The (current) IP address of the device this message is associated to. Will be the empty string, if the message does not belong to a specific device. This property is constant, it cannot be changed in an existing message. |
domain | string The domain name extracted from the property |
hidden | boolean Whether the user has decided to hide the message from the view. |
msg_id | string non-empty The unique identifier of the message. This property is constant, it cannot be changed in an existing message. |
severity | string Default: "LOW" Enum: "LOW" "MEDIUM" "HIGH" An identifier for the severity of the message. This property is constant, it cannot be changed in an existing message. |
text | string An arbitrary explicit message text to be shown to the user. This property is constant, it cannot be changed in an existing message. |
timestamp | integer >= 0 The UNIX timestamp (in seconds) of the event reported by this message. This property is constant, it cannot be changed in an existing message. |
url | string The URL that was blocked by a filter rule (may be empty). This property is constant, it cannot be changed in an existing message. |
user_id | string [ 1 .. 50 ] characters The middleware identifier of the user owning the message. This property is constant, it cannot be changed in an existing message. |
{- "app": "string",
- "broadcast": true,
- "categories": [
- "string"
], - "code": 0,
- "device_id": "string",
- "device_ip": "string",
- "domain": "string",
- "hidden": true,
- "msg_id": "string",
- "severity": "LOW",
- "text": "string",
- "timestamp": 0,
- "url": "string",
- "user_id": "string"
}
{- "app": "string",
- "broadcast": true,
- "categories": [
- "string"
], - "code": 0,
- "device_id": "string",
- "device_ip": "string",
- "domain": "string",
- "hidden": true,
- "msg_id": "string",
- "severity": "LOW",
- "text": "string",
- "timestamp": 0,
- "url": "string",
- "user_id": "string"
}
Returns the contents of all existing messages of the user.
user_id required | string The middleware identifier of the user. The API supports several ways to identify the user sending a request:
|
skip | integer >= 0 If set to a positive integer, skips the specified number of (most recent) messages. |
count | integer >= 0 If set to a positive integer, specifies the (maximum) number of messages to be returned. |
[- {
- "app": "string",
- "broadcast": true,
- "categories": [
- "string"
], - "code": 0,
- "device_id": "string",
- "device_ip": "string",
- "domain": "string",
- "hidden": true,
- "msg_id": "string",
- "severity": "LOW",
- "text": "string",
- "timestamp": 0,
- "url": "string",
- "user_id": "string"
}
]
Modifies the contents of all existing messages of the user.
user_id required | string The middleware identifier of the user. The API supports several ways to identify the user sending a request:
|
oneway | boolean If set to true, the server response will not contain the specified JSON data but an empty object only. This can be used to reduce network traffic, and allows the server to perform optimizations in specific cases. |
The properties to be changed in the messages. Omitted properties will not be modified.
app | string The identifier of the application that generated the message. This property is constant, it cannot be changed in an existing message. |
broadcast | boolean Whether the message has been broadcasted to all users. This property is constant, it cannot be changed in an existing message. |
categories | Array of strings[ items non-empty ] The names of all classification categories that caused to block the request. This property is constant, it cannot be changed in an existing message. |
code | integer >= 0 Integral message type identifier:
This property is constant, it cannot be changed in an existing message. |
device_id | string The unique identifier of the device this message is associated to. Will be the empty string, if the message does not belong to a specific device. This property is constant, it cannot be changed in an existing message. |
device_ip | string The (current) IP address of the device this message is associated to. Will be the empty string, if the message does not belong to a specific device. This property is constant, it cannot be changed in an existing message. |
domain | string The domain name extracted from the property |
hidden | boolean Whether the user has decided to hide the message from the view. |
msg_id | string non-empty The unique identifier of the message. This property is constant, it cannot be changed in an existing message. |
severity | string Default: "LOW" Enum: "LOW" "MEDIUM" "HIGH" An identifier for the severity of the message. This property is constant, it cannot be changed in an existing message. |
text | string An arbitrary explicit message text to be shown to the user. This property is constant, it cannot be changed in an existing message. |
timestamp | integer >= 0 The UNIX timestamp (in seconds) of the event reported by this message. This property is constant, it cannot be changed in an existing message. |
url | string The URL that was blocked by a filter rule (may be empty). This property is constant, it cannot be changed in an existing message. |
user_id | string [ 1 .. 50 ] characters The middleware identifier of the user owning the message. This property is constant, it cannot be changed in an existing message. |
{- "app": "string",
- "broadcast": true,
- "categories": [
- "string"
], - "code": 0,
- "device_id": "string",
- "device_ip": "string",
- "domain": "string",
- "hidden": true,
- "msg_id": "string",
- "severity": "LOW",
- "text": "string",
- "timestamp": 0,
- "url": "string",
- "user_id": "string"
}
[- {
- "app": "string",
- "broadcast": true,
- "categories": [
- "string"
], - "code": 0,
- "device_id": "string",
- "device_ip": "string",
- "domain": "string",
- "hidden": true,
- "msg_id": "string",
- "severity": "LOW",
- "text": "string",
- "timestamp": 0,
- "url": "string",
- "user_id": "string"
}
]