API docs by Redocly

rportd HTTP(S) API (1.0.0)

Download OpenAPI specification:Download

License: MIT

To run API, use --api-addr=yourserver:3000 CLI argument or enable it in config file

Generate auth token. Requires HTTP-basic authorization..

  • If 2FA is disabled: returns authorization JWT token.
  • If 2FA is enabled: triggers sending 2FA token to the user. 2fa token can be further verified using /verify-2fa endpoint. Requires the user to have a valid two_fa_send_to delivery option
  • If TotP is enabled, it returns a login token, which should be used to call /verify-2fa endpoint and also to create and read a totp secret for the first time (see /me/totp-secret)
  • If Rport Plus OAuth is enabled, then this API will be disabled and a 403 status response will be returned. Login using the /auth/provider and /auth/ext/settings or /auth/ext/settings/device endpoints instead.
Authorizations:
bearer_authbasic_auth
query Parameters
token-lifetime
integer <= 7776000
Default: 600

initial lifetime of JWT token in seconds. Max value is 90 days. Default: 10 min

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Generate auth token. Requires username and password in request body

If 2FA is disabled: returns authorization JWT token.

If 2FA is enabled: triggers sending 2FA token to the user. 2fa token can be further verified using /verify-2fa endpoint. Requires the user to have a valid two_fa_send_to delivery option. username and password should be provided in request body either in JSON either in x-www-formurlencoded format.

If fields username, password and new_password are provided: a new password will be set for the user, the user will be logged in and password_expired flag will be reset to false.

If time based one time passwords (TotP) are enabled (Google/Microsoft authenticator app), it returns a login token, which should be used to call /verify-2fa endpoint and also to create and totp secret key for the first time (see /me/totp-secret) To understand if TotP is enabled, delivery_method field will contain totp_authenticator_app value, that indicates the limited scope of the JWT token validity. If user has already a TotP secret key, the value of totp_key_status field will be 'pending' or 'exists' otherwise.

IfRport Plus OAuth is enabled, then this API will be disabled and a 403 status response will be returned. Login using the /auth/provider and /auth/ext/settings endpoints instead.

Authorizations:
bearer_authbasic_auth
query Parameters
token-lifetime
integer <= 7776000
Default: 600

initial lifetime of JWT token in seconds. Max value is 90 days. Default: 10 min

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Revoke token. Requires Bearer authorization provided

Authorizations:
bearer_authbasic_auth

Responses

Response samples

Content type
application/json
{
  • "errors": [
    ]
}

Verify 2FA token of the user. Requires enabled 2FA or time based one time code generation (totp_enabled=true).

Returns authorization JWT token if athe provided username and his 2fa token are valid. If totp_enabled is true, you should provide one time password as 2fa token. If both 2FA and TotP are disabled, this api will return 400.

Authorizations:
bearer_authbasic_auth
query Parameters
token-lifetime
integer <= 7776000
Default: 600

initial lifetime of JWT token in seconds. Max value is 90 days. Default: 10 min

Request Body schema: */*

Username and his 2FA token

username
string

Unique username

token
string

2FA or TotP options should be enabled. Requires JWT bearer token received from /login endpoint. 2FA token that was sent to the user by /login endpoints or generated by an Authenticator application. If totp_enabled is true, provide here one time password generated by an Authenticator app.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Auth

For more details https://oss.openrport.io

Get info on the configured authorization method

This API allows clients to determine how to login to Rport.

  • If the auth_provider is built-in then the regular OSS Rport login API can be used.

  • If the auth_provider is one of the Rport Plus OAuth providers (e.g. github, microsoft or google) then either the settings_uri or device_settings_uri endpoint must be must be queried for login related links/info. Which uri should be used depends on whether the api client is a web app or device style (e.g. cli) app.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Get auth info for a web app login

This API provides client with the necessary links to authorize a user and then perform an Rport login to obtain an Rport JWT Bearer token.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Get auth info for a device (or cli app) login

This API provides client with the necessary information for a user to authorize via an OAuth device flow. Typically the device flow is used with limited UI/input apps such as CLI apps.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Profile & Info

Profile and System Information

Return currently logged in user and groups the user belongs to

Authorizations:
bearer_authbasic_auth

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Update your own username, password or two_fa_send_to

Authorizations:
bearer_authbasic_auth
Request Body schema: */*

your own parameters that you would like to update

username
string

new username, empty if keep the same

password
string

new password, empty if keep the same

old_password
string

old password, required only on password change

two_fa_send_to
string

applicable only when 2FA is enabled, ignored otherwise. New two_fa_send_to, empty if keep the same

Responses

Response samples

Content type
application/json
{
  • "errors": [
    ]
}

Return a public ip address of a client who makes the request

Authorizations:
bearer_authbasic_auth

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Generate a new API token for user and return it

Authorizations:
bearer_authbasic_auth
Request Body schema: application/json:
scope
any
Enum: "read" "read+write" "clients-auth"

what this token is authorized for

expires_at
string <date-time>

date and time when this token will expire

Responses

Request samples

Content type
application/json:
{
  • "scope": "read",
  • "expires_at": "2019-08-24T14:15:22Z"
}

Response samples

Content type
application/json
{
  • "prefix": "string",
  • "name": "string",
  • "token": "b5507016-7da2-4777-a161-1e8042a6a377",
  • "created_at": "2019-08-24T14:15:22Z",
  • "expires_at": "2019-08-24T14:15:22Z",
  • "scope": "read"
}

Updates a specific user's API token

Authorizations:
bearer_authbasic_auth
Request Body schema: application/json:
prefix
string

token id prefix

name
string

token name, 250 chars max description, unique per user

expires_at
string <date-time>

date and time when this token will expire

Responses

Request samples

Content type
application/json:
{
  • "prefix": "string",
  • "name": "string",
  • "expires_at": "2019-08-24T14:15:22Z"
}

Response samples

Content type
application/json
{
  • "prefix": "string",
  • "expires_at": "2019-08-24T14:15:22Z"
}

Delete user's API token

Authorizations:
bearer_authbasic_auth
Request Body schema: application/json

token to be deleted

token_prefix
string

prefix of the token to be deleted

Responses

Request samples

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

Returns the user's list of Tokens

Authorizations:
bearer_authbasic_auth

Responses

Response samples

Content type
application/json
{
  • "prefix": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "expires_at": "2019-08-24T14:15:22Z",
  • "scope": "read"
}

Get information about rport server

Show health status, server version, etc

Authorizations:
bearer_authbasic_auth

Responses

Response samples

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

Read secret key and qr for an Authenticator app

Shows secret key and qr image in base64 format for an Authenticator app. Requires a token received from /verify-2fa endpoint.

Authorizations:
bearer_authbasic_auth

Responses

Response samples

Content type
application/json
{
  • "secret": "string",
  • "qr": "string"
}

Creates a new secret key for an Authenticator app

Creates a new secret key for an Authenticator app only for the first time! If another totP secret already exists for this user, an error will appear. Requires a valid JWT token received from the /login endpoint.

Authorizations:
bearer_authbasic_auth

Responses

Response samples

Content type
application/json
{
  • "secret": "string",
  • "qr": "string"
}

Delete time based one time secret key of the current user. Requires a token received from `/verify-2fa` endpoint.

Authorizations:
bearer_authbasic_auth

Responses

List all active and disconnected client connections. By default sorted by IDin asc order

Authorizations:
bearer_authbasic_auth
query Parameters
sort
string

Sort option -<field>(desc) or <field>(asc). <field> can be one of 'id', 'name', 'os', 'hostname', 'version'. For example, &sort=-name or &sort=hostname, etc

filter
string

Filter option filter[<FIELD>]=<VALUE> or filter[<FIELD>|<FIELD>]=<VALUE>,<VALUE> for OR conditions, alternatively: filter[<FIELD>]=or(<VALUE1>,<VALUE2>) for OR conditions, and filter[<FIELD>]=and(<VALUE1>,<VALUE2>) for AND conditions.

<FIELD> can be one of 'id', 'name', 'os', 'os_arch', 'os_family', 'os_kernel', 'os_full_name', 'os_version', 'os_virtualization_system', 'os_virtualization_role', 'cpu_family', 'cpu_model', 'cpu_model_name', 'cpu_vendor', 'num_cpus', 'timezone', 'hostname', 'ipv4', 'ipv6', 'tags', 'version', 'address' 'client_auth_id', 'connection_state', 'allowed_user_groups' and 'groups'.

You can use * wildcards to filter on any field and for partial matches. Text matching is case insensitive, filters can be combined together.
Examples:
filter[os_full_name]=Ubuntu 20.04
filter[os_full_name]=Ubuntu 20.04,Ubuntu 18.04
filter[os_full_name|os]=Ubuntu*
filter[*]=*Ubuntu*,*10.10.*,*Redhat*
filter[tags]=and(Linux,Datacenter 4)

fields[<RESOURCE>]
string

Fields to be returned. It should be provided in the format as fields[<RESOURCE>]=<FIELDS>, where <RESOURCE> is clients and <FIELDS> is a comma separated list of fields. Example: fields[clients]=id,name. If no fields are specified, only id, name and hostname will be returned.

