Documentation Powered by ReDoc

OX Protect - Web Middleware API (2.0.0)

Download OpenAPI specification:Download

Open-Xchange: info@open-xchange.com URL: https://www.open-xchange.com

The Web Middleware API of OX Protect allows web applications to communicate with the OX Protect Core Middleware.

General

General settings unrelated to users.

Monitoring endpoint for Prometheus.

Provides application metrics data in the native text format expected by the Prometheus server.

Responses

Response samples

Content type
text/plain
# HELP up 1 = up, 0 = not up
# TYPE up gauge
up 1

Return version information.

Returns version information for all components.

Responses

Response samples

Content type
application/json
{
  • "core": {
    },
  • "web": {
    }
}

Session

The session API to setup and destroy server-side user sessions.

Authenticate a user with password.

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.

Request Body schema:
application/json
application/json
application/x-www-form-urlencoded

The identifier of the user and the password needed for authentication.

locale
string [ 1 .. 32 ] characters

The locale to be used for the session (will be stored in the user settings). If omitted, the locale that is currently stored in the user settings will be used.

password
required
string >= 6 characters

The password of the user.

timezone
string [ 1 .. 100 ] characters

The current time zone of the user, e.g. Australia/Sydney. Will be used as initial time zone for the user account, if no time zone has been configured yet.

username
required
string [ 1 .. 50 ] characters

The middleware identifier of the user.

Responses

Request samples

Content type
application/json
application/json
application/x-www-form-urlencoded
{
  • "locale": "string",
  • "password": "string",
  • "timezone": "string",
  • "username": "string"
}

Response samples

Content type
application/json
Example
AWAITING_TFA_TOKEN
AWAITING_TFA_TOKEN
OK
{
  • "data": {
    },
  • "status": "AWAITING_TFA_TOKEN"
}

Send another token for two-factor authentication.

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.

Responses

Response samples

Content type
application/json
{
  • "data": {
    },
  • "status": "AWAITING_TFA_TOKEN"
}

Authenticate a user with the generated two-factor authentication token.

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.

Request Body schema:
application/json
application/json
application/x-www-form-urlencoded

The token needed for authentication.

token
required
string >= 4 characters

The authentication token that has been sent to the user.

Responses

Request samples

Content type
application/json
application/json
application/x-www-form-urlencoded
{
  • "token": "string"
}

Response samples

Content type
application/json
{
  • "data": {
    },
  • "status": "OK"
}

Invalidate a server session.

Invalidates the server session identified by the request cookie protect-sid.

Responses

Refresh a server session.

Refreshes the lifetime of the server session identified by the request cookie protect-sid, and returns whether the session is valid and associated to an authenticated user.

Responses

Response samples

Content type
application/json
{
  • "authed": true
}

Account

The account API to manage global settings of the user account.

Return the complete user account.

Returns the complete settings of a user account but the messages.

Responses

Response samples

Content type
application/json
{
  • "config": {
    },
  • "devices": [
    ],
  • "profiles": [
    ],
  • "settings": {
    },
  • "versions": {
    }
}

Return the static configuration of the user account.

Returns the static configuration (classification platforms, categories, presets, and time zones) to be used by the user account, according to the device mode of the account.

Responses

Response samples

Content type
application/json
{
  • "categories": [
    ],
  • "device_mode": true,
  • "platforms": [
    ],
  • "presets": [
    ],
  • "safesearch": [
    ],
  • "timezones": [
    ]
}

Return the settings of the user account.

Returns the settings of the user account.

Responses

Response samples

Content type
application/json
{
  • "ignore_list": [
    ],
  • "locale": "string",
  • "mail_active": true,
  • "mail_address": "string",
  • "mail_filter_content": true,
  • "mail_filter_security": true,
  • "mail_new_device": true,
  • "phone_active": true,
  • "phone_filter_content": true,
  • "phone_filter_security": true,
  • "phone_new_device": true,
  • "phone_number": "string",
  • "profile_wizard_shown": true,
  • "push_active": true,
  • "push_filter_content": true,
  • "push_filter_security": true,
  • "push_new_device": true,
  • "tfa_active": true,
  • "tfa_mail": "string",
  • "tfa_phone": "string",
  • "timezone": "string",
  • "user_id": "string"
}

Modify the settings of the user account.

Modifies the settings of the user account.

query Parameters
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.

Request Body schema:
application/json
application/json
application/x-www-form-urlencoded

The properties to be changed for the user account. Omitted properties will not be modified.

It is possible to patch ignore_list string array 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 array. The values will be inserted into or deleted from the existing array respectively.

    • Example: Use {"ignore_list":{"insert":["example.org","example.com"],"delete":"example.net"}} to patch the ignore_list string array.

  • Specify the insert and delete properties together with the path to the array property with dot notation.

    • Example: Use {"ignore_list.insert":["example.org","example.com"],"ignore_list.delete":"example.net"} to patch the ignore_list string array.

It is possible to patch the ignore_list string array 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.

    • Example: Use {"ignore_list":{"patch":{"example.org":true,"example.net":false}}} to patch the ignore_list string array.

  • Specify the patch property together with the path to the array property with dot notation.

    • Example: Use {"ignore_list.patch":{"example.org":true,"example.net":false}} to patch the ignore_list string array.

  • 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).

    • Example: Use {"ignore_list@example.org":true,"ignore_list@example.net":false} to patch the ignore_list string array.
ignore_list
Array of strings[ items non-empty ]

A list with domain names that will never be sent by push, email and SMS notifications, and can be used to filter the notification list.

locale
string [ 1 .. 32 ] characters

The locale of the user, e.g. en-US.

mail_active
boolean

Whether the registered email address will be used for notifications.

mail_address
string or null

The email address used in the notification center.

mail_filter_content
boolean

Whether to send email notifications for requests that have been blocked by content-based filtering. Will be effective only if the property mail_active is set to true.

mail_filter_security
boolean

Whether to send email notifications for requests that have been blocked by virus/malware filtering. Will be effective only if the property mail_active is set to true.

mail_new_device
boolean

Whether to send an email notification when a new device has been detected. Will be effective only if the property mail_active is set to true.

phone_active
boolean