page
integer

Pagination options page[limit] and page[offset] can be used to get more than the first page of results. Default limit is 50 and maximum is 500. The count property in meta shows the total number of results.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Returns all active tunnels of rport clients that current user has access to

Authorizations:
bearer_authbasic_auth

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Get client by id

Authorizations:
bearer_authbasic_auth
path Parameters
client_id
required
string

unique client ID

query Parameters
fields[<RESOURCE>]
string

Fields to be returned. It should be provided in the format as fields[<RESOURCE>]=<FIELDS>, where <RESOURCE> is clients and <FIELDS> is a comma separated list of fields. Example: fields[clients]=id,name. If no fields are specified, all will be returned.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Delete a disconnected client by id

Deletes a client by a given id. This API requires the current client to be offline. Returns 400 otherwise.

Authorizations:
bearer_authbasic_auth
path Parameters
client_id
required
string

unique client ID

Responses

Response samples

Content type
application/json
{
  • "errors": [
    ]
}

Updates Client's attributes

Updates client's attributes, they are persisted on the client if the client has configured and writeable attributes file

Authorizations:
bearer_authbasic_auth
path Parameters
client_id
required
string

Unique client ID

Request Body schema: application/json

value in the json format

tags
Array of strings
object

additional key-value metadata stored in client attributes file

Responses

Request samples

Content type
application/json
{
  • "tags": [
    ],
  • "labels": {
    }
}

Response samples

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

Shows Client's attributes

Authorizations:
bearer_authbasic_auth
path Parameters
client_id
required
string

Unique client ID

Responses

Response samples

Content type
application/json
{
  • "tags": [
    ],
  • "labels": {
    }
}

Request a new tunnel for an active client connection

Authorizations:
bearer_authbasic_auth
path Parameters
client_id
required
string

unique client id retrieved previously

query Parameters
local
string

local refers to the local port of the rport server to use for a new tunnel, e.g. '3390' or '0.0.0.0:3390'. If local is not specified, a random free server port will be selected automatically

remote
required
string

remote address endpoint, e.g. '3389', '0.0.0.0:22' or '192.168.178.1:80', etc

scheme
string

URI scheme to be used. For example, 'ssh', 'rdp', etc.

acl
string

ACL, IP v4 addresses or ranges who is allowed to use the tunnel (ipv6 is not supported yet). For example, '142.78.90.8,201.98.123.0/24'

check_port
string

A flag whether to check availability of a public port (remote). By default check is enabled. To disable it specify 'check_port=0'.

idle-timeout-minutes
integer [ 0 .. 10080 ]
Default: 5

Auto-close the tunnel after given period of inactivity in minutes. If not provided, default value is 5 minutes. This parameter should not be used with a non empty skip-idle-timeout parameter

auto-close
string

if > 0 then auto-close the tunnel after given duration. Valid time units are 's'(seconds), 'm'(minutes), 'h'(hours). For example, '20m', '1m30s', '1h', etc

protocol
string

Protocol for the tunnel. Can be tcp, udp or tcp+udp. Default is tcp.

skip-idle-timeout
integer

Disables the auto-close time of the tunnel (see idle-timeout-minutes parameter). The parameter should not be used with a non empty idle-timeout-minutes parameter

http_proxy
boolean

If true, triggers the start of a reverse proxy in front of the tunnel to handle ssl offloading. Default is false. http_proxy=true is only allowed in combination with scheme 'http' or 'https'

host_header
string

If http_proxy is true, you can specify a host name which will be added as header field Host to each outgoing proxy request. (virtual hosting on remote side)

auth_user
string

If present together with auth_password tunnels with an http reverse proxy (NoVNC, HTTP, HTTPS, RDP via browser) will require additional http basic auth on access. Requires http_proxy to be true.

auth_password
string

see auth_user

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Terminate a specified tunnel

Authorizations:
bearer_authbasic_auth
path Parameters
client_id
required
string

unique client id retrieved previously

tunnel_id
required
string

unique tunnel id retrieved previously

query Parameters
force
boolean

If true, terminate a tunnel even when it is still active.

Responses

Update a specified tunnel ACL

Authorizations:
bearer_authbasic_auth
path Parameters
client_id
required
string

unique client id retrieved previously

tunnel_id
required
string

unique tunnel id retrieved previously

Request Body schema: application/json:
acl
string

ACL, IP v4 addresses or ranges who is allowed to use the tunnel (ipv6 is not supported yet). For example, '142.78.90.8,201.98.123.0/24'

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "errors": [
    ]
}

Limit access to a current client to user groups. Require admin access

Authorizations:
bearer_authbasic_auth
path Parameters
client_id
required
string

unique client id retrieved previously

Request Body schema: */*
allowed_user_groups
Array of strings

list of user groups that are allowed to access this client. Empty means only Administrators can access it. You must always specify the entire list of allowed groups, partial updates are not supported

Responses

Response samples

Content type
application/json
{
  • "errors": [
    ]
}

Trigger updates status refresh on the client

Authorizations:
bearer_authbasic_auth
path Parameters
client_id
required
string

unique client id retrieved previously

Responses

Response samples

Content type
application/json
{
  • "errors": [
    ]
}

Return all client tags

Return a list of all client tags with belonging client IDs sorted by tag in asc order

Authorizations:
bearer_authbasic_auth
query Parameters
fields[<RESOURCE>]
string

Fields to be returned. It should be provided in the format as fields[<RESOURCE>]=<FIELDS>, where <RESOURCE> is client_tags and <FIELDS> is a comma separated list of fields. Example: fields[client_tags]=tag. If no fields are specified, all fields will be returned.

page
integer

Pagination options page[limit] and page[offset] can be used to get more than the first page of results. Default limit is 50 and maximum is 500. The count property in meta shows the total number of results.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

List stored tunnels

Authorizations:
bearer_authbasic_auth
path Parameters
client_id
required
string

Unique client ID

query Parameters
sort
string

Sort field to be used for sorting, the sorting direction is by default ASC. To change the direction add - to the sorting value e.g. -id. Allowed values are created_at, name, scheme, remote_ip, remote_port. You can use as many sort parameters as you want.

filter[<FIELD>]
string

Filter to find stored tunnels. It should be provided in the format as filter[<FIELD>]=<VALUE>, where <FIELD> is one of the values name, scheme, remote_ip, remote_port and <VALUE> is the search value, e.g. filter[scheme]=https will request only stored tunnels with scheme https. You can use as many filter parameters as you want. If you want to filter by multiple values e.g. find entries either for scheme = http or https you can use following filters filter[scheme]=http,https.

page
integer

Pagination options page[limit] and page[offset] can be used to get more than the first page of results. Default limit is 10 and maximum is 100. The count property in meta shows the total number of results.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Creates a new stored tunnel

Authorizations:
bearer_authbasic_auth
path Parameters
client_id
required
string

Unique client ID

Request Body schema: */*

value in the json format

name
string

Name of the stored tunnel

remote_ip
string

Remote for the stored tunnel

remote_port
integer

Remote port for the stored tunnel

public_port
integer

Public port for the stored tunnel

scheme
string

URI scheme for the stored tunnel

acl
string

ACL for the stored tunnel

further_options
object

Further options for the stored tunnel

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Updates an existing stored tunnel

Updates an existing stored tunnel by the provided id parameter. You need to provide all fields like those you used to create the stored tunnel. Partial updates are not supported. You can get id by using the listing API. You get the id also when you store a new value.

Authorizations:
bearer_authbasic_auth
path Parameters
client_id
required
string

Unique client ID

id
required
string

Unique script ID

Request Body schema: */*

value in the json format

name
string

Name of the stored tunnel

remote_ip
string

Remote for the stored tunnel

remote_port
integer

Remote port for the stored tunnel

public_port
integer

Public port for the stored tunnel

scheme
string

URI scheme for the stored tunnel

acl
string

ACL for the stored tunnel

further_options
object

Further options for the stored tunnel

Responses

Deletes an existing stored tunnel

Authorizations:
bearer_authbasic_auth
path Parameters
client_id
required
string

Unique client ID

id
required
string

Unique stored tunnel ID

Responses

Return all client groups

Return a list of all existing client groups sorted by ID in asc order

Authorizations:
bearer_authbasic_auth
query Parameters
sort
string

Sort option -<field>(desc) or <field>(asc). <field> can be one of 'id', 'description'.

filter
string

Filter option filter[<FIELD>]=<VALUE>. <FIELD> can be one of 'id', 'description'.

fields[<RESOURCE>]
string

Fields to be returned. It should be provided in the format as fields[<RESOURCE>]=<FIELDS>, where <RESOURCE> is client_groups and <FIELDS> is a comma separated list of fields. Example: fields[client_groups]=id,description. If no fields are specified, only id and description will be returned. Supported fields: id, description, num_clients, num_clients_connected

page
integer

Pagination options page[limit] and page[offset] can be used to get more than the first page of results. Default limit is 50 and maximum is 500. The count property in meta shows the total number of results.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Create a new client group. Require admin access

Create a new client group.

Authorizations:
bearer_authbasic_auth
Request Body schema: */*