Whether the registered phone number will be used for notifications.

phone_filter_content
boolean

Whether to send sms notifications for requests that have been blocked by content-based filtering. Will be effective only if the property phone_active is set to true.

phone_filter_security
boolean

Whether to send sms notifications for requests that have been blocked by virus/malware filtering. Will be effective only if the property phone_active is set to true.

phone_new_device
boolean

Whether to send a sms notification when a new device has been detected. Will be effective only if the property phone_active is set to true.

phone_number
string or null

The phone number used in the notification center.

profile_wizard_shown
boolean

Whether the initial profile wizard has been shown in the web application.

push_active
boolean

Whether the registered push tokens for mobile devices will be used for push notifications.

push_filter_content
boolean

Whether to send push notifications for requests that have been blocked by content-based filtering. Will be effective only if the property push_active is set to true.

push_filter_security
boolean

Whether to send push notifications for requests that have been blocked by virus/malware filtering. Will be effective only if the property push_active is set to true.

push_new_device
boolean

Whether to send a push notification when a new device has been detected. Will be effective only if the property push_active is set to true.

tfa_active
boolean

Whether the user will use two-factor authentication with an additional token sent to an email address or to a phone number.

tfa_mail
string or null [ 1 .. 100 ] characters

The email address used to send an email with the token for two-factor authentication.

tfa_phone
string or null [ 1 .. 40 ] characters

The phone number used to send an SMS with the token for two-factor authentication.

timezone
string or null [ 1 .. 100 ] characters

The time zone of the user, e.g. Australia/Sydney. Used for all profile settings with times, e.g. offtime and homework time schedules.

user_id
required
string [ 1 .. 50 ] characters

The middleware identifier of the user (used in the URLs of the middleware API).

Responses

Request samples

Content type
application/json
application/json
application/x-www-form-urlencoded
{
  • "ignore_list": [
    ],
  • "locale": "string",
  • "mail_active": true,
  • "mail_address": "string",
  • "mail_filter_content": true,
  • "mail_filter_security": true,
  • "mail_new_device": true,
  • "phone_active": true,
  • "phone_filter_content": true,
  • "phone_filter_security": true,
  • "phone_new_device": true,
  • "phone_number": "string",
  • "profile_wizard_shown": true,
  • "push_active": true,
  • "push_filter_content": true,
  • "push_filter_security": true,
  • "push_new_device": true,
  • "tfa_active": true,
  • "tfa_mail": "string",
  • "tfa_phone": "string",
  • "timezone": "string",
  • "user_id": "string"
}

Response samples

Content type
application/json
{
  • "ignore_list": [
    ],
  • "locale": "string",
  • "mail_active": true,
  • "mail_address": "string",
  • "mail_filter_content": true,
  • "mail_filter_security": true,
  • "mail_new_device": true,
  • "phone_active": true,
  • "phone_filter_content": true,
  • "phone_filter_security": true,
  • "phone_new_device": true,
  • "phone_number": "string",
  • "profile_wizard_shown": true,
  • "push_active": true,
  • "push_filter_content": true,
  • "push_filter_security": true,
  • "push_new_device": true,
  • "tfa_active": true,
  • "tfa_mail": "string",
  • "tfa_phone": "string",
  • "timezone": "string",
  • "user_id": "string"
}

Change the password of the user account.

Changes the internal password of the user account.

Request Body schema:
application/json
application/json
application/x-www-form-urlencoded

The current password of the user, and the new password to be set for the user.

old_password
required
string >= 6 characters

The current password to be verified for the user.

password
required
string >= 6 characters

The new password to be set for the user.

Responses

Request samples

Content type
application/json
application/json
application/x-www-form-urlencoded
{
  • "old_password": "string",
  • "password": "string"
}

Response samples

Content type
application/json
{
  • "error": "string"
}

Verify the password of the user account.

Verifies that the password in the request body matches the internal password of the user account.

Request Body schema:
application/json
application/json
application/x-www-form-urlencoded

The password to be checked.

password
required
string >= 6 characters

The password to be verified for the user.

Responses

Request samples

Content type
application/json
application/json
application/x-www-form-urlencoded
{
  • "password": "string"
}

Response samples

Content type
application/json
{
  • "valid": true
}

Profiles

The profile API to manage the user's filter profiles.

Create a new filter profile in the user account.

Creates a new filter profile in the user account. The identifier of the new filter profile will be set to the first available free profile identifier in the user account.

query Parameters
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 profile_id with the profile identifier only. This can be used to reduce network traffic, and allows the server to perform optimizations in specific cases.

Request Body schema:
application/json
application/json
application/x-www-form-urlencoded

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.