Client group to create. Note: ClientGroup.client_ids field should not be set. It's read-only.

id
string

Client Group ID

description
string

Client Group description

client_ids
Array of strings

Read Only field. Shows active and disconnected clients that belong to this group.

object

Parameters that define what clients belong to a given client group.

Each parameter can be specified by:

  1. exact match of the property (ignoring case). For example, "client_id": ["test-win2019-tk01", "qa-lin-ubuntu16"]
  2. dynamic criteria using wildcards (ignoring case). For example, "os_family": ["linux*"]
  3. matches with logical operators (only for tags searching). For example, "tags": { "and": ["linux*", "SMP"] }

For more details please see https://oss.rport.io/get-started/client-groups/

allowed_user_groups
Array of strings

List of user groups that are allowed to access the client.

For more details please see https://oss.rport.io/get-started/permissions-model/

Responses

Response samples

Content type
application/json
{
  • "errors": [
    ]
}

Return a client group

Return a detailed info about a client group by a given id

Authorizations:
bearer_authbasic_auth
path Parameters
group_id
required
string

unique client group ID

query Parameters
fields[<RESOURCE>]
string

Fields to be returned. It should be provided in the format as fields[<RESOURCE>]=<FIELDS>, where <RESOURCE> is client_groups and <FIELDS> is a comma separated list of fields. Example: fields[client_groups]=id,description. If no fields are specified, all will be returned.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Save a client group. Require admin access

Update an existing client group or save a new client group

Authorizations:
bearer_authbasic_auth
path Parameters
group_id
required
string

unique client group ID

Request Body schema: */*

Client group to save. Note: ClientGroup.client_ids field should not be set.

id
string

Client Group ID

description
string

Client Group description

client_ids
Array of strings

Read Only field. Shows active and disconnected clients that belong to this group.

object

Parameters that define what clients belong to a given client group.

Each parameter can be specified by:

  1. exact match of the property (ignoring case). For example, "client_id": ["test-win2019-tk01", "qa-lin-ubuntu16"]
  2. dynamic criteria using wildcards (ignoring case). For example, "os_family": ["linux*"]
  3. matches with logical operators (only for tags searching). For example, "tags": { "and": ["linux*", "SMP"] }

For more details please see https://oss.rport.io/get-started/client-groups/

allowed_user_groups
Array of strings

List of user groups that are allowed to access the client.

For more details please see https://oss.rport.io/get-started/permissions-model/

Responses

Response samples

Content type
application/json
{
  • "errors": [
    ]
}

Delete a client group. Require admin access

Delete a client group by a given id

Authorizations:
bearer_authbasic_auth
path Parameters
group_id
required
string

unique client group ID

Responses

Response samples

Content type
application/json
{
  • "errors": [
    ]
}

Client Auth Credentials

For more details https://oss.openrport.io/docs/no03-client-auth.html

Return all rport clients authentication credentials. Sorted by ID in asc order. Require admin access

Authorizations:
bearer_authbasic_auth
query Parameters
filter
string

Filter option filter[id]=<VALUE>. You can use * wildcards for partial matches. Text matching is case insensitive. Examples: filter[id]=auth1234 filter[id]=auth*

page
integer

Pagination options page[limit] and page[offset] can be used to get more than the first page of results. Default limit is 50 and maximum is 500. The count property in meta shows the total number of results.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Add new rport client authentication credentials. Require admin access

Authorizations:
bearer_authbasic_auth
Request Body schema: */*

Client auth credentials to add

id
string

client auth ID

password
string

client auth password

Responses

Response samples

Content type
application/json
{
  • "errors": [
    ]
}

Get rport client authentication credentials. Require admin access

Authorizations:
bearer_authbasic_auth
path Parameters
client_auth_id
required
string

client auth ID

Responses

Delete rport client authentication credentials. Require admin access

Authorizations:
bearer_authbasic_auth
path Parameters
client_auth_id
required
string

client auth ID

query Parameters
force
boolean

If true, delete a client auth even when it has active/disconnected clients.

Responses

Return a short info about all client commands

Return a list of all running and finished commands sorted by finished time in desc order with running commands at the beginning

Authorizations:
bearer_authbasic_auth
path Parameters
client_id
required
string

unique client id retrieved previously

query Parameters
sort
string

Sort field to be used for sorting, the default sorting is by finished time in desc order. To change the direction add - to the sorting value e.g. -started_at. Allowed values are jid, started_at, finished_at, status, multi_job_id, created_by, schedule_id. You can use as many sort parameters as you want.

filter[<FIELD>]
string

Filter option filter[<field>] or filter[started_at][<op>]. <field> can be one of jid, created_by, started_at, finished_at, status, multi_job_id, schedule_id and <value> is the search value, e.g. filter[created_by]=admin will request only commands created by admin. You can use as many filter parameters as you want. Wildcards * are supported in the filter <value>. For started_at and finished_at filters you need to specify operation: gt, lt, since or until. If you want to filter by multiple values e.g. find entries either for created_by = admin or other you can use following filters filter[created_by]=admin,other.

page
integer

Pagination options page[limit] and page[offset] can be used to get more than the first page of results. Default limit is 100 and maximum is 1000. The count property in meta shows the total number of results.

fields[<RESOURCE>]
string

Fields to be returned. It should be provided in the format as fields[<RESOURCE>]=<FIELDS>, where <RESOURCE> is commands or result and <FIELDS> is a comma separated list of fields. Default is: fields[commands]=jid,status,finished_at&fields[result]=summary.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Execute a command by the rport client

NOTE: if command limitation is enabled by an rport client then a full path command can be required to use. See https://oss.rport.io/docs/no06-command-execution.html for more details

Authorizations:
bearer_authbasic_auth
path Parameters
client_id
required
string

unique client id retrieved previously

Request Body schema: */*

remote command to execute by the rport client

command
string

remote command to execute by the rport client. NOTE: if command limitation is enabled by an rport client then a full path command can be required to use. See https://oss.rport.io/docs/no06-command-execution.html for more details

interpreter
string
Enum: "cmd" "powershell" "tacoscript"

command interpreter to use to execute the command. If not set 'cmd' is used by default on Windows and /bin/sh on Linux

cwd
string

current working directory for the executable command

is_sudo
boolean

execute a command as sudo user

timeout_sec
integer

timeout in seconds to observe the command execution. If not set a default timeout (60 seconds) is used

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Return a detailed info about a specific client command

Return a detailed info about a command by given job id

Authorizations:
bearer_authbasic_auth
path Parameters
client_id
required
string

unique client id retrieved previously

job_id
required
string

unique job id retrieved previously

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Return a short info about all multi-client commands

Return a list of all running and finished commands sorted by started time in desc order

Authorizations:
bearer_authbasic_auth
query Parameters
sort
string

Sort field to be used for sorting, the default sorting is by started time in desc order. To change the direction add - to the sorting value e.g. -started_at. Allowed values are jid, started_at, created_by, schedule_id. You can use as many sort parameters as you want.

filter[<FIELD>]
string

Filter option filter[<field>] or filter[started_at][<op>]. <field> can be one of jid, created_by, started_at, schedule_id and <value> is the search value, e.g. filter[created_by]=admin will request only commands created by admin. You can use as many filter parameters as you want. For started_at filter you need to specify operation: gt, lt, since or until. If you want to filter by multiple values e.g. find entries either for created_by = admin or other you can use following filters filter[created_by]=admin,other.

page
integer

Pagination options page[limit] and page[offset] can be used to get more than the first page of results. Default limit is 100 and maximum is 1000. The count property in meta shows the total number of results.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Execute a command on multiple rport clients

NOTE: if command limitation is enabled by an rport client then a full path command can be required to use. See https://oss.rport.io/docs/no06-command-execution.html for more details

Authorizations:
bearer_authbasic_auth
Request Body schema: */*

properties and remote command to execute by rport clients

command
string

remote command to execute by rport clients. NOTE: if command limitation is enabled by an rport client then a full path command can be required to use. See https://oss.rport.io/docs/no06-command-execution.html for more details

client_ids
Array of strings

list of client IDs where to run the command. Min items is 2 if group_ids is not specified

group_ids
Array of strings

list of client group IDs. A command will be executed on all clients that belong to given group(s)

object (Tags)

list of client tags to target for execution, plus an operator either OR (for any matching tags) or AND (for all tags must match). Tags cannot be used in conjunction with client_ids or group_ids.

interpreter
string
Enum: "cmd" "powershell"

command interpreter to use to execute the command. Is applicable only for windows clients. If not set 'cmd' is used by default

timeout_sec
integer

timeout in seconds to observe the command execution on each client separately. If not set a default timeout (60 seconds) is used

execute_concurrently
boolean
Default: false

if true - execute the command concurrently on clients. If false - sequentially in order that is in 'client_ids'. By default is false

abort_on_error
boolean
Default: true