Adding domains into the domains_allowed string array property will remove them automatically from the domains_blocked string array property, and vice versa.

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).

    • Example: Use {"homework_schedule":{"enabled":true}} to enable the homework time schedule.
    • Example: Use {"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.

    • Example: Use {"homework_schedule.enabled":true} (or homework_schedule.enabled=true for application/www-form-urlencoded body data) to enable the homework time schedule.
    • Example: Use {"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.

    • Example: Use {"domains_allowed":{"insert":["example.org","example.com"],"delete":"example.net"}} to patch the domains_allowed string array.
    • Example: Use {"homework_schedule":{"categories_blocked":{"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.

    • Example: Use {"homework_schedule.categories_blocked":{"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.

    • Example: Use {"domains_allowed.insert":["example.org","example.com"],"domains_allowed.delete":"example.net"} to patch the domains_allowed string array.
    • Example: Use {"homework_schedule.categories_blocked.insert":"C1","homework_schedule.categories_blocked.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.

    • Example: Use {"domains_allowed":{"patch":{"example.org":true,"example.net":false}}} to patch the domains_allowed string array.
    • Example: Use {"homework_schedule":{"categories_blocked":{"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.

    • Example: Use {"homework_schedule.categories_blocked":{"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.

    • Example: Use {"domains_allowed.patch":{"example.org":true,"example.net":false}} to patch the domains_allowed string array.
    • Example: Use {"homework_schedule.categories_blocked.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).

    • Example: Use {"domains_allowed@example.org":true,"domains_allowed@example.net":false} to patch the domains_allowed string array.
    • Example: Use {"homework_schedule.categories_blocked@C1":true,"homework_schedule.categories_blocked@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 /user/{user_id}/profile/{profile_id}/avatar.

object

Bedtime settings in weekend nights (Friday to Saturday, and Saturday to Sunday). Only the keys fr and sa (Friday and Saturday) of the property days will have an effect. Changing the other weekday properties will not do anything. The time frame is intended to start at the respective day, and to end in the next day (property start should be in the evening, property end should be less than start).

object

Bedtime settings in nights before workdays (Sunday to Monday, ..., Thursday to Friday). Only the keys su, mo, tu, we, and th (Sunday to Thursday) of the property days will have an effect. Changing the other weekday properties will not do anything. The time frame is intended to start at the respective day, and to end in the next day (property start should be in the evening, property end should be less than start).

categories_blocked
Array of strings[ items non-empty ]

The kes of all classification categories to be blocked. If this property will be set, the property preset will be set to "custom" automatically.

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 too. The result of changing both properties at the same time is undefined.

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 disabled_duration too. The result of changing both properties at the same time is undefined.

domains_allowed
Array of strings[ items non-empty ]

A list with domain names that will never be blocked, regardless of other filtering settings in the profile.

domains_blocked
Array of strings[ items non-empty ]

A list with domain names that will always be blocked, regardless of other filtering settings in the profile.

filter_content
boolean

Whether content-based filtering is enabled.

  • If this property will be set to false, the property preset will be set to the value "none" automatically.
  • If this property will be set to true, the previous value of the property preset will be restored.
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.

platforms_allowed
Array of strings[ items non-empty ]

The kes of all classification platforms to be allowed independently from category settings in the property categories_blocked. If this property will be set, the property preset will be set to "custom" automatically.

platforms_blocked
Array of strings[ items non-empty ]

The kes of all classification platforms to be blocked independently from category settings in the property categories_blocked. If this property will be set, the property preset will be set to "custom" automatically.

preset
string non-empty

The key of a predefined set of classification items, or the special key "custom" for a user-defined set, or the special key "none", if content filtering is disabled (property filter_content is false).

  • If this property will be set to an existing preset list, the properties platforms_allowed, platforms_blocked, categories_blocked, and safesearch_enabled will be updated automatically.
  • If this property will be set to the value "none", the property filter_content will be set to false automatically (no content filtering, no domain filtering).
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).

safesearch_enabled
Array of strings[ items non-empty ]

The kes of all safe-search engines to be enabled. If this property will be set, the property preset will be set to "custom" 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).

Responses

Request samples

Content type
application/json
application/json
application/x-www-form-urlencoded
{
  • "avatar_version": 0,
  • "bedtime_weekend": {
    },
  • "bedtime_workdays": {
    },
  • "categories_blocked": [
    ],
  • "disabled_duration": 0,
  • "disabled_until": 0,
  • "domains_allowed": [
    ],
  • "domains_blocked": [
    ],
  • "filter_content": true,
  • "filter_security": true,
  • "homework_schedule": {
    },
  • "name": "string",
  • "offtime_schedules": [
    ],
  • "pause_internet": true,
  • "platforms_allowed": [
    ],
  • "platforms_blocked": [
    ],
  • "preset": "string",
  • "profile_id": 0,
  • "safesearch_enabled": [
    ],
  • "user_id": "string"
}

Response samples

Content type
application/json
{
  • "avatar_version": 0,
  • "bedtime_weekend": {
    },
  • "bedtime_workdays": {
    },
  • "categories_blocked": [
    ],
  • "disabled_duration": 0,
  • "disabled_until": 0,
  • "domains_allowed": [
    ],
  • "domains_blocked": [
    ],
  • "filter_content": true,
  • "filter_security": true,
  • "homework_schedule": {
    },
  • "name": "string",
  • "offtime_schedules": [
    ],
  • "pause_internet": true,
  • "platforms_allowed": [
    ],
  • "platforms_blocked": [
    ],
  • "preset": "string",
  • "profile_id": 0,
  • "safesearch_enabled": [
    ],
  • "user_id": "string"
}

Delete an existing filter profile.

Deletes the settings of an existing filter profile.

path Parameters
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.

Responses

Response samples

Content type
application/json
{
  • "deleted": true
}

Return an existing filter profile.

Returns the settings of an existing filter profile.

path Parameters
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.

Responses

Response samples

Content type
application/json
{
  • "avatar_version": 0,
  • "bedtime_weekend": {
    },
  • "bedtime_workdays": {
    },
  • "categories_blocked": [
    ],
  • "disabled_duration": 0,
  • "disabled_until": 0,
  • "domains_allowed": [
    ],
  • "domains_blocked": [
    ],
  • "filter_content": true,
  • "filter_security": true,
  • "homework_schedule": {
    },
  • "name": "string",
  • "offtime_schedules": [
    ],
  • "pause_internet": true,
  • "platforms_allowed": [
    ],
  • "platforms_blocked": [
    ],
  • "preset": "string",
  • "profile_id": 0,
  • "safesearch_enabled": [
    ],
  • "user_id": "string"
}

Modify an existing filter profile.

Modifies the settings of an existing filter profile.

path Parameters
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.

query Parameters
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.

Request Body schema:
application/json
application/json
application/x-www-form-urlencoded

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.

Adding domains into the domains_allowed string array property will remove them automatically from the domains_blocked string array property, and vice versa.

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).

    • Example: Use {"homework_schedule":{"enabled":true}} to enable the homework time schedule.
    • Example: Use {"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.

    • Example: Use {"homework_schedule.enabled":true} (or homework_schedule.enabled=true for application/www-form-urlencoded body data) to enable the homework time schedule.
    • Example: Use {"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.

    • Example: Use {"domains_allowed":{"insert":["example.org","example.com"],"delete":"example.net"}} to patch the domains_allowed string array.
    • Example: Use {"homework_schedule":{"categories_blocked":{"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.

    • Example: Use {"homework_schedule.categories_blocked":{"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.

    • Example: Use {"domains_allowed.insert":["example.org","example.com"],"domains_allowed.delete":"example.net"} to patch the domains_allowed string array.
    • Example: Use {"homework_schedule.categories_blocked.insert":"C1","homework_schedule.categories_blocked.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.

    • Example: Use {"domains_allowed":{"patch":{"example.org":true,"example.net":false}}} to patch the domains_allowed string array.
    • Example: Use {"homework_schedule":{"categories_blocked":{"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.

    • Example: Use {"homework_schedule.categories_blocked":{"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.

    • Example: Use {"domains_allowed.patch":{"example.org":true,"example.net":false}} to patch the domains_allowed string array.
    • Example: Use {"homework_schedule.categories_blocked.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).

    • Example: Use {"domains_allowed@example.org":true,"domains_allowed@example.net":false} to patch the domains_allowed string array.
    • Example: Use {"homework_schedule.categories_blocked@C1":true,"homework_schedule.categories_blocked@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 /user/{user_id}/profile/{profile_id}/avatar.

object

Bedtime settings in weekend nights (Friday to Saturday, and Saturday to Sunday). Only the keys fr and sa (Friday and Saturday) of the property days will have an effect. Changing the other weekday properties will not do anything. The time frame is intended to start at the respective day, and to end in the next day (property start should be in the evening, property end should be less than start).

object

Bedtime settings in nights before workdays (Sunday to Monday, ..., Thursday to Friday). Only the keys su, mo, tu, we, and th (Sunday to Thursday) of the property days will have an effect. Changing the other weekday properties will not do anything. The time frame is intended to start at the respective day, and to end in the next day (property start should be in the evening, property end should be less than start).

categories_blocked
Array of strings[ items non-empty ]

The kes of all classification categories to be blocked. If this property will be set, the property preset will be set to "custom" automatically.

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 too. The result of changing both properties at the same time is undefined.

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 disabled_duration too. The result of changing both properties at the same time is undefined.

domains_allowed
Array of strings[ items non-empty ]

A list with domain names that will never be blocked, regardless of other filtering settings in the profile.

domains_blocked
Array of strings[ items non-empty ]

A list with domain names that will always be blocked, regardless of other filtering settings in the profile.

filter_content
boolean

Whether content-based filtering is enabled.

  • If this property will be set to false, the property preset will be set to the value "none" automatically.
  • If this property will be set to true, the previous value of the property preset will be restored.
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.

platforms_allowed
Array of strings[ items non-empty ]

The kes of all classification platforms to be allowed independently from category settings in the property categories_blocked. If this property will be set, the property preset will be set to "custom" automatically.

platforms_blocked
Array of strings[ items non-empty ]

The kes of all classification platforms to be blocked independently from category settings in the property categories_blocked. If this property will be set, the property preset will be set to "custom" automatically.

preset
string non-empty

The key of a predefined set of classification items, or the special key "custom" for a user-defined set, or the special key "none", if content filtering is disabled (property filter_content is false).

  • If this property will be set to an existing preset list, the properties platforms_allowed, platforms_blocked, categories_blocked, and safesearch_enabled will be updated automatically.
  • If this property will be set to the value "none", the property filter_content will be set to false automatically (no content filtering, no domain filtering).
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).

safesearch_enabled
Array of strings[ items non-empty ]

The kes of all safe-search engines to be enabled. If this property will be set, the property preset will be set to "custom" 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).

Responses

Request samples

Content type
application/json
application/json
application/x-www-form-urlencoded
{
  • "avatar_version": 0,
  • "bedtime_weekend": {
    },
  • "bedtime_workdays": {
    },
  • "categories_blocked": [
    ],
  • "disabled_duration": 0,
  • "disabled_until": 0,
  • "domains_allowed": [
    ],
  • "domains_blocked": [
    ],
  • "filter_content": true,
  • "filter_security": true,
  • "homework_schedule": {
    },
  • "name": "string",
  • "offtime_schedules": [
    ],
  • "pause_internet": true,
  • "platforms_allowed": [
    ],
  • "platforms_blocked": [
    ],
  • "preset": "string",
  • "profile_id": 0,
  • "safesearch_enabled": [
    ],
  • "user_id": "string"
}

Response samples

Content type
application/json
{
  • "avatar_version": 0,
  • "bedtime_weekend": {
    },
  • "bedtime_workdays": {
    },
  • "categories_blocked": [
    ],
  • "disabled_duration": 0,
  • "disabled_until": 0,
  • "domains_allowed": [
    ],
  • "domains_blocked": [
    ],
  • "filter_content": true,
  • "filter_security": true,
  • "homework_schedule": {
    },
  • "name": "string",
  • "offtime_schedules": [
    ],
  • "pause_internet": true,
  • "platforms_allowed": [
    ],
  • "platforms_blocked": [
    ],
  • "preset": "string",
  • "profile_id": 0,
  • "safesearch_enabled": [
    ],
  • "user_id": "string"
}

Create a new filter profile in the user account.

Creates a new filter profile in the user account with the identifier specified in the URL. The filter profile must not exist yet.

path Parameters
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.

query Parameters
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 profile_id with the profile identifier only. This can be used to reduce network traffic, and allows the server to perform optimizations in specific cases.

Request Body schema:
application/json
application/json
application/x-www-form-urlencoded

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.

Adding domains into the domains_allowed string array property will remove them automatically from the domains_blocked string array property, and vice versa.

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).

    • Example: Use {"homework_schedule":{"enabled":true}} to enable the homework time schedule.
    • Example: Use {"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.

    • Example: Use {"homework_schedule.enabled":true} (or homework_schedule.enabled=true for application/www-form-urlencoded body data) to enable the homework time schedule.
    • Example: Use {"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.

    • Example: Use {"domains_allowed":{"insert":["example.org","example.com"],"delete":"example.net"}} to patch the domains_allowed string array.
    • Example: Use {"homework_schedule":{"categories_blocked":{"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.

    • Example: Use {"homework_schedule.categories_blocked":{"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.

    • Example: Use {"domains_allowed.insert":["example.org","example.com"],"domains_allowed.delete":"example.net"} to patch the domains_allowed string array.
    • Example: Use {"homework_schedule.categories_blocked.insert":"C1","homework_schedule.categories_blocked.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.

    • Example: Use {"domains_allowed":{"patch":{"example.org":true,"example.net":false}}} to patch the domains_allowed string array.
    • Example: Use {"homework_schedule":{"categories_blocked":{"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.

    • Example: Use {"homework_schedule.categories_blocked":{"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.

    • Example: Use {"domains_allowed.patch":{"example.org":true,"example.net":false}} to patch the domains_allowed string array.
    • Example: Use {"homework_schedule.categories_blocked.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).

    • Example: Use {"domains_allowed@example.org":true,"domains_allowed@example.net":false} to patch the domains_allowed string array.
    • Example: Use {"homework_schedule.categories_blocked@C1":true,"homework_schedule.categories_blocked@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 /user/{user_id}/profile/{profile_id}/avatar.

object

Bedtime settings in weekend nights (Friday to Saturday, and Saturday to Sunday). Only the keys fr and sa (Friday and Saturday) of the property days will have an effect. Changing the other weekday properties will not do anything. The time frame is intended to start at the respective day, and to end in the next day (property start should be in the evening, property end should be less than start).

object

Bedtime settings in nights before workdays (Sunday to Monday, ..., Thursday to Friday). Only the keys su, mo, tu, we, and th (Sunday to Thursday) of the property days will have an effect. Changing the other weekday properties will not do anything. The time frame is intended to start at the respective day, and to end in the next day (property start should be in the evening, property end should be less than start).

categories_blocked
Array of strings[ items non-empty ]

The kes of all classification categories to be blocked. If this property will be set, the property preset will be set to "custom" automatically.

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 too. The result of changing both properties at the same time is undefined.

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 disabled_duration too. The result of changing both properties at the same time is undefined.

domains_allowed
Array of strings[ items non-empty ]

A list with domain names that will never be blocked, regardless of other filtering settings in the profile.

domains_blocked
Array of strings[ items non-empty ]

A list with domain names that will always be blocked, regardless of other filtering settings in the profile.

filter_content
boolean

Whether content-based filtering is enabled.

  • If this property will be set to false, the property preset will be set to the value "none" automatically.
  • If this property will be set to true, the previous value of the property preset will be restored.
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.

platforms_allowed
Array of strings[ items non-empty ]

The kes of all classification platforms to be allowed independently from category settings in the property categories_blocked. If this property will be set, the property preset will be set to "custom" automatically.

platforms_blocked
Array of strings[ items non-empty ]

The kes of all classification platforms to be blocked independently from category settings in the property categories_blocked. If this property will be set, the property preset will be set to "custom" automatically.

preset
string non-empty

The key of a predefined set of classification items, or the special key "custom" for a user-defined set, or the special key "none", if content filtering is disabled (property filter_content is false).

  • If this property will be set to an existing preset list, the properties platforms_allowed, platforms_blocked, categories_blocked, and safesearch_enabled will be updated automatically.
  • If this property will be set to the value "none", the property filter_content will be set to false automatically (no content filtering, no domain filtering).
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).

safesearch_enabled
Array of strings[ items non-empty ]

The kes of all safe-search engines to be enabled. If this property will be set, the property preset will be set to "custom" 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).

Responses

Request samples

Content type
application/json
application/json
application/x-www-form-urlencoded
{
  • "avatar_version": 0,
  • "bedtime_weekend": {
    },
  • "bedtime_workdays": {
    },
  • "categories_blocked": [
    ],
  • "disabled_duration": 0,
  • "disabled_until": 0,
  • "domains_allowed": [
    ],
  • "domains_blocked": [
    ],
  • "filter_content": true,
  • "filter_security": true,
  • "homework_schedule": {
    },
  • "name": "string",
  • "offtime_schedules": [
    ],
  • "pause_internet": true,
  • "platforms_allowed": [
    ],
  • "platforms_blocked": [
    ],
  • "preset": "string",
  • "profile_id": 0,
  • "safesearch_enabled": [
    ],
  • "user_id": "string"
}

Response samples

Content type
application/json
{
  • "avatar_version": 0,
  • "bedtime_weekend": {
    },
  • "bedtime_workdays": {
    },
  • "categories_blocked": [
    ],
  • "disabled_duration": 0,
  • "disabled_until": 0,
  • "domains_allowed": [
    ],
  • "domains_blocked": [
    ],
  • "filter_content": true,
  • "filter_security": true,
  • "homework_schedule": {
    },
  • "name": "string",
  • "offtime_schedules": [
    ],
  • "pause_internet": true,
  • "platforms_allowed": [
    ],
  • "platforms_blocked": [
    ],
  • "preset": "string",
  • "profile_id": 0,
  • "safesearch_enabled": [
    ],
  • "user_id": "string"
}

Delete the avatar image from an existing filter profile.

Deletes the avatar image from an existing filter profile.

path Parameters
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.

Responses

Response samples

Content type
application/json
{
  • "deleted": true
}

Return the avatar image of an existing filter profile.

Returns the avatar image of an existing filter profile.

path Parameters
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.

Responses

Response samples

Content type
application/json
{
  • "error": "string"
}

Upload a new avatar image for an existing filter profile.

Uploads a new avatar image for an existing filter profile. An existing avatar image will be replaced.

path Parameters
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.

Request Body schema: image/*

The binary image data.

string <binary>

Responses

Response samples

Content type
application/json
{
  • "avatar_version": 1
}

Create a new offtime schedule in an existing filter profile.

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.

path Parameters
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.

Request Body schema:
application/json
application/json
application/x-www-form-urlencoded

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).

    • Example: Use {"days":{"fr":true}} to enable Friday in the offtime schedule.

  • Specify the properties to be modified with dot notation in the root object.

    • Example: Use {"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.

Responses

Request samples

Content type
application/json
application/json
application/x-www-form-urlencoded
{
  • "days": {
    },
  • "enabled": true,
  • "end": 86399,
  • "name": "string",
  • "start": 86399
}

Response samples

Content type
application/json
{
  • "days": {
    },
  • "enabled": true,
  • "end": 86399,
  • "name": "string",
  • "start": 86399
}

Delete an existing offtime schedule.

Deletes the settings of an existing offtime schedule. Deleting offtime schedules shrinks the array (following offtime schedules will decrease their array indexes).

path Parameters
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 offtime_schedules.

Responses

Response samples

Content type
application/json
{
  • "deleted": true
}

Return an existing offtime schedule.

Returns the settings of an existing offtime schedule.

path Parameters
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 offtime_schedules.

Responses

Response samples

Content type
application/json
{
  • "days": {
    },
  • "enabled": true,
  • "end": 86399,
  • "name": "string",
  • "start": 86399
}

Modify an existing offtime schedule.

Modifies the settings of an existing offtime schedule.

path Parameters
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 offtime_schedules.

Request Body schema:
application/json
application/json
application/x-www-form-urlencoded

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).

    • Example: Use {"days":{"fr":true}} to enable Friday in the offtime schedule.

  • Specify the properties to be modified with dot notation in the root object.

    • Example: Use {"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.

Responses

Request samples

Content type
application/json
application/json
application/x-www-form-urlencoded
{
  • "days": {
    },
  • "enabled": true,
  • "end": 86399,
  • "name": "string",
  • "start": 86399
}

Response samples

Content type
application/json
{
  • "days": {
    },
  • "enabled": true,
  • "end": 86399,
  • "name": "string",
  • "start": 86399
}

Devices

The device API to manage the user's registered devices.

Delete an existing device.

Deletes the settings of an existing device.

path Parameters
device_id
required
string non-empty

The unique identifier of a device (the EDNS client identifier of the device encoding its MAC address).

Responses

Response samples

Content type
application/json
{
  • "deleted": true
}

Return an existing device.

Returns the settings of an existing device.

path Parameters
device_id
required
string non-empty

The unique identifier of a device (the EDNS client identifier of the device encoding its MAC address).

Responses

Response samples

Content type
application/json
{
  • "created_ts": 0,
  • "device_id": "string",
  • "mac": "string",
  • "name": "string",
  • "name_auto": "string",
  • "notify": true,
  • "producer": "string",
  • "profile_id": 0,
  • "type": "phone",
  • "user_id": "string",
  • "visited": true
}

Modify an existing device.

Modifies the settings of an existing device.

path Parameters
device_id
required
string non-empty

The unique identifier of a device (the EDNS client identifier of the device encoding its MAC address).

query Parameters
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.

Request Body schema:
application/json
application/json
application/x-www-form-urlencoded

The properties to be changed for the device. Omitted properties will not be modified.

created_ts
integer >= 0

The Unix timestamp in seconds (UTC, zero is 1970-01-01 at midnight) of registration of the device in the PowerDNS filter platform.

device_id
string non-empty

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.

Responses

Request samples

Content type
application/json
application/json
application/x-www-form-urlencoded
{
  • "created_ts": 0,
  • "device_id": "string",
  • "mac": "string",
  • "name": "string",
  • "name_auto": "string",
  • "notify": true,
  • "producer": "string",
  • "profile_id": 0,
  • "type": "phone",
  • "user_id": "string",
  • "visited": true
}

Response samples

Content type
application/json
{
  • "created_ts": 0,
  • "device_id": "string",
  • "mac": "string",
  • "name": "string",
  • "name_auto": "string",
  • "notify": true,
  • "producer": "string",
  • "profile_id": 0,
  • "type": "phone",
  • "user_id": "string",
  • "visited": true
}

Delete all existing devices.

Deletes the settings of all existing devices.

Responses

Response samples

Content type
application/json
{
  • "deleted": 0
}

Return all existing devices.

Returns the settings of all existing devices.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Messages

The message API to manage the user's registered notifications.

Delete an existing message.

Deletes an existing message.

path Parameters
msg_id
required
string non-empty

The unique identifier of a message.

Responses

Response samples

Content type
application/json
{
  • "deleted": true
}

Return an existing message.

Returns the contents of an existing message.

path Parameters
msg_id
required
string non-empty

The unique identifier of a message.

Responses

Response samples

Content type
application/json
{
  • "app": "string",
  • "broadcast": true,
  • "categories": [
    ],
  • "code": "info",
  • "context": "regular",
  • "device_id": "string",
  • "device_ip": "string",
  • "device_name": "string",
  • "device_type": "string",
  • "domain": "string",
  • "hidden": true,
  • "msg_id": "string",
  • "platforms": [
    ],
  • "severity": "low",
  • "text": "string",
  • "timestamp": 0,
  • "url": "string",
  • "user_id": "string"
}

Modify an existing message.

Modifies the contents of an existing message.

path Parameters
msg_id
required
string non-empty

The unique identifier of a message.

query Parameters
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.

Request Body schema:
application/json
application/json
application/x-www-form-urlencoded

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 keys of all classification categories that caused to block the request. This property is constant, it cannot be changed in an existing message.

code
string (MessageCode)
Enum: "info" "malware" "phishing" "botnet" "category" "domain" "new_device" "login_success" "login_failure" "login_suspicious"

The identifiers for different message types.

CodeDescription
infoGeneral information.
malwareThe request was blocked by the malware filter.
phishingThe request was blocked by the phishing filter.
botnetThe request was blocked by the botnet filter.
categoryThe request was blocked by a platform or category filter rule.
domainThe request was blocked by a domain filter rule.
new_deviceA new device has been detected by the PowerDNS filter platform.
login_successLogin into the middleware was successful.
login_failureLogin into the middleware has failed (e.g. wrong password).
login_suspiciousLogin into the middleware was successful, but the login is suspicious (e.g. unusual IP address).
context
string
Default: "regular"
Enum: "regular" "homework"

The filter context of the message. If set to "homework", a request has been blocked by a homework schedule. 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.

device_name
string

The name of the new device. This property will only be set to a non-empty string when the message code is new_device.

device_type
string

The type of the new device. This property will only be set to a non-empty string when the message code is new_device.

domain
string

The domain name extracted from the property url. This property is constant, it cannot be changed in an existing message.

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.

platforms
Array of strings[ items non-empty ]

The keys of all classification platforms that caused to block the request. 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 (UTC, zero is 1970-01-01 at midnight) 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 an empty string). 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.

Responses

Request samples

Content type
application/json
application/json
application/x-www-form-urlencoded
{
  • "app": "string",
  • "broadcast": true,
  • "categories": [
    ],
  • "code": "info",
  • "context": "regular",
  • "device_id": "string",
  • "device_ip": "string",
  • "device_name": "string",
  • "device_type": "string",
  • "domain": "string",
  • "hidden": true,
  • "msg_id": "string",
  • "platforms": [
    ],
  • "severity": "low",
  • "text": "string",
  • "timestamp": 0,
  • "url": "string",
  • "user_id": "string"
}

Response samples

Content type
application/json
{
  • "app": "string",
  • "broadcast": true,
  • "categories": [
    ],
  • "code": "info",
  • "context": "regular",
  • "device_id": "string",
  • "device_ip": "string",
  • "device_name": "string",
  • "device_type": "string",
  • "domain": "string",
  • "hidden": true,
  • "msg_id": "string",
  • "platforms": [
    ],
  • "severity": "low",
  • "text": "string",
  • "timestamp": 0,
  • "url": "string",
  • "user_id": "string"
}

Deletes all existing messages.

Deletes all messages of the user matching the specified filter criteria.

query Parameters
codes
Array of strings (MessageCode)
Items Enum: "info" "malware" "phishing" "botnet" "category" "domain" "new_device" "login_success" "login_failure" "login_suspicious"

The message codes to be included in the filtered message list (matching message property code). If omitted, messages will not be filtered by message code.

platforms
Array of strings (ClassificationKeyList) [ items non-empty ]

The keys of all classification platforms to be included in a filtered list (matching any entry of the property platforms). If omitted, the list will not be filtered by platform.

categories
Array of strings (ClassificationKeyList) [ items non-empty ]

The keys of all classification categories to be included in a filtered list (matching any entry of the property categories). If omitted, the list will not be filtered by category.

devices
Array of strings (DeviceIdList) [ items non-empty ]

The identifiers of all devices to be included in a filtered list (matching the property device_id). If omitted, the list will not be filtered by device identifier.

urls
Array of strings (DomainList) [ items non-empty ]

The URLs to be included in the filtered message list (matching any substring of message property url). If omitted, messages will not be filtered by URL.

age
integer >= 1

The maximum age of list entries to filter for, in seconds.

Responses

Response samples

Content type
application/json
{
  • "deleted": true
}

Return all existing messages.

Returns the contents of all messages of the user matching the specified filter criteria.

query Parameters
codes
Array of strings (MessageCode)
Items Enum: "info" "malware" "phishing" "botnet" "category" "domain" "new_device" "login_success" "login_failure" "login_suspicious"

The message codes to be included in the filtered message list (matching message property code). If omitted, messages will not be filtered by message code.

platforms
Array of strings (ClassificationKeyList) [ items non-empty ]

The keys of all classification platforms to be included in a filtered list (matching any entry of the property platforms). If omitted, the list will not be filtered by platform.

categories
Array of strings (ClassificationKeyList) [ items non-empty ]

The keys of all classification categories to be included in a filtered list (matching any entry of the property categories). If omitted, the list will not be filtered by category.

devices
Array of strings (DeviceIdList) [ items non-empty ]

The identifiers of all devices to be included in a filtered list (matching the property device_id). If omitted, the list will not be filtered by device identifier.

urls
Array of strings (DomainList) [ items non-empty ]

The URLs to be included in the filtered message list (matching any substring of message property url). If omitted, messages will not be filtered by URL.

age
integer >= 1

The maximum age of list entries to filter for, in seconds.

size
integer [ 1 .. 1000 ]
Default: 50

The size of a page to be returned from a result list (the maximum number of result elements to be returned from the entire list).

index
integer >= 0
Default: 0

The zero-based index of a page to be returned from a result list. If set to a positive integer, skips the specified number of pages in the result list. The size of a page will be determined with the query parameter size.

consume
boolean

If set to true, all existing messages will lose their "new" state (regardless of the passed filter options).

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Modify all existing messages.

Modifies the contents of all messages of the user matching the specified filter criteria.

query Parameters
codes
Array of strings (MessageCode)
Items Enum: "info" "malware" "phishing" "botnet" "category" "domain" "new_device" "login_success" "login_failure" "login_suspicious"

The message codes to be included in the filtered message list (matching message property code). If omitted, messages will not be filtered by message code.

platforms
Array of strings (ClassificationKeyList) [ items non-empty ]

The keys of all classification platforms to be included in a filtered list (matching any entry of the property platforms). If omitted, the list will not be filtered by platform.

categories
Array of strings (ClassificationKeyList) [ items non-empty ]

The keys of all classification categories to be included in a filtered list (matching any entry of the property categories). If omitted, the list will not be filtered by category.

devices
Array of strings (DeviceIdList) [ items non-empty ]

The identifiers of all devices to be included in a filtered list (matching the property device_id). If omitted, the list will not be filtered by device identifier.

urls
Array of strings (DomainList) [ items non-empty ]

The URLs to be included in the filtered message list (matching any substring of message property url). If omitted, messages will not be filtered by URL.

age
integer >= 1

The maximum age of list entries to filter for, in seconds.

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.

Request Body schema:
application/json
application/json
application/x-www-form-urlencoded

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 keys of all classification categories that caused to block the request. This property is constant, it cannot be changed in an existing message.

code
string (MessageCode)
Enum: "info" "malware" "phishing" "botnet" "category" "domain" "new_device" "login_success" "login_failure" "login_suspicious"

The identifiers for different message types.

CodeDescription
infoGeneral information.
malwareThe request was blocked by the malware filter.
phishingThe request was blocked by the phishing filter.
botnetThe request was blocked by the botnet filter.
categoryThe request was blocked by a platform or category filter rule.
domainThe request was blocked by a domain filter rule.
new_deviceA new device has been detected by the PowerDNS filter platform.
login_successLogin into the middleware was successful.
login_failureLogin into the middleware has failed (e.g. wrong password).
login_suspiciousLogin into the middleware was successful, but the login is suspicious (e.g. unusual IP address).
context
string
Default: "regular"
Enum: "regular" "homework"

The filter context of the message. If set to "homework", a request has been blocked by a homework schedule. 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.

device_name
string

The name of the new device. This property will only be set to a non-empty string when the message code is new_device.

device_type
string

The type of the new device. This property will only be set to a non-empty string when the message code is new_device.

domain
string

The domain name extracted from the property url. This property is constant, it cannot be changed in an existing message.

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.

platforms
Array of strings[ items non-empty ]

The keys of all classification platforms that caused to block the request. 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 (UTC, zero is 1970-01-01 at midnight) 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 an empty string). 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.

Responses

Request samples

Content type
application/json
application/json
application/x-www-form-urlencoded
{
  • "app": "string",
  • "broadcast": true,
  • "categories": [
    ],
  • "code": "info",
  • "context": "regular",
  • "device_id": "string",
  • "device_ip": "string",
  • "device_name": "string",
  • "device_type": "string",
  • "domain": "string",
  • "hidden": true,
  • "msg_id": "string",
  • "platforms": [
    ],
  • "severity": "low",
  • "text": "string",
  • "timestamp": 0,
  • "url": "string",
  • "user_id": "string"
}

Response samples

Content type
application/json
[
  • {
    }
]

Return the number of existing messages.

Returns the number of existing messages of the user (optionally matching the specified filter criteria).

query Parameters
codes
Array of strings (MessageCode)
Items Enum: "info" "malware" "phishing" "botnet" "category" "domain" "new_device" "login_success" "login_failure" "login_suspicious"

The message codes to be included in the filtered message list (matching message property code). If omitted, messages will not be filtered by message code.

platforms
Array of strings (ClassificationKeyList) [ items non-empty ]

The keys of all classification platforms to be included in a filtered list (matching any entry of the property platforms). If omitted, the list will not be filtered by platform.

categories
Array of strings (ClassificationKeyList) [ items non-empty ]

The keys of all classification categories to be included in a filtered list (matching any entry of the property categories). If omitted, the list will not be filtered by category.

devices
Array of strings (DeviceIdList) [ items non-empty ]

The identifiers of all devices to be included in a filtered list (matching the property device_id). If omitted, the list will not be filtered by device identifier.

urls
Array of strings (DomainList) [ items non-empty ]

The URLs to be included in the filtered message list (matching any substring of message property url). If omitted, messages will not be filtered by URL.

age
integer >= 1

The maximum age of list entries to filter for, in seconds.

Responses

Response samples

Content type
application/json
{
  • "count": 0
}

Return the number of new messages.

Returns the number of new messages of the user. Messages are considered to be new, if they have been arrived after the last call to GET /user/messages?consume=true.

Responses

Response samples

Content type
application/json
{
  • "count": 0
}

Return filter settings for all existing messages.

Returns the available filter settings for all existing messages of the user.

Responses

Response samples

Content type
application/json
{
  • "categories": [
    ],
  • "codes": [
    ],
  • "devices": [
    ],
  • "platforms": [
    ],
  • "urls": [
    ]
}

Notifications

The notification API to send new messages to the user.

Delete the push token of a mobile device.

Deletes the push token of a mobile device for the user.

Request Body schema:
application/json
application/json
application/x-www-form-urlencoded

The push token to be deleted.

type
required
string
Enum: "fcm" "apn"

The type specifier of the push service provider.

value
required
string

The value of the push token.

Responses

Request samples

Content type
application/json
application/json
application/x-www-form-urlencoded
{
  • "type": "fcm",
  • "value": "string"
}

Response samples

Content type
application/json
{
  • "deleted": true
}

Register the push token of a mobile device.

Registers the push token of a mobile device for the user.

Request Body schema:
application/json
application/json
application/x-www-form-urlencoded

The push token to be registered.

type
required
string
Enum: "fcm" "apn"

The type specifier of the push service provider.

value
required
string

The value of the push token.

Responses

Request samples

Content type
application/json
application/json
application/x-www-form-urlencoded
{
  • "type": "fcm",
  • "value": "string"
}

Response samples

Content type
application/json
{
  • "error": "string"
}

Security

The security report API to render security related incidents.

Retrieve security related incidents for this device.

query Parameters
from
integer >= 0

The Unix timestamp in seconds (UTC, zero is 1970-01-01 at midnight) for the beginning of the time range to filter a result list with elements containing a timestamp.

to
integer >= 0

The Unix timestamp in seconds (UTC, zero is 1970-01-01 at midnight) for the ending of the time range to filter a result list with elements containing a timestamp.

devices
Array of strings (DeviceIdList) [ items non-empty ]

The identifiers of all devices to be included in a filtered list (matching the property device_id). If omitted, the list will not be filtered by device identifier.

types
Array of strings (SecurityIncidentType)
Items Enum: "botnet" "phishing" "malware"

The incident types to be included in the filtered incident list (matching incident property type). If omitted, incidents will not be filtered by their type.

size
integer [ 1 .. 1000 ]
Default: 50

The size of a page to be returned from a result list (the maximum number of result elements to be returned from the entire list).

index
integer >= 0
Default: 0

The zero-based index of a page to be returned from a result list. If set to a positive integer, skips the specified number of pages in the result list. The size of a page will be determined with the query parameter size.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Combined information about the situation.

Contains a list of devices and in what activities they are involved in among some statistical data and a situation code. Omitting the to parameter will be interpreted as it having the value of now.

query Parameters
from
integer >= 0

The Unix timestamp in seconds (UTC, zero is 1970-01-01 at midnight) for the beginning of the time range to filter a result list with elements containing a timestamp.

to
integer >= 0

The Unix timestamp in seconds (UTC, zero is 1970-01-01 at midnight) for the ending of the time range to filter a result list with elements containing a timestamp.

Responses

Response samples

Content type
application/json
{
  • "blocked_by_category": [
    ],
  • "blocked_by_device": [
    ],
  • "blocked_by_platform": [
    ],
  • "blocked_by_type": [
    ],
  • "blocked_count": 0
}

Privacy

Privacy and personal data related resources.

Personal user data for compliance.

Returns all personal data stored for the user in the system.

Responses

Response samples

Content type
application/json
{
  • "devices": [
    ],
  • "mail_address": "string",
  • "offtime_schedules": [
    ],
  • "phone_number": "string",
  • "profiles": [
    ],
  • "user_id": "string"
}