applicable only if 'execute_concurrently' is false. If true - abort the entire cycle if the execution fails on some client. By default is true

cwd
string

current working directory for an executable command

is_sudo
boolean

execute the command as a sudo user

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Return a detailed info about a specific multi-client command

Return a detailed info about a multi-client command by given id with child jobs as well

Authorizations:
bearer_authbasic_auth
path Parameters
job_id
required
string

unique multi job id retrieved previously

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Return a short info about all multi-client command jobs

Return a list of all running and finished jobs sorted by finished time in desc order with running commands at the beginning

Authorizations:
bearer_authbasic_auth
path Parameters
job_id
required
string

unique multi-client command id

query Parameters
sort
string

Sort field to be used for sorting, the default sorting is by finished time in desc order. To change the direction add - to the sorting value e.g. -started_at. Allowed values are jid, started_at, finished_at, status, client_id, created_by, schedule_id. You can use as many sort parameters as you want.

filter[<FIELD>]
string

Filter option filter[<field>] or filter[started_at][<op>]. <field> can be one of jid, created_by, started_at, finished_at, status, client_id, schedule_id and <value> is the search value, e.g. filter[created_by]=admin will request only commands created by admin. You can use as many filter parameters as you want. Wildcards * are supported in the filter <value>. For started_at and finished_at filters you need to specify operation: gt, lt, since or until. If you want to filter by multiple values e.g. find entries either for created_by = admin or other you can use following filters filter[created_by]=admin,other.

page
integer

Pagination options page[limit] and page[offset] can be used to get more than the first page of results. Default limit is 100 and maximum is 1000. The count property in meta shows the total number of results.

fields[<RESOURCE>]
string

Fields to be returned. It should be provided in the format as fields[<RESOURCE>]=<FIELDS>, where <RESOURCE> is commands or result and <FIELDS> is a comma separated list of fields. Default is: fields[commands]=jid,status,finished_at&fields[result]=summary.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Web Socket Connection to execute a remote command on rport client(s)

NOTE: swagger is not designed to document WebSocket API. This is a temporary solution. A new web socket is created for each new request to execute a remote command on rport client(s). Steps:

  1. To pass authentication - include "access_token" param into the url. The value is a jwt token that is created by 'login' API endpoint.
  2. Upgrades the current connection to Web Socket.
  3. Then server waits for an inbound message from UI client. It should be a JSON object ExecuteCmdRequest(see in 'Models') For example,
    {
 "command": "/usr/bin/whoami",
 "client_ids": [ "qa-lin-debian9", "qa-lin-debian10", "qa-lin-centos8", "qa-lin-ubuntu18", "qa-lin-ubuntu16" ],
 "group_ids": [ "group-1"],
 "timeout_sec": 30,
 "cwd": "/root",
 "execute_concurrently": true,
 "is_sudo": true
}
  4. Validates the inbound msg. If it fails - server sends an outbound JSON message ErrorPayload(see in 'Models') and closes the connection.
  5. Server sends a given command to rport client(s) to execute.
  6. Partial stdout and stderr messages are streamed with JSON message JobPartial (see in 'Models').
  7. As soon as the command finishes a final result from each rport client is sent with JSON message Job(see in 'Models'). The final result contains full stdout and stderr outputs. It can contain a non-empty 'error' field if server wasn't able to send the command to the rport client. Number of final outbound messages is expected to be as many as rport clients. Or less if it's not a concurrent mode and 'abort_on_error' is turned on.
  8. As soon as all rport clients send back the result - the connection is closed by server.
  9. Also, a current connection can be closed by UI client.

There is a simple UI for testing. Try it out on http://127.0.0.1:3000/api/v1/test/commands/ui.

Authorizations:
bearer_authbasic_auth
query Parameters
access_token
required
string

JWT token that is created by 'login' API endpoint. Required to pass the authentication.

Responses

Response samples

Content type
application/json
{ }

Return all users

Return a list of all existing users sorted by username in asc order. This API requires the current user to be member of group Administrators. Returns 403 otherwise. The Administrators group name is hardcoded and cannot be changed at the moment

Authorizations:
bearer_authbasic_auth

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Create a new user

Create a new user. This API requires the current user to be member of group Administrators. Returns 403 otherwise. The Administrators group name is hardcoded and cannot be changed at the moment

Authorizations:
bearer_authbasic_auth
Request Body schema: */*

User to create.

username
string

Username for the credentials pair

password
string

Password for the credentials pair

password_expired
boolean

Password expired flag. Setting this to true, sessions are invalidated and user is forced to create a new password on next login

groups
Array of strings

List of groups to which the current user belongs

two_fa_send_to
string

Holds either the email or the pushover token of the user. It's used to deliver 2FA token to user when 2FA is enabled

Responses

Response samples

Content type
application/json
{
  • "errors": [
    ]
}

Update a user identified by the provided id

Update an existing user. This API requires the current user to be member of group Administrators. Returns 403 otherwise. The Administrators group name is hardcoded and cannot be changed at the moment.

Authorizations:
bearer_authbasic_auth
path Parameters
user_id
required
string

unique user ID

Request Body schema: */*

User to update. Please note, that if you provide some key/values like username: login1, the not mentioned keys won't be changed, e.g. password

username
string

Username for the credentials pair

password
string

Password for the credentials pair

password_expired
boolean

Password expired flag. Setting this to true, sessions are invalidated and user is forced to create a new password on next login

groups
Array of strings

List of groups to which the current user belongs

two_fa_send_to
string

Holds either the email or the pushover token of the user. It's used to deliver 2FA token to user when 2FA is enabled

Responses

Response samples

Content type
application/json
{
  • "errors": [
    ]
}

Delete a user

Deletes a user by a given id. This API requires the current user to be member of group Administrators. Returns 403 otherwise. The Administrators group name is hardcoded and cannot be changed at the moment

Authorizations:
bearer_authbasic_auth
path Parameters
user_id
required
string

unique user ID

Responses

Response samples

Content type
application/json
{
  • "errors": [
    ]
}

Gets all existing user api sessions for user.

Gets all the API sessions for the user specified. This API requires the current user to be member of group Administrators. Returns 403 otherwise. The Administrators group name is hardcoded and cannot be changed at the moment

Authorizations:
bearer_authbasic_auth
path Parameters
user_id
required
string

unique user ID

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Delete all existing user api sessions for user.

Deletes all the API sessions for the user specified. This API requires the current user to be member of group Administrators. Returns 403 otherwise. The Administrators group name is hardcoded and cannot be changed at the moment

Authorizations:
bearer_authbasic_auth
path Parameters
user_id
required
string

unique user ID

Responses

Response samples

Content type
application/json
{
  • "errors": [
    ]
}

Delete existing user api session.

Deletes the API session with the session id specified. This API requires the current user to be member of group Administrators. Returns 403 otherwise. The Administrators group name is hardcoded and cannot be changed at the moment

Authorizations:
bearer_authbasic_auth
path Parameters
user_id
required
string

unique user ID

session_id
required
string

session ID

Responses

Response samples

Content type
application/json
{
  • "errors": [
    ]
}

Delete time based one time private key for the provided user. Requires a token received from `/verify-2fa` endpoint.

Deletes private key for an Authenticator app. This API requires the current user to be member of group Administrators. Returns 403 otherwise. The Administrators group name is hardcoded and cannot be changed at the moment

Authorizations:
bearer_authbasic_auth
path Parameters
user_id
required
string

unique user ID

Responses

Response samples

Content type
application/json
{
  • "errors": [
    ]
}

OAuth / Login

Login with OAuth

  • This API is only enabled if the Rport Plus plugin is loaded and running. For more information, see Rport Plus.

  • It allows an authorization code (code) returned by an OAuth provider callback to be used to login to RPort and obtain an Rport Authorization JWT Token. The state parameter also received in the callback must also be provided and will be validated by the Rport server.

  • Note that security will be increased if clients verify that the state parameter returned in the callback matches the state parameter supplied initially as part of the OAuth authorize url. To obtain an authorize url, the Rport /auth/ext/settings endpoint must be called. It will return two additional APIs that can be used to perform OAuth based logins.

query Parameters
code
string

the authorization code received via the OAuth provider callback

state
string

the state received via the OAuth provider callback

token-lifetime
integer <= 7776000
Default: 600

initial lifetime of JWT token in seconds. Max value is 90 days. Default: 10 min

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Device Login with OAuth

  • This API is only enabled if the Rport Plus plugin is loaded and running. For more information, see Rport Plus.

  • Before this API can be called, the api client must have previously called the /auth/ext/settings/device endpoint and presented the returned verification_uri and user_code to the user. The user is then responsible for proceeding independently to the verification_uri page and entering the user_code to authorize the api client for use with Rport.

  • Once the user is authorized then this API call will return an Rport authentication token which will be stored in the config.json. The user will not need to authenticate again until the Rport token expires.

  • If the user has not authorized yet, then an error will be returned indicating that the authorization is authorization_pending. The api client must wait for the interval period (in seconds) after which they may try to login again. If the api client retries too quickly then the OAuth provider will rate limit the client and a slow_down error message will be returned.

  • Only the authorization_pending and slow_down error messages are soft errors that can be retried. The api client should abort the authorization on receiving any other errors.

  • NOTE: Some OAuth providers return http error status codes while others always return 200. If the response is 200, then the api client should still check the error value in the response for non-empty text. If non- empty then there is an error to be handled.

query Parameters
device_code
string

the device_code received via the OAuth device settings API

token-lifetime
integer <= 7776000
Default: 600

initial lifetime of JWT token in seconds. Max value is 90 days. Default: 10 min

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Scripts

Execute a script by a rport client.

Rport server will copy script contents to a temp folder on an rport client. Then it will implicitly execute shell script as a command e.g. sh /tmp/script.sh. NOTE: if command limitation is enabled by an rport client then it should allow execution commands like sh script.sh or cmd script.bat or powershell -executionpolicy bypass -file script.ps1. See https://oss.rport.io/docs/no06-command-execution.html#securing-your-environment for more details

Authorizations:
bearer_authbasic_auth
path Parameters
client_id
required
string

unique client id retrieved previously

Request Body schema: application/json

script to execute by the rport client, the format depends on the client's OS

script
string

base64 encoded script which should be executed on a remote client

interpreter
string
Enum: "cmd" "powershell" "tacoscript"

command interpreter to use to execute the script. If not set 'cmd' is used by default on Windows and /bin/sh on Linux. For tacoscript interpreter you should install tacoscript binary from here: https://github.com/realvnc-labs/tacoscript#installation. It should also be available in the system path. Additionally, you can use interpreter aliases or full absolute paths to an interpreter of your choice (see https://oss.rport.io/docs/no14-scripts.html#scripts-execution for details).

cwd
string

current working directory for the executable script

is_sudo
boolean

execute a command as sudo user, applicable only for Linux systems

timeout_sec
integer

timeout in seconds to observe the script execution. If not set a default timeout (60 seconds) is used

Responses

Request samples

Content type
application/json
{
  • "script": "string",
  • "interpreter": "cmd",
  • "cwd": "string",
  • "is_sudo": true,
  • "timeout_sec": 0
}

Execute a script on multiple rport clients

This API executes the provided script on multiple clients similar to the command execution

Authorizations:
bearer_authbasic_auth
Request Body schema: */*

properties and remote command to execute by rport clients

object (ExecuteScriptRequest)

Request that contains a remote script to execute by rport client(s) and other related properties

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Web Socket Connection to execute scripts on rport client(s)

NOTE: swagger is not designed to document WebSocket API. This is a temporary solution. A new web socket is created for each new request to execute a script on rport client(s). Steps:

  1. To pass authentication - include "access_token" param into the url. The value is a jwt token that is created by 'login' API endpoint.
  2. Upgrades the current connection to Web Socket.
  3. Then server waits for an inbound script message from UI client. It should be a JSON object ExecuteScriptRequest(see in 'Models'): For example,
    {
  "script": "Y2QgL1VzZXJzL2JyZWF0aGJhdGgvc3NsCmxzIC1sYQpjZCBnb2tleQpjYXQgTElDRU5TRQ==",
  "client_ids": [ "qa-lin-debian9", "qa-lin-debian10", "qa-lin-centos8", "qa-lin-ubuntu18", "qa-lin-ubuntu16" ],
  "group_ids": [ "group-1"],
  "timeout_sec": 30,
  "cwd": "/users/root",
  "execute_concurrently": true,
  "is_sudo": true
}
  4. Rport server will create the provided script as a shell script file in the target client(s) (e.g. /tmp/f68a779d-1d46-414a-b165-d8d2df5f348c.sh or f68a779d-1d46-414a-b165-d8d2df5f348.ps1). Then it will run this script as a regular command e.g. sh /tmp/f68a779d-1d46-414a-b165-d8d2df5f348c.sh If it fails, the server sends an outbound JSON message ErrorPayload(see in 'Models') and closes the connection. The temp script will be deleted anyway.
  5. Partial stdout and stderr messages are streamed with JSON message JobPartial (see in 'Models').
  6. As soon as the script finishes a final result from each rport client is sent with JSON message Job(see in 'Models'). The final result contains full stdout and stderr outputs. It can contain a non-empty 'error' field if server wasn't able to send the command to the rport client. Number of final outbound messages is expected to be as many as rport clients. Or less if it's not a concurrent mode and 'abort_on_error' is turned on.
  7. As soon as all rport clients send back the result - the connection is closed by server.
  8. Also, a current connection can be closed by UI client.

There is a simple UI for testing. Try it out on http://127.0.0.1:3000/api/v1/test/scripts/ui. You can enable this api by setting enable_ws_test_endpoints=true in the configuration file.

Authorizations:
bearer_authbasic_auth
query Parameters
access_token
required
string

JWT token that is created by 'login' API endpoint. Required to pass the authentication.

Responses

Response samples

Content type
application/json
{ }

Upload

Web Socket Connection to track upload process on clients

NOTE: swagger is not designed to document WebSocket API. This is a temporary solution.

The web socket API tracks uploads for all clients and all requests. Steps:

  1. To pass authentication - include "access_token" param into the url. The value is a jwt token that is created by 'login' API endpoint.
  2. Upgrades the current connection to Web Socket.
  3. Once the conneciton is open, all uploads to the clients can be tracked through it 4. Server receives an upload request, stores a file in a temp location and sends this information to all provided clients. 5. Clients will establish an sftp connection on top of the existing ssh connection and will download file from the servers temp folder and store it in its own temp folder 6. After download success, client will move the uploaded file from the temp to the desired path and perform chmod/chown operations if needed 7. The result (success/failure/partial failure/ignore) will be reported to the server through the SSH connection 8. The Rport server will send the client upload results to all open websocket connections 9. The websocket connection will stay open till client closes it There is a simple UI for testing. Try it out http://127.0.0.1:3000/api/v1/test/uploads/ui. You can enable this api by setting enable_ws_test_endpoints=true in the configuration file
Authorizations:
bearer_authbasic_auth
query Parameters
access_token
required
string

JWT token that is created by 'login' API endpoint. Required to pass the authentication.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Upload file

Handles file uploads as a multipart/form-data.

  • Files are stored on the rport server in a temporary location.
  • Then all specified clients download them by sftp protocol to a temp location as well.
  • If download was successful, clients move the temp file to the destination path.
Authorizations:
bearer_authbasic_auth
Request Body schema: multipart/form-data
upload
required
string <binary>

The file to upload

client_id
required
string

Client ID where the file should be placed. You can repeat 'client' parameter to indicate multiple clients

group_id
string

ID of a client group where the file should be placed. You can repeat 'group_id' parameter to indicate multiple groups

object (Tags)

list of client tags to target for execution, plus an operator either OR (for any matching tags) or AND (for all tags must match). Tags cannot be used in conjunction with client_ids or group_ids.

dest
required
string

Absolute path with the file name on the client where the file should be placed

force
string

If true, rport client will overwrite destination file if it exists or fail otherwise. You can provide values like true or 1 or on to enable this flag

sync
string

If true and the destination file exists, rport client will compare md5 checksum of the provided file with the destination file and will overwrite it if it's not matching. On Unix it will also compare file mode, owner and group of the existing file with the provided values and if they don't match, rport client will execute chmod/chown operations on the destination path. if false or file doesn't exists, the provided file will be copied to the destination.

mode
string

For Unix only, indicates the desired file mode of the target file on the client. If the file doesn't exist, it will be created with the provided mode. If file exists (and sync is true), rport client will run chmod operation with the provided file mode.

user
string

For Unix only, indicates the desired owner name the target file on the client. The uploaded file will be created with the default owner in a temp folder. If user is not empty, rport client will perform chown operation on the temp file. Then it will be moved to the target path Please make sure that the provided user exists on the client. Since changing owner of a file requires sudo rights, the rport client user should have the necessary permissions to chown and move file to the target location.

group
string

For Unix only, indicates the group name the target file on the client. The uploaded file will be created with the default group in a temp folder. Then rport client will chown the temp file with the provided group name. Then it will be moved to the target path. Please make sure that the provided group exists on the client. Since changing group of a file requires sudo rights, the rport client user should have the necessary permissions to chown and move file to the target location.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

User Groups

List user groups

Authorizations:
bearer_authbasic_auth

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Get user group

Authorizations:
bearer_authbasic_auth
path Parameters
name
required
string

group name

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Update user group

Authorizations:
bearer_authbasic_auth
path Parameters
name
required
string

group name

Request Body schema: application/json
object

permissions with boolean values

object

restriction with values

object

command restrictions with values

Responses

Request samples

Content type
application/json
{
  • "permissions": {
    },
  • "tunnels_restricted": {
    },
  • "commands_restricted": {
    }
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Delete user group

Delete user gruop, any member users will be removed from the group.

Authorizations:
bearer_authbasic_auth
path Parameters
name
required
string

group name

Responses

Response samples

Content type
application/json
{
  • "errors": [
    ]
}

Vault

Get status of RPort vault

Returns status information about the Rport vault.

Authorizations:
bearer_authbasic_auth

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Read or find vault entries

Reads all vault entries or find some based on the input parameters

Authorizations:
bearer_authbasic_auth
query Parameters
sort
string

Sort field to be used for values, the sorting direction is by default ASC. To change the direction add - to the sorting value e.g. -id. Allowed values are id, client_id, created_by, created_at, key. You can use as many sort parameters as you want.

filter[<FIELD>]
string

Filter to find vault entries. It should be provided in the format as filter[<FIELD>]=<VALUE>, where <FIELD> is one of the values id, client_id, created_by, created_at, key and <VALUE> is the search value, e.g. filter[created_by]=admin will request only vault entries created by admin. You can use as many filter parameters as you want. If you want to filter by multiple values e.g. find entries either for client_id = client1 or client2 you can use following filters filter[client_id]=client1,client2 Wildcards * are supported in the filter <value>.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Creates a new vault entry

Creates a new entry in vault with the encrypted value field. If another entry with the same key and client id combination exists, an error will be returned.

Authorizations:
bearer_authbasic_auth
Request Body schema: */*

value in the json format

client_id
string

Used to tie a document to a specific client where 0 means the document can be accessed from any client.

required_group
string

if filled, users not belonging to this group are not allowed to store or read the decrypted value

key
string

[required] some string to identify the document

value
string

[required] value represents the encrypted body of a document. It should be provided as a plain text

type
string
Enum: "text" "secret" "markdown" "string"

[required] Type of the secret value

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Read a decrypted vault value

Reads a vault entry with a decrypted value field. If required_group value of the stored vault entry is not emtpy, only users of this group can read this value.

Authorizations:
bearer_authbasic_auth
path Parameters
id
required
integer

Unique vault entry ID

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Updates an existing vault entry

Updates an existing vault entry by the provided id parameter. If required_group value of the stored vault entry is not empty, only users of this group can change this value. You need to provide all fields like those you used to create a vault entry. Partial updates are not supported. You can get id it by using the listing API. You get the id also when you store a new value.

Authorizations:
bearer_authbasic_auth
path Parameters
id
required
integer

Unique vault entry ID

Request Body schema: */*

value in the json format

client_id
string

Used to tie a document to a specific client where 0 means the document can be accessed from any client.

required_group
string

if filled, users not belonging to this group are not allowed to store or read the decrypted value

key
string

[required] some string to identify the document

value
string

[required] value represents the encrypted body of a document. It should be provided as a plain text

type
string
Enum: "text" "secret" "markdown" "string"

[required] Type of the secret value

Responses

Deletes an existing vault entry

Delete a vault entry by the provided id parameter. If required_group value of the stored vault entry is not empty, only users of this group can delete this value.

Authorizations:
bearer_authbasic_auth
path Parameters
id
required
integer

Unique vault entry ID

Responses

Initialize vault

Initializes vault database and stores password for further requests. This API requires the current user to be member of group Administrators. Returns 403 otherwise. The Administrators group name is hardcoded and cannot be changed at the moment

Authorizations:
bearer_authbasic_auth
Request Body schema: */*

Password to unlock the vault

password
string

A string of printed symbols 32 and 256 bits long

Responses

Response samples

Content type
application/json
{
  • "errors": [
    ]
}

Unlock vault

Unlocks vault to make it functional. If vault is locked, it won't accept any API requests. This API requires the current user to be member of group Administrators. Returns 403 otherwise. The Administrators group name is hardcoded and cannot be changed at the moment

Authorizations:
bearer_authbasic_auth
Request Body schema: */*

Password to unlock the vault. It should be the same password, which was provided when the vault was initialized.

password
string

A string of printed symbols 32 and 256 bits long

Responses

Response samples

Content type
application/json
{
  • "errors": [
    ]
}

Locks vault

Locks vault and delets it's password from server's memory. This API requires the current user to be member of group Administrators. Returns 403 otherwise. The Administrators group name is hardcoded and cannot be changed at the moment

Authorizations:
bearer_authbasic_auth

Responses

Response samples

Content type
application/json
{
  • "errors": [
    ]
}

Library

Read or find scripts

Reads all scripts or find some based on the input parameters

Authorizations:
bearer_authbasic_auth
query Parameters
sort
string

Sort field to be used for values, the sorting direction is by default ASC. To change the direction add - to the sorting value e.g. -id. All fields are allowed. You can use as many sort parameters as you want.

filter[<FIELD>]
string

Filter to find scripts. It should be provided in the format as filter[<FIELD>]=<VALUE>, where <FIELD> is one of the fields and <VALUE> is the search value, e.g. filter[created_by]=admin will request only scripts created by admin. You can use as many filter parameters as you want. You can use wildcards *. If you want to filter by multiple values e.g. find entries either for name = script1 or script2 you can use following filters filter[name]=script1,script2. Wildcards * are supported in the filter <value>.

fields[<RESOURCE>]
string

Fields to be returned. It should be provided in the format as fields[<RESOURCE>]=<FIELDS>, where <RESOURCE> is scripts and <FIELDS> is a comma separated list of fields. Example: fields[scripts]=id,name. If no fields are specified, all will be returned.

page
integer

Pagination options page[limit] and page[offset] can be used to get more than the first page of results. Default limit is 20 and maximum is 100. The count property in meta shows the total number of results.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Creates a new script

Creates a new script. If another entry with the same name exists, an error will be returned.

Authorizations:
bearer_authbasic_auth
Request Body schema: */*

value in the json format

name
string

[required] User-friendly name of a script

script
string

[required] text of the script

interpreter
string

how will the script be executed on the client, e.g. /bin/sh, cmd.exe, powershell, tacoscript

cwd
string

current working directory, where the script should be executed

is_sudo
boolean

if true, this script will be executed as a sudo user

tags
Array of strings

List of tags for the script

timeout_sec
integer

Timout of the script in seconds

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Read a script

Reads a script by the provided ID

Authorizations:
bearer_authbasic_auth
path Parameters
id
required
string

Unique script ID

query Parameters
fields[<RESOURCE>]
string

Fields to be returned. It should be provided in the format as fields[<RESOURCE>]=<FIELDS>, where <RESOURCE> is scripts and <FIELDS> is a comma separated list of fields. Example: fields[scripts]=id,name. If no fields are specified, all will be returned.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Updates an existing script

Updates an existing script by the provided id parameter. You need to provide all fields like those you used to create a script. Partial updates are not supported. You can get id by using the listing API. You get the id also when you store a new value.

Authorizations:
bearer_authbasic_auth
path Parameters
id
required
string

Unique script ID

Request Body schema: */*

value in the json format

name
string

[required] User-friendly name of a script

script
string

[required] text of the script

interpreter
string

how will the script be executed on the client, e.g. /bin/sh, cmd.exe, powershell, tacoscript

cwd
string

current working directory, where the script should be executed

is_sudo
boolean

if true, this script will be executed as a sudo user

tags
Array of strings

List of tags for the script

timeout_sec
integer

Timout of the script in seconds

Responses

Deletes an existing script

Delete a script by the provided id parameter.

Authorizations:
bearer_authbasic_auth
path Parameters
id
required
string

Unique script ID

Responses

List commands

Reads all commands or find some based on the input parameters

Authorizations:
bearer_authbasic_auth
query Parameters
sort
string

Sort field to be used for values, the sorting direction is by default ASC. To change the direction add - to the sorting value e.g. -id. All fields are allowed. You can use as many sort parameters as you want.

filter[<FIELD>]
string

Filter to find commands. It should be provided in the format as filter[<FIELD>]=<VALUE>, where <FIELD> is one of the fields and <VALUE> is the search value, e.g. filter[created_by]=admin will request only commands created by admin. You can use as many filter parameters as you want. You can use wildcard *. If you want to filter by multiple values e.g. find entries either for name = command1 or command2 you can use following filters filter[name]=command1,command2.

fields[<RESOURCE>]
string

Fields to be returned. It should be provided in the format as fields[<RESOURCE>]=<FIELDS>, where <RESOURCE> is comamnds and <FIELDS> is a comma separated list of fields. Example: fields[commands]=id,name. If no fields are specified, all will be returned.

page
integer

Pagination options page[limit] and page[offset] can be used to get more than the first page of results. Default limit is 20 and maximum is 100. The count property in meta shows the total number of results.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Creates a new command

Creates a new command. If another entry with the same name exists, an error will be returned.

Authorizations:
bearer_authbasic_auth
Request Body schema: */*

value in the json format

name
string

[required] User-friendly name of a commend

script
string

[required] text of the command

tags
Array of strings

List of tags for the script

timeout_sec
integer

Timout of the command in seconds

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Read a command

Reads a command by the provided ID

Authorizations:
bearer_authbasic_auth
path Parameters
id
required
string

Unique command ID

query Parameters
fields[<RESOURCE>]
string

Fields to be returned. It should be provided in the format as fields[<RESOURCE>]=<FIELDS>, where <RESOURCE> is commands and <FIELDS> is a comma separated list of fields. Example: fields[commands]=id,name. If no fields are specified, all will be returned.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Updates an existing command

Updates an existing command by the provided id parameter. You need to provide all fields like those you used to create a command. Partial updates are not supported. You can get id by using the listing API. You get the id also when you store a new value.

Authorizations:
bearer_authbasic_auth
path Parameters
id
required
string

Unique command ID

Request Body schema: */*

value in the json format

name
string

[required] User-friendly name of a commend

script
string

[required] text of the command

tags
Array of strings

List of tags for the script

timeout_sec
integer

Timout of the command in seconds

Responses

Deletes an existing command

Delete a command by the provided id parameter.

Authorizations:
bearer_authbasic_auth
path Parameters
id
required
string

Unique command ID

Responses

Audit Log

List auditlog entries

List auditlog entries using the provided filters

Authorizations:
bearer_authbasic_auth
query Parameters
sort
string

Sort option -<field>(desc) or <field>(asc). <field> can be one of 'timestamp', 'username', 'remote_ip', 'application', 'action', 'affected_id', 'client_id', 'client_hostname'. For example, &sort=-timestamp.

filter
string

Filter option filter[<field>] or filter[timestamp][<op>]. <field> can be one of 'username', 'remote_ip', 'application', 'action', 'affected_id', 'client_id', 'client_hostname'. For example, &filter[username]=admin or filter[timestamp][gt]=2021-10-28, etc. Multiple filters are possible. Wildcards * are supported in the filter <value>. Note: Only members of the Administrators user group are allowed to filter by username. Returns 403 Forbidden if an unallowed filter is used.

page
integer

Pagination options page[limit] and page[offset] can be used to get more than the first page of results. Default limit is 10 and maximum is 100. The count property in meta shows the total number of results.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Monitoring

Lists client metrics for displaying as graphs

List downsampled monitoring data about client metrics for the provided clientID

Authorizations:
bearer_authbasic_auth
path Parameters
client_id
required
string

Unique client ID

query Parameters
sort
string

There is only timestamp allowed as sort field. Default direction is DESC To sort ascending use &sort=timestamp.

filter[timestamp][<OPERATOR>]
string

Filter entries by field timestamp. <OPERATOR> can be one of gt, lt, since or until. gt and lt require a timestamp value as unixepoch. since and until require a timestamp value in format RFC3339. e.g. filter[timestamp][gt]=1636009200&filter[timestamp][lt]=1636009500 or e.g. filter[timestamp][since]=2021-01-01T00:00:00+01:00&filter[timestamp][until]=2021-01-01T01:00:00+01:00.

Downsampling data is available for a period >= 2 hours and <= 48 hours. When downsampling takes place you get avg, min and max values for cpu_usage_percent, memory_usage_percent and io_usage_percent

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "links": {
    }
}

Lists client metrics for given graph name

List downsampled monitoring data about client metrics for the provided clientID and graph name

Authorizations:
bearer_authbasic_auth
path Parameters
client_id
required
string

Unique client ID

graph_name
required
string

Unique graph name Possible values are cpu_usage_percent, mem_usage_percent, io_usage_percent, net_usage_percent_lan, net_usage_bps_lan, net_usage_percent_wan, net_usage_bps_wan

query Parameters
sort
string

There is only timestamp allowed as sort field. Default direction is DESC To sort ascending use &sort=timestamp.

filter[timestamp][<OPERATOR>]
string

Filter entries by field timestamp. <OPERATOR> can be one of gt, lt, since or until. gt and lt require a timestamp value as unixepoch. since and until require a timestamp value in format RFC3339. e.g. filter[timestamp][gt]=1636009200&filter[timestamp][lt]=1636009500 or e.g. filter[timestamp][since]=2021-01-01T00:00:00+01:00&filter[timestamp][until]=2021-01-01T01:00:00+01:00.

Downsampling data is available for a period >= 2 hours and <= 48 hours. When downsampling takes place you get avg, min and max values for one of cpu_usage_percent, memory_usage_percent, io_usage_percent, net_usage_percent_lan, net_usage_bps_lan, net_usage_percent_wan or net_usage_bps_wan

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Lists client metrics

List monitoring data about client metrics for the provided clientID

Authorizations:
bearer_authbasic_auth
path Parameters
client_id
required
string

Unique client ID

query Parameters
sort
string

There is only timestamp allowed as sort field. Default direction is DESC To sort ascending use &sort=timestamp.

filter[timestamp][<OPERATOR>]
string

Filter entries by field timestamp. <OPERATOR> can be one of gt, lt, since or until. gt and lt require a timestamp value as unixepoch. since and until require a timestamp value in format RFC3339. e.g. filter[timestamp][gt]=1636009200&filter[timestamp][lt]=1636009500 or e.g. filter[timestamp][since]=2021-01-01T00:00:00+01:00&filter[timestamp][until]=2021-01-01T01:00:00+01:00.

fields[<RESOURCE>]
string

Fields to be returned. It should be provided in the format as fields[<RESOURCE>]=<FIELDS>, where <RESOURCE> is metrics and <FIELDS> is a comma separated list of fields. Example: fields[metrics]=timestamp,cpu_usage_percent,memory_usage_percent,io_usage_percent. If no fields are specified, timestamp, cpu_usage_percent, memory_usage_percent and io_usage_percent are returned.

page
integer

Pagination options page[limit] and page[offset] can be used to get more than the first page of results. Default limit is 1 and maximum is 120. The count property in meta shows the total number of results.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Lists client mountpoints

List monitoring data about client mountpoints for the provided clientID

Authorizations:
bearer_authbasic_auth
path Parameters
client_id
required
string

Unique client ID

query Parameters
sort
string

There is only timestamp allowed as sort field. Default direction is DESC To sort ascending use &sort=timestamp.

filter[timestamp][<OPERATOR>]
string

Filter entries by field timestamp. <OPERATOR> can be one of gt, lt, since or until. gt and lt require a timestamp value as unixepoch. since and until require a timestamp value in format RFC3339. e.g. filter[timestamp][gt]=1636009200&filter[timestamp][lt]=1636009500 or e.g. filter[timestamp][since]=2021-01-01T00:00:00+01:00&filter[timestamp][until]=2021-01-01T01:00:00+01:00.

page
integer

Pagination options page[limit] and page[offset] can be used to get more than the first page of results. Default limit is 1 and maximum is 100. The count property in meta shows the total number of results.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Lists client processes

List monitoring data about client processes for the provided clientID

Authorizations:
bearer_authbasic_auth
path Parameters
client_id
required
string

Unique client ID

query Parameters
sort
string

There is only timestamp allowed as sort field. Default direction is DESC To sort ascending use &sort=timestamp.

filter[timestamp][<OPERATOR>]
string

Filter entries by field timestamp. <OPERATOR> can be one of gt, lt, since or until. gt and lt require a timestamp value as unixepoch. since and until require a timestamp value in format RFC3339. e.g. filter[timestamp][gt]=1636009200&filter[timestamp][lt]=1636009500 or e.g. filter[timestamp][since]=2021-01-01T00:00:00+01:00&filter[timestamp][until]=2021-01-01T01:00:00+01:00.

Fetching data for a period greater than 48 hours is not allowed. If the period exceeds 2 hours, than the returned measurement points get down sampled to reduce the amount of data. When down sampling takes place you get average, min and max values for cpu_usage_percent, memory_usage_percent and io_usage_percent

page
integer

Pagination options page[limit] and page[offset] can be used to get more than the first page of results. Default limit is 1 and maximum is 10. The count property in meta shows the total number of results.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Get the latest problems

  • Returns the latest problems for the alerting service
Authorizations:
bearer_authbasic_auth
query Parameters
sort
string

Sort option -<field>(desc) or <field>(asc). <field> can be one of rule_id, client_id, client_name, active, created_at, resolved_at. For example, TODO, etc

filter
string

Filter option filter[<FIELD>]=<VALUE> or filter[<FIELD>|<FIELD>]=<VALUE>,<VALUE> for OR conditions, alternatively: filter[<FIELD>]=or(<VALUE1>,<VALUE2>) for OR conditions, and filter[<FIELD>]=and(<VALUE1>,<VALUE2>) for AND conditions. The created_at and resolved_at date fields are handled differently, see below.

<FIELD> can be one of problem_id, rule_id, client_id, client_name, active, created_at, resolved_at.

You can use * wildcards to filter on any field and for partial matches (except the date fields). Text matching is case insensitive, filters can be combined together.

The created_at and the resolved_at fields can be queried with the gt, lt and eq filter operators to perform greater than, less than and equal date match filters. The date values specified in the filter must either conform to RFC3339 or be simple date fields (e.g. 2023-07-01). Currently, the other fields do not support the gt, lt and eq operators.

Examples:
TODO

fields[<RESOURCE>]
string

Fields to be returned. It should be provided in the format as fields[<RESOURCE>]=<FIELDS>, where <RESOURCE> is problems and <FIELDS> is a comma separated list of fields. Example: fields[clients]=id,name.

page
integer

Pagination options page[limit] and page[offset] can be used to get more than the first page of results. Default limit is 50 and maximum is 500. The count property in meta shows the total number of results.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Get details for a problem

  • Returns details for a problem generated by the alerting service.
Authorizations:
bearer_authbasic_auth
path Parameters
problem_id
required
string

unique problem ID

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Update problem status

Allows manual update of the active state for a problem. This API requires the current user to be member of group Administrators. Returns 403 otherwise. The Administrators group name is hardcoded and cannot be changed at the moment.

Authorizations:
bearer_authbasic_auth
path Parameters
problem_id
required
string

problem ID

Request Body schema: */*

New active state for the problem

active
boolean

Responses

Response samples

Content type
application/json
{
  • "errors": [
    ]
}

Get the latest rules

  • Returns the latest rules from the alerting service
Authorizations:
bearer_authbasic_auth

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Update all existing rules

Update the existing rules. This API requires the current user to be member of group Administrators. Returns 403 otherwise. The Administrators group name is hardcoded and cannot be changed at the moment.

Authorizations:
bearer_authbasic_auth
Request Body schema: */*

The new rules.

vars
Array of strings
Array of objects (Rule)

Responses

Response samples

Content type
application/json
{
  • "errors": [
    ]
}

Deletes all existing rules

Delete the existing rules. This API requires the current user to be member of group Administrators. Returns 403 otherwise. The Administrators group name is hardcoded and cannot be changed at the moment

Authorizations:
bearer_authbasic_auth

Responses

Response samples

Content type
application/json
{
  • "errors": [
    ]
}

Test Rules Against Test Data

Allows a set of rules to be tested against a set of test data. If successful then will include problems raised / resolved and notification requests (if applicable) that would be generated. If unsuccessful then will include the relevant errors, including any rules validation errors.

Authorizations:
bearer_authbasic_auth
Request Body schema: */*

Rules and test data to test.

object (RuleSet)
Array of objects (Template)
Array of objects (Client)
Array of objects (Measurement)
delay_ms
number

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Get details for a notification template

  • Returns details for a configured notification template
Authorizations:
bearer_authbasic_auth
path Parameters
template_id
required
string

unique template ID

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Update a template identified by the provided id

Update an existing template. This API requires the current user to be member of group Administrators. Returns 403 otherwise. The Administrators group name is hardcoded and cannot be changed at the moment.

Authorizations:
bearer_authbasic_auth
path Parameters
template_id
required
string

unique template ID

Request Body schema: */*

Template to update.

transport
string
subject
string
body
string
html
boolean
object
recipients
Array of strings

Responses

Response samples

Content type
application/json
{
  • "errors": [
    ]
}

Delete a template identified by the provided id

Deletes a template by a given id. This API requires the current user to be member of group Administrators. Returns 403 otherwise. The Administrators group name is hardcoded and cannot be changed at the moment

Authorizations:
bearer_authbasic_auth
path Parameters
template_id
required
string

unique template ID

Responses

Response samples

Content type
application/json
{
  • "errors": [
    ]
}

Get all notification templates

  • Returns the configured templates for the alerting service
Authorizations:
bearer_authbasic_auth

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Creates a template

Create a new template. This API requires the current user to be member of group Administrators. Returns 403 otherwise. The Administrators group name is hardcoded and cannot be changed at the moment.

Authorizations:
bearer_authbasic_auth
Request Body schema: */*

Template to update.

id
string
transport
any (Transport)
Enum: "smtp" "name of script"
subject
string
body
string
html
boolean
object
recipients
Array of strings

Responses

Response samples

Content type
application/json
{
  • "errors": [
    ]
}

Jobs

List schedules

Reads all schedules or find some based on the input parameters

Authorizations:
bearer_authbasic_auth
query Parameters
sort
string

Sort field to be used for sorting, the sorting direction is by default ASC. To change the direction add - to the sorting value e.g. -id. Allowed values are id, created_at, created_by, name, type. You can use as many sort parameters as you want.

filter[<FIELD>]
string

Filter the results. It should be provided in the format as filter[<FIELD>]=<VALUE>, where <FIELD> is one of the values id, created_at, created_by, name, type, client_ids, group_ids and <VALUE> is the search value, e.g. filter[name]=Schedule will request only schedule with name Schedule. You can use as many filter parameters as you want. If you want to filter by multiple values e.g. find entries either for name = Schedule or Other you can use following filters filter[name]=Schedule,Other. Wildcards * are supported in the filter <value>.

page
integer

Pagination options page[limit] and page[offset] can be used to get more than the first page of results. Default limit is 20 and maximum is 100. The count property in meta shows the total number of results.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Creates a new schedule

Creates a new schedule.

Authorizations:
bearer_authbasic_auth
Request Body schema: */*

value in the json format

name
string

Name of the schedule

schedule
string

Schedule in the cron format

type
string

'command' or 'script'

client_ids
Array of strings

Client IDs that schedule will be executed on

group_ids
Array of strings

Group IDs that schedule will be executed on

object (Tags)

list of client tags to target for execution, plus an operator either OR (for any matching tags) or AND (for all tags must match). Tags cannot be used in conjunction with client_ids or group_ids.

command
string

Command to be executed, only for type 'command'

script
string

Base64 encoded script to be executed, only for type 'script'

interpreter
string

Interpreter for schedule execution, for details on this and other params see commands or scripts

cwd
string

Cwd for schedule execution

is_sudo
boolean

Is sudo for schedule execution

timeout_sec
number

Timeout for schedule execution

execute_concurrently
boolean

Whether to execute concurrently on all clients

abort_on_error
boolean

Abort on error for schedule execution

overlaps
boolean

Whether to start another schedule execution when previous is still in progress

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Get a schedule

Get a schedule by the provided ID

Authorizations:
bearer_authbasic_auth
path Parameters
id
required
string

Unique schedule ID

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Updates an existing schedule

Updates an existing schedule by the provided id parameter. You need to provide all fields like those you used to create a schedule. Partial updates are not supported. You can get id by using the listing API. You get the id also when you store a new value.

Authorizations:
bearer_authbasic_auth
path Parameters
id
required
string

Unique schedule ID

Request Body schema: */*

value in the json format

name
string

Name of the schedule

schedule
string

Schedule in the cron format

type
string

'command' or 'script'

client_ids
Array of strings

Client IDs that schedule will be executed on

group_ids
Array of strings

Group IDs that schedule will be executed on

object (Tags)

list of client tags to target for execution, plus an operator either OR (for any matching tags) or AND (for all tags must match). Tags cannot be used in conjunction with client_ids or group_ids.

command
string

Command to be executed, only for type 'command'

script
string

Base64 encoded script to be executed, only for type 'script'

interpreter
string

Interpreter for schedule execution, for details on this and other params see commands or scripts

cwd
string

Cwd for schedule execution

is_sudo
boolean

Is sudo for schedule execution

timeout_sec
number

Timeout for schedule execution

execute_concurrently
boolean

Whether to execute concurrently on all clients

abort_on_error
boolean

Abort on error for schedule execution

overlaps
boolean

Whether to start another schedule execution when previous is still in progress

Responses

Deletes an existing schedule

Delete a schedule by the provided id parameter.

Authorizations:
bearer_authbasic_auth
path Parameters
id
required
string

Unique schedule ID

Responses

Notifications

Get the latest notifications

  • Returns the latest problems for the alerting service
Authorizations:
bearer_authbasic_auth
query Parameters
sort
string

Sort option -<field>(desc) or <field>(asc). <field> can be one of timestamp, state.

filter
string

Filter option filter[<FIELD>]=<VALUE> or filter[<FIELD>|<FIELD>]=<VALUE>,<VALUE> for OR conditions, alternatively: filter[<FIELD>]=or(<VALUE1>,<VALUE2>) for OR conditions, and filter[<FIELD>]=and(<VALUE1>,<VALUE2>) for AND conditions. The created_at and resolved_at date fields are handled differently, see below.

<FIELD> can be one of state, reference_id, transport, subject, timestamp[gt], timestamp[lt], timestamp[since], timestamp[until].

You can use * wildcards to filter on any field and for partial matches (except the date fields). Text matching is case insensitive, filters can be combined together.

The timestamp fields can be queried with the gt, lt and eq filter operators to perform greater than, less than and equal date match filters. The date values specified in the filter must either conform to RFC3339 or be simple date fields (e.g. 2023-07-01). Currently, the other fields do not support the gt, lt and eq operators.

fields[<RESOURCE>]
string

Fields to be returned. It should be provided in the format as fields[<RESOURCE>]=<FIELDS>, where <RESOURCE> is problems and <FIELDS> is a comma separated list of fields. Example: fields[clients]=id,name.

page
integer

Pagination options page[limit] and page[offset] can be used to get more than the first page of results. Default limit is 50 and maximum is 500. The count property in meta shows the total number of results.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Get notification details

Authorizations:
bearer_authbasic_auth
path Parameters
notification_id
required
string

unique notification ID

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}