[go: up one dir, main page]
Documentation Powered by ReDoc

LiveEdge Cloud REST API (1.0.1307)

Download OpenAPI specification:Download

E-mail: info@videonlabs.com

Videon's LiveEdge Cloud provides a simple and intuitive way for organizations to manage fleets of appliances using an intuitive website, or an extensive API set.

OpenAPI Specification

This API is documented in OpenAPI format. Use the /openapi endpoint to retrieve the specification for the API.

Cross-Origin Resource Sharing

The API features Cross-Origin Resource Sharing (CORS). Any endpoint can receive a preflight OPTIONS request, and will respond with the supported methods on that endpoint.

Authentication

VideonAuthorizer

Currently the LiveEdge Cloud API supports two different authentication schemes:

1. JSON Web Token (JWT)

JWT access token issued by the LiveEdge Cloud auth provider. Typically used by interactive web applications. Such tokens are short-lived and must be refreshed frequently. The provided token must not be expired, and must be an access token (not an identity or refresh token).

For JWT authentication, the HTTP Authorization header should be prefixed with "Bearer", followed by a space, followed by the access token value.

Example: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6Ikp...

2. Personal Access Token (PAT)

Use a Personal Access Token issued by the LiveEdge Cloud platform. Users have the ability to issue long-lived PAT tokens that are easier to use in non-interactive applications. Authenticating with a PAT token will yield the same permissions as the user that issued it.

Since PAT tokens are long-lived, it is important for the client to securely store the token and protect it from unauthorized access. Avoid storing the token in unencrypted plain text and do not hard code it into your application source code.

Despite being long-lived, PAT tokens do have an expiration date. Clients are responsible tracking PAT expiration and issuing new tokens as needed (this can be done via the API).

If a PAT token is no longer needed or has been exposed to an unauthorized party, it may be revoked immediately.

For PAT authentication, the HTTP Authorization header should be prefixed with "PAT", followed by a space, followed by the access token value.

Example: PAT J1eee35QGmzwgqaaovJ8cbnS9wBPGwHI

Security Scheme Type API Key
Header parameter name: Authorization

openapi

Retrieve the OpenAPI specification for this API

OpenAPI Spec

Redirects the client to the HTML version of the documentation, see /openapi/html.

Responses

OpenAPI Spec (HTML)

Returns the OpenAPI specification document for this API as user-friendly HTML. Users may visit this URL with their browser to learn about the API. No authentication required.

Responses

OpenAPI Spec (JSON)

Returns the OpenAPI specification document for this API as plain text JSON. Tools that consume OpenAPI (Swagger, Postman, etc.) may use this URL to import the API definition. No authentication required.

Responses

OpenAPI Spec (YAML)

Returns the OpenAPI specification document for this API as plain text YAML. Tools that consume OpenAPI (Swagger, Postman, etc.) may use this URL to import the API definition. No authentication required.

Responses

auth-info

Retrieve Authentication Information

Get Authentication Details

Used by the front end UI to provide information for a smooth authentication flow. Returns info about which SSO identity provider the user is registered with, URL to the OAuth provider, etc. The expectation is that the login screen will prompt the user for their email, call this API, and then use the response to determine the next step (prompt for password, redirect to SSO Identity Provider, etc.).

query Parameters
email
string <email>

Email address of the user attempting to sign in. The user does not need to actually be registered (the API will not disclose whether or not a user actually exists).

Responses

Response samples

Content type
application/json
{
  • "cognito_region": "string",
  • "cognito_user_pool_id": "string",
  • "cognito_user_pool_domain": "string",
  • "cognito_identity_pool_id": "string",
  • "client_id": "string",
  • "profile_picture_bucket": "string",
  • "oauth_scope": [
    ],
  • "oauth_response_type": "string",
  • "idp_identifier": "string",
  • "identity_provider": "string",
  • "sso_providers": [ ]
}

pats

View and Manage Personal Access Tokens

Get Personal Access Tokens

Get the personal access tokens for a specific user.

query Parameters
user_guid
string

GUID of the user account. If omitted, the API will use the GUID associated with your user.

pagination_size
integer [ 1 .. 60 ]
Default: 50

The pagination size for the request. This is the maximum number of objects to return in the request.

pagination_token
string non-empty

Search results are paginated, up to 1MB of data or the client-defined amount (pagination_size), whichever is lower. If one of those limits is exceeded, the response will include a token to retrieve the next page. If you have a pagination token from a previous request, pass it in here (all other parameters the same) to get the next page. It may be necessary to repeat the call several times to obtain the full set of search results. When pagination_token is null or missing from the response, you have reached the end of the results.

Responses

Response samples

Content type
application/json
{
  • "personal_access_tokens": [
    ],
  • "pagination_token": "string"
}

Create a Personal Access Token

Create a personal access token with the attributes specified.

Request Body schema: application/json
token_lifespan_days
required
integer [ 1 .. 365 ]

Number of days the token will be valid.

comment
string

A comment that will be associated with the personal access token.

Responses

Request samples

Content type
application/json
{
  • "token_lifespan_days": 1,
  • "comment": "Access token for computer A"
}

Response samples

Content type
application/json
{
  • "token_guid": "612f310f-a8d2-401b-8e5a-ce42b43d6d85",
  • "token_prefix": "string",
  • "token_value": "string",
  • "expires": "2019-08-24T14:15:22Z"
}

Get Personal Access Token Details

Get the details for a specific personal access token.

path Parameters
token_guid
required
string

GUID of the personal access token.

query Parameters
user_guid
string

GUID of the user account. If omitted, the API will use the GUID associated with your user.

Responses

Response samples

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

Revoke a Personal Access Token

Revoke a personal access token with the attributes specified.

path Parameters
token_guid
required
string

GUID of the personal access token.

query Parameters
user_guid
string

GUID of the user account. If omitted, the API will use the GUID associated with your user.

Responses

Response samples

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

alerts

View and Configure Alert Notifications

Find Alerts

Search for alerts based on the specified search parameters.

query Parameters
org_guid
string

GUID of an organization to filter alert results by. Either Org-Guid or org_guid must be present. If both are present, org_guid is used.

device_guids
Array of strings

Devices to find alerts for.

silenced
boolean
Default: true

If true, include silenced alerts in the results.

resolved
boolean
Default: true

If true, include resolved alerts in the results.

start_time
string <date-time>

Date and time of the earliest events to return in ISO 8601 format as specified by RFC 3339, Section 5.6. Required when device_guids is omitted or contains more than one device guid.

end_time
string <date-time>

Date and time of the latest events to return in ISO 8601 format as specified by RFC 3339, Section 5.6.

pagination_size
integer [ 1 .. 60 ]
Default: 50

The pagination size for the request. This is the maximum number of objects to return in the request.

pagination_token
string non-empty

Search results are paginated, up to 1MB of data or the client-defined amount (pagination_size), whichever is lower. If one of those limits is exceeded, the response will include a token to retrieve the next page. If you have a pagination token from a previous request, pass it in here (all other parameters the same) to get the next page. It may be necessary to repeat the call several times to obtain the full set of search results. When pagination_token is null or missing from the response, you have reached the end of the results.

header Parameters
Org-Guid
string

GUID of an organization to filter alert results by. Either Org-Guid or org_guid must be present. If both are present, org_guid is used.

Responses

Response samples

Content type
application/json
{
  • "alerts": [
    ],
  • "pagination_token": "string"
}

Get Alert Details

Get the details for a specific alert.

path Parameters
alert_guid
required
string

GUID of the alert.

Responses

Response samples

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

Silence Alert

Update an alert to be silenced.

path Parameters
alert_guid
required
string

GUID of the alert.

Request Body schema: application/json
silenced
boolean
Default: true

True when silencing the alert, false when unsilencing.

Responses

Request samples

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

Close Alert

Close an alert. By closing an alert, the next time the alert goes into an error state, the email and user list will be notified.

path Parameters
alert_guid
required
string

GUID of the alert.

Responses

Get Alerts History

Get a history of alerts

query Parameters
device_guids
Array of strings

Devices to find alerts for.

start_time
required
string <date-time>

Date and time of the earliest events to return in ISO 8601 format as specified by RFC 3339, Section 5.6.

end_time
string <date-time>

Date and time of the latest events to return in ISO 8601 format as specified by RFC 3339, Section 5.6.

pagination_size
integer [ 1 .. 60 ]
Default: 50

The pagination size for the request. This is the maximum number of objects to return in the request.

pagination_token
string non-empty

Search results are paginated, up to 1MB of data or the client-defined amount (pagination_size), whichever is lower. If one of those limits is exceeded, the response will include a token to retrieve the next page. If you have a pagination token from a previous request, pass it in here (all other parameters the same) to get the next page. It may be necessary to repeat the call several times to obtain the full set of search results. When pagination_token is null or missing from the response, you have reached the end of the results.

Responses

Response samples

Content type
application/json
{
  • "alerts": [
    ],
  • "pagination_token": "string"
}

Get Alerts Configuration

Get the alert configuration for a specific organization

query Parameters
org_guid
string

GUID of the organization the configuration is for. Either Org-Guid or org_guid must be present. If both are present, org_guid is used.

header Parameters
Org-Guid
string

GUID of the organization the configuration is for. Either Org-Guid or org_guid must be present. If both are present, org_guid is used.

Responses

Response samples

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

Update Alerts Configuration Properties

Update the alert configuration for a specific organization. This endpoint is asynchronous when any metric alerts are provided or a state alert is disabled, meaning it returns before the operation has completed. If multiple asynchronous configuration changes are sent within a short period of time, the last request to be processed will be the one that succeeds.

header Parameters
Org-Guid
string

GUID of the organization the configuration is for. Either Org-Guid or org_guid must be present. If both are present, org_guid is used.

Request Body schema: application/json
org_guid
string

GUID of the organization the configuration is for. Either Org-Guid or org_guid must be present. If both are present, org_guid is used.

required
object

Responses

Request samples

Content type
application/json
{
  • "org_guid": "string",
  • "config": {
    }
}

Response samples

Content type
application/json
{
  • "message": "string",
  • "failed_emails": [
    ],
  • "failed_users": [
    ]
}

devices

View and Manage Videon Devices

Find Devices

Search for devices based on the specified search parameters.

query Parameters
org_guid
string

GUID of an organization to filter device results by. If both Org-Guid and org_guid are present, org_guid is used.

user_guid
string

GUID of a user to filter device results by. If present, org_guid is ignored. If org_guid/Org-Guid and user_guid are not present, defaults to your user GUID. Only devices that the user is directly assigned to will be returned.

serial_number
string

Serial number of a device to filter results by. Partial matches will be returned, only if it matches the prefix of the serial number, e.g., 123 will match device 1234 but not device 4123.

pagination_size
integer [ 1 .. 60 ]
Default: 50

The pagination size for the request. This is the maximum number of objects to return in the request.

pagination_token
string non-empty

Search results are paginated, up to 1MB of data or the client-defined amount (pagination_size), whichever is lower. If one of those limits is exceeded, the response will include a token to retrieve the next page. If you have a pagination token from a previous request, pass it in here (all other parameters the same) to get the next page. It may be necessary to repeat the call several times to obtain the full set of search results. When pagination_token is null or missing from the response, you have reached the end of the results.

header Parameters
Org-Guid
string

GUID of an organization to filter device results by. If both Org-Guid and org_guid are present, org_guid is used.

Responses

Response samples

Content type
application/json
{
  • "devices": [
    ],
  • "pagination_token": "string"
}

Adopt Device

Adopt a device with the specified attributes.

query Parameters
org_guid
string

GUID of the organization adopting the device. Either Org-Guid or org_guid must be present. If both are present, org_guid is used.

serial_number
required
string

Serial number of the device to adopt.

header Parameters
Org-Guid
string

GUID of the organization adopting the device. Either Org-Guid or org_guid must be present. If both are present, org_guid is used.

Responses

Response samples

Content type
application/json
{
  • "message": "string",
  • "device": {
    }
}

Get Device Events - Multiple Devices

Get devices events based on the provided attributes. Events are deleted 30 days after they occur.

query Parameters
device_guids
required
Array of strings

Devices to find events for.

event_types
Array of strings

Type of events to search for. If omitted, all event types are returned.

start_time
required
string <date-time>

Date and time of the earliest events to return in ISO 8601 format as specified by RFC 3339, Section 5.6.

end_time
string <date-time>

Date and time of the latest events to return in ISO 8601 format as specified by RFC 3339, Section 5.6.

pagination_size
integer [ 1 .. 60 ]
Default: 50

The pagination size for the request. This is the maximum number of objects to return in the request.

pagination_token
string non-empty

Search results are paginated, up to 1MB of data or the client-defined amount (pagination_size), whichever is lower. If one of those limits is exceeded, the response will include a token to retrieve the next page. If you have a pagination token from a previous request, pass it in here (all other parameters the same) to get the next page. It may be necessary to repeat the call several times to obtain the full set of search results. When pagination_token is null or missing from the response, you have reached the end of the results.

Responses

Response samples

Content type
application/json
{
  • "events": [
    ],
  • "pagination_token": "string"
}

Get Possible Device Metric Properties - Generic

Returns the possible values for various metrics properties.

Responses

Response samples

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

Search Device Metrics - Multiple Devices

Search for metrics for specific devices.

Request Body schema: application/json
device_guids
required
Array of strings

Devices to retrieve metrics for.

required
Array of objects
start_time
required
string <date-time>

The date and time indicating the earliest data to be returned, in ISO 8601 format as specified by RFC 3339, Section 5.6.

end_time
required
string <date-time>

The date and time indicating the latest data to be returned, in ISO 8601 format as specified by RFC 3339, Section 5.6.

scan_by
string
Default: "TimestampDescending"
Enum: "TimestampDescending" "TimestampAscending"

The order in which data should be returned:

  • TimestampAscending - Returns the oldest data first
  • TimestampDescending - Returns the newest data first
pagination_size
integer [ 1 .. 60 ]
Default: 50

The pagination size for the request. This is the maximum number of objects to return in the request.

pagination_token
string

Search results are paginated, up to 1MB of data or the client-defined amount (pagination_size), whichever is lower. If one of those limits is exceeded, the response will include a token to retrieve the next page. If you have a pagination token from a previous request, pass it in here (all other parameters the same) to get the next page. It may be necessary to repeat the call several times to obtain the full set of search results. When pagination_token is null or missing from the response, you have reached the end of the results.

Responses

Request samples

Content type
application/json
{
  • "device_guids": [
    ],
  • "metrics": [
    ],
  • "start_time": "2019-08-24T14:15:22Z",
  • "end_time": "2019-08-24T14:15:22Z",
  • "scan_by": "TimestampDescending",
  • "pagination_size": 50,
  • "pagination_token": "string"
}

Response samples

Content type
application/json
{
  • "metrics": [
    ],
  • "pagination_token": "string"
}

Get Device Statuses

Get the statuses for devices in an organization.

query Parameters
org_guid
string

GUID of the organization associated with the device. Either Org-Guid or org_guid must be present. If both are present, org_guid is used.

online
boolean
Default: true

Whether to return devices that are currently online.

streaming
boolean
Default: true

Whether to return devices that are actively streaming.

header Parameters
Org-Guid
string

GUID of the organization associated with the device. Either Org-Guid or org_guid must be present. If both are present, org_guid is used.

Responses

Response samples

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

Get Update Version

Get the most up-to-date version that is available.

path Parameters
update_type
required
string
Value: "cloud"

The type of the update.

Responses

Response samples

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

Get Device Details

Get the details for a specific device.

path Parameters
device_guid
required
string

GUID of the device.

Responses

Response samples

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

Delete Device

Delete a specific device.

path Parameters
device_guid
required
string

GUID of the device.

Request Body schema: application/json
reason
required
string <= 2048 characters

Reason for deletion of device.

Responses

Request samples

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

Get Device Command Requests/Responses

Get device commands based on the provided attributes.

path Parameters
device_guid
required
string

GUID of the device.

query Parameters
pagination_size
integer [ 1 .. 60 ]
Default: 50

The pagination size for the request. This is the maximum number of objects to return in the request.

pagination_token
string non-empty

Search results are paginated, up to 1MB of data or the client-defined amount (pagination_size), whichever is lower. If one of those limits is exceeded, the response will include a token to retrieve the next page. If you have a pagination token from a previous request, pass it in here (all other parameters the same) to get the next page. It may be necessary to repeat the call several times to obtain the full set of search results. When pagination_token is null or missing from the response, you have reached the end of the results.

Responses

Response samples

Content type
application/json
{
  • "commands": {
    },
  • "pagination_token": "string"
}

Send Command

Send a new command to a device.

path Parameters
device_guid
required
string

GUID of the device.

Request Body schema: application/json
command
required
string

The command to execute.

output_type
string

The output type that the command was issued for. Required for the command set_output_state. Set this to "all" to apply to all output_types, otherwise set to one of the values in the output_type enum under Output Streams in the Edgecaster Videon Streaming REST API documentation (found in the Videon Help Center)

data
any

The request data to give to the command. The type of this attribute varies based on the command.
For set_output_state, valid values are true or false.
For rest_direct commands, see the Edgecaster Videon Streaming REST API documentation (found in the Videon Help Center) for valid request data for each endpoint.

rest_endpoint
string

The relative path to the device's REST endpoint that is to receive the command. Only present for rest_direct commands.

Responses

Request samples

Content type
application/json
{
  • "command": "string",
  • "output_type": "string",
  • "data": {
    },
  • "rest_endpoint": "encoders/vid_encoders/60"
}

Response samples

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

Get Device Command Request/Response

Get device command based on the provided attributes.

path Parameters
device_guid
required
string

GUID of the device.

command_guid
required
string

GUID of the command.

Responses

Response samples

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

Get Device Document Details

Returns the timestamp that each document was last updated.

path Parameters
device_guid
required
string

GUID of the device.

Responses

Response samples

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

Get Device Events

Get devices events based on the provided attributes. Events are deleted 30 days after they occur.

path Parameters
device_guid
required
string

GUID of the device.

query Parameters
event_types
Array of strings

Type of events to search for. If omitted, all event types are returned.

start_time
string <date-time>

Date and time of the earliest events to return in ISO 8601 format as specified by RFC 3339, Section 5.6.

end_time
string <date-time>

Date and time of the latest events to return in ISO 8601 format as specified by RFC 3339, Section 5.6.

pagination_size
integer [ 1 .. 60 ]
Default: 50

The pagination size for the request. This is the maximum number of objects to return in the request.

pagination_token
string non-empty

Search results are paginated, up to 1MB of data or the client-defined amount (pagination_size), whichever is lower. If one of those limits is exceeded, the response will include a token to retrieve the next page. If you have a pagination token from a previous request, pass it in here (all other parameters the same) to get the next page. It may be necessary to repeat the call several times to obtain the full set of search results. When pagination_token is null or missing from the response, you have reached the end of the results.

Responses

Response samples

Content type
application/json
{
  • "events": [
    ],
  • "pagination_token": "string"
}

Get Device Fleets

Get the fleets for a specific device.

path Parameters
device_guid
required
string

GUID of the device.

query Parameters
pagination_size
integer [ 1 .. 60 ]
Default: 50

The pagination size for the request. This is the maximum number of objects to return in the request.

pagination_token
string non-empty

Search results are paginated, up to 1MB of data or the client-defined amount (pagination_size), whichever is lower. If one of those limits is exceeded, the response will include a token to retrieve the next page. If you have a pagination token from a previous request, pass it in here (all other parameters the same) to get the next page. It may be necessary to repeat the call several times to obtain the full set of search results. When pagination_token is null or missing from the response, you have reached the end of the results.

Responses

Response samples

Content type
application/json
{
  • "fleets": [
    ],
  • "pagination_token": "string"
}

Get Device Logs

Get a url to the last requested set of logs

path Parameters
device_guid
required
string

GUID of the device.

Responses

Response samples

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

Request Device Logs

Send a command to the device to retrieve the current device logs.

path Parameters
device_guid
required
string

GUID of the device.

Responses

Response samples

Content type
application/json
{
  • "message": "string",
  • "command_guid": "string"
}

Get Device Metadata

Get all metadata configured on a given device

path Parameters
device_guid
required
string

GUID of the device.

query Parameters
pagination_size
integer [ 1 .. 60 ]
Default: 50

The pagination size for the request. This is the maximum number of objects to return in the request.

pagination_token
string non-empty

Search results are paginated, up to 1MB of data or the client-defined amount (pagination_size), whichever is lower. If one of those limits is exceeded, the response will include a token to retrieve the next page. If you have a pagination token from a previous request, pass it in here (all other parameters the same) to get the next page. It may be necessary to repeat the call several times to obtain the full set of search results. When pagination_token is null or missing from the response, you have reached the end of the results.

Responses

Response samples

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

Create or Update Device Metadata

Create new metadata key/value pair, or update an existing key/value pair

path Parameters
device_guid
required
string

GUID of the device.

Request Body schema: application/json
Array ()
key
string

The key of the metadata

value
string

The value of the metadata

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

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

Get Possible Device Metric Properties - Device-Specific

Returns the possible values for various metrics properties.

path Parameters
device_guid
required
string

GUID of the device.

Responses

Response samples

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

Search Device Metrics - Device-Specific

Search for metrics for a specific device.

path Parameters
device_guid
required
string

GUID of the device.

Request Body schema: application/json
required
Array of objects
start_time
required
string <date-time>

The date and time indicating the earliest data to be returned, in ISO 8601 format as specified by RFC 3339, Section 5.6.

end_time
required
string <date-time>

The date and time indicating the latest data to be returned, in ISO 8601 format as specified by RFC 3339, Section 5.6.

scan_by
string
Default: "TimestampDescending"
Enum: "TimestampDescending" "TimestampAscending"

The order in which data should be returned:

  • TimestampAscending - Returns the oldest data first
  • TimestampDescending - Returns the newest data first
pagination_size
integer [ 1 .. 60 ]
Default: 50

The pagination size for the request. This is the maximum number of objects to return in the request.

pagination_token
string

Search results are paginated, up to 1MB of data or the client-defined amount (pagination_size), whichever is lower. If one of those limits is exceeded, the response will include a token to retrieve the next page. If you have a pagination token from a previous request, pass it in here (all other parameters the same) to get the next page. It may be necessary to repeat the call several times to obtain the full set of search results. When pagination_token is null or missing from the response, you have reached the end of the results.

Responses

Request samples

Content type
application/json
{
  • "metrics": [
    ],
  • "start_time": "2019-08-24T14:15:22Z",
  • "end_time": "2019-08-24T14:15:22Z",
  • "scan_by": "TimestampDescending",
  • "pagination_size": 50,
  • "pagination_token": "string"
}

Response samples

Content type
application/json
{
  • "metrics": [
    ],
  • "pagination_token": "string"
}

Update Device Outputs

Update Outputs shadow to enable/disable outputs

path Parameters
device_guid
required
string

GUID of the device.

Request Body schema: application/json
Array ()
output_id
required
integer

ID of the output to operate on

enable
required
boolean

True if changing the output to enabled

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Get Device Shadow

Returns the reported state from the most recently completed shadow command and the information from the most recently issued shadow command that is requesting changes (excludes get). This data will be updated every time a new shadow command is completed.

path Parameters
device_guid
required
string

GUID of the device.

query Parameters
shadow_names
Array of strings non-empty
Items Enum: "System" "Inputs" "Encoders" "Outputs"

Names of the shadows to retrieve. When omitted, all shadows are retrieved.

Responses

Response samples

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

Get Device Shadow Command Requests/Responses

Get device shadow commands based on the provided attributes.

path Parameters
device_guid
required
string

GUID of the device.

query Parameters
pagination_size
integer [ 1 .. 60 ]
Default: 50

The pagination size for the request. This is the maximum number of objects to return in the request.

pagination_token
string non-empty

Search results are paginated, up to 1MB of data or the client-defined amount (pagination_size), whichever is lower. If one of those limits is exceeded, the response will include a token to retrieve the next page. If you have a pagination token from a previous request, pass it in here (all other parameters the same) to get the next page. It may be necessary to repeat the call several times to obtain the full set of search results. When pagination_token is null or missing from the response, you have reached the end of the results.

Responses

Response samples

Content type
application/json
{
  • "commands": [
    ],
  • "pagination_token": "string"
}

Send Shadow Command

Send a new shadow command to a device.

path Parameters
device_guid
required
string

GUID of the device.

Request Body schema: application/json
command_type
required
string
Enum: "get" "set"

The type of command(s) to issue:

  • "get" - Get the current configuration of the shadow.
  • "set" - Update the current configuration of the shadow.
required
Array of objects

The data to give to the command. This attribute should contain an object for each shadow being targeted.

Responses

Request samples

Content type
application/json
{
  • "command_type": "get",
  • "commands": [
    ]
}

Response samples

Content type
application/json
{
  • "command_type": "string",
  • "commands": [
    ]
}

Get Device Shadow Request/Response

Get device shadow command based on the provided attributes.

path Parameters
device_guid
required
string

GUID of the device.

command_guid
required
string

GUID of the shadow command.

Responses

Response samples

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

Get Device State

Get the state for a specific device. Note all state details listed below. See response body for full list.

path Parameters
device_guid
required
string

GUID of the device.

Responses

Response samples

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

Get Update Version

Get the most up-to-date version that is available.

path Parameters
device_guid
required
string

GUID of the device.

update_type
required
string
Value: "cloud"

The type of the update.

Responses

Response samples

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

Start update

Start the update process for the device.

path Parameters
device_guid
required
string

GUID of the device.

update_type
required
string
Value: "cloud"

The type of the update.

Request Body schema: application/json
update
required
boolean

To prevent accidentally starting an update, this field must be true in order for the update to begin.

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "message": "string",
  • "command_guid": "string"
}

Get Device Membership Details

Get the users for a specific device. Note that you will be unable to access devices that you are not a member of. If a user has multiple direct assignments (via fleet and/or device assignment), the user will appear in the list multiple times.

path Parameters
device_guid
required
string

GUID of the device.

query Parameters
user_guid
string

GUID of a user to get device access for. If the user has access to the device via multiple direct assignments (via fleet and/or device assignment), they will all be returned.

pagination_size
integer [ 1 .. 60 ]
Default: 50

The pagination size for the request. This is the maximum number of objects to return in the request.

pagination_token
string non-empty

Search results are paginated, up to 1MB of data or the client-defined amount (pagination_size), whichever is lower. If one of those limits is exceeded, the response will include a token to retrieve the next page. If you have a pagination token from a previous request, pass it in here (all other parameters the same) to get the next page. It may be necessary to repeat the call several times to obtain the full set of search results. When pagination_token is null or missing from the response, you have reached the end of the results.

Responses

Response samples

Content type
application/json
{
  • "users": [
    ],
  • "pagination_token": "string"
}

Create or Add User to Device

Add a user to a device, or if the user doesn't exist, create and add the user.

path Parameters
device_guid
required
string

GUID of the device.

Request Body schema: application/json
user_guid
string

User GUID (if adding existing user)

name
string [ 1 .. 2048 ] characters

Full name of the user.

email
string <email> [ 1 .. 128 ] characters

Email address of the user.

password
string [ 6 .. 256 ] characters

Password for the user.

phone_number
string or null

Mobile phone number of the user (optional). Must start with + and country code. Can only contain plus sign and digits.

locale
string <= 2048 characters

User locale in BCP 47 (RFC 5646) format.

zoneinfo
string <= 2048 characters

User time zone in zoneinfo (tz database) format.

access
required
integer

If user_guid was provided, the access level of the requested user. Otherwise, the access level of the current user. (100 = reader, 200 = user, 300 = admin)

Responses

Request samples

Content type
application/json
{
  • "user_guid": "string",
  • "name": "string",
  • "email": "user@example.com",
  • "password": "string",
  • "phone_number": 18142351111,
  • "locale": "en_US",
  • "zoneinfo": "Europe/Paris",
  • "access": 100
}

Response samples

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

Update Device Users

Update user permissions within a device.

path Parameters
device_guid
required
string

GUID of the device.

Request Body schema: application/json
Array of objects

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "message": "string",
  • "failed_users": [
    ]
}

Delete Device Users

Remove users from a device.

path Parameters
device_guid
required
string

GUID of the device.

Request Body schema: application/json
users
Array of strings

List of user GUIDs to remove from the device.

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "message": "string",
  • "failed_users": [
    ]
}

Get Device Docker Images

Returns the Docker images downloaded on the device.

path Parameters
device_guid
required
string

GUID of the device.

Responses

Response samples

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

Pull Docker Image

Instructs the device to pull an image from Docker Hub.

path Parameters
device_guid
required
string

GUID of the device.

Request Body schema: application/json
repository
required
string

Repository of image.

tag
string

Tag of image.

Responses

Request samples

Content type
application/json
{
  • "repository": "string",
  • "tag": "string"
}

Response samples

Content type
application/json
{
  • "repository": "string",
  • "tag": "string",
  • "id": "string",
  • "hash": "string",
  • "created": "2019-08-24T14:15:22Z",
  • "size": 0
}

Get Device Docker Image

Returns a specific Docker image downloaded on the device.

path Parameters
device_guid
required
string

GUID of the device.

image_id
required
string

ID of the image.

Responses

Response samples

Content type
application/json
{
  • "repository": "string",
  • "tag": "string",
  • "id": "string",
  • "hash": "string",
  • "created": "2019-08-24T14:15:22Z",
  • "size": 0
}

Delete Docker Image

Instructs the device to delete an image.

path Parameters
device_guid
required
string

GUID of the device.

image_id
required
string

ID of the image.

Request Body schema: application/json
reason
required
string

Responses

Request samples

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

Get Device Docker Containers

Returns the Docker containers running on the device.

path Parameters
device_guid
required
string

GUID of the device.

Responses

Response samples

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

Create Docker Container

Instructs the device to create a container from an image.

path Parameters
device_guid
required
string

GUID of the device.

Request Body schema: application/json
name
string

Name of the container.

image_id
required
string

Image id to use.

object
Array of objects
Array of objects
Array of objects

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "image_id": "string",
  • "restart_policy": {
    },
  • "environment": [
    ],
  • "volumes": [
    ],
  • "ports": [
    ]
}

Response samples

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

Get Device Docker Container

Returns a specific Docker container on the device.

path Parameters
device_guid
required
string

GUID of the device.

container_id
required
string

ID of the container.

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "image": "string",
  • "created": "string",
  • "status": "created"
}

Perform an action on a Docker Container

Start, Stop, Pause, Unpause, Kill, or Restart container.

path Parameters
device_guid
required
string

GUID of the device.

container_id
required
string

ID of the container.

Request Body schema: application/json
action
required
string
Enum: "start" "stop" "pause" "unpause" "kill" "restart"

Responses

Request samples

Content type
application/json
{
  • "action": "start"
}

Delete Docker Container

Instructs the device to delete an inactive container.

path Parameters
device_guid
required
string

GUID of the device.

container_id
required
string

ID of the container.

Request Body schema: application/json
reason
required
string

Responses

Request samples

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

entitlements

View and Manage Entitlements

Get Device Licenses

Get the licenses applied to a specific device.

path Parameters
device_guid
required
string

GUID of the device.

query Parameters
pagination_size
integer [ 1 .. 60 ]
Default: 50

The pagination size for the request. This is the maximum number of objects to return in the request.

pagination_token
string non-empty

Search results are paginated, up to 1MB of data or the client-defined amount (pagination_size), whichever is lower. If one of those limits is exceeded, the response will include a token to retrieve the next page. If you have a pagination token from a previous request, pass it in here (all other parameters the same) to get the next page. It may be necessary to repeat the call several times to obtain the full set of search results. When pagination_token is null or missing from the response, you have reached the end of the results.

Responses

Response samples

Content type
application/json
{
  • "licenses": [
    ],
  • "pagination_token": "string"
}

Get Entitlement Licenses

Search for licenses based on the specified attributes.

query Parameters
org_guid
string

GUID of an organization to filter license results by.

serial_number
string

Serial number of a device to filter license results by. If present, org_guid is ignored.

show_orgs
boolean
Default: true

When an org GUID or serial number has not been provided, return all orgs with licenses in the response.

show_serials
boolean
Default: true

When an org GUID or serial number has not been provided, return all serial numbers with licenses in the response.

pagination_size
integer [ 1 .. 60 ]
Default: 50

The pagination size for the request. This is the maximum number of objects to return in the request.

pagination_token
string non-empty

Search results are paginated, up to 1MB of data or the client-defined amount (pagination_size), whichever is lower. If one of those limits is exceeded, the response will include a token to retrieve the next page. If you have a pagination token from a previous request, pass it in here (all other parameters the same) to get the next page. It may be necessary to repeat the call several times to obtain the full set of search results. When pagination_token is null or missing from the response, you have reached the end of the results.

Responses

Response samples

Content type
application/json
{
  • "licenses": [
    ],
  • "pagination_token": "string"
}

Get Entitlement License

Get the details for a specific license.

path Parameters
license_id
required
string

ID of the license.

Responses

Response samples

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

Get License Allocations

Get the devices this license is allocated to. Only licenses with an allocation limit can be allocated to a device, so licenses that are for all devices in an org or a specific serial number will return an empty list.

path Parameters
license_id
required
string

ID of the license.

query Parameters
pagination_size
integer [ 1 .. 60 ]
Default: 50

The pagination size for the request. This is the maximum number of objects to return in the request.

pagination_token
string non-empty

Search results are paginated, up to 1MB of data or the client-defined amount (pagination_size), whichever is lower. If one of those limits is exceeded, the response will include a token to retrieve the next page. If you have a pagination token from a previous request, pass it in here (all other parameters the same) to get the next page. It may be necessary to repeat the call several times to obtain the full set of search results. When pagination_token is null or missing from the response, you have reached the end of the results.

Responses

Response samples

Content type
application/json
{
  • "allocations": [
    ],
  • "pagination_token": "string"
}

Allocate Device Licenses

Allocate a license to a device. Only licenses with an allocation limit can be allocated to a device.

path Parameters
license_id
required
string

ID of the licenses.

Request Body schema: application/json
devices
required
Array of strings

List of device GUIDs to allocate the license to.

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "message": "string",
  • "failed_devices": [
    ]
}

Delete License Allocations

Remove a license allocation from a device. Only licenses with an allocation limit can be allocated to a device.

path Parameters
license_id
required
string

ID of the license.

Request Body schema: application/json
devices
required
Array of strings

List of device GUIDs to remove the license from.

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "message": "string",
  • "failed_devices": [
    ]
}

Get Entitlement Profiles

Get the available entitlement profiles.

query Parameters
pagination_size
integer [ 1 .. 60 ]
Default: 50

The pagination size for the request. This is the maximum number of objects to return in the request.

pagination_token
string non-empty

Search results are paginated, up to 1MB of data or the client-defined amount (pagination_size), whichever is lower. If one of those limits is exceeded, the response will include a token to retrieve the next page. If you have a pagination token from a previous request, pass it in here (all other parameters the same) to get the next page. It may be necessary to repeat the call several times to obtain the full set of search results. When pagination_token is null or missing from the response, you have reached the end of the results.

Responses

Response samples

Content type
application/json
{
  • "profiles": [
    ],
  • "pagination_token": "string"
}

Get Entitlement Profile Details

Get the details for a specific entitlement profile.

path Parameters
profile_guid
required
string

GUID of the profile.

Responses

Response samples

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

fleets

View and Manage Fleets

Find Fleets

Search for fleets based on the specified attributes. Note that search results will exclude fleets that you do not have access to.

query Parameters
org_guid
string

GUID of an organization to filter fleet results by. If both Org-Guid and org_guid are present, org_guid is used.

fleet_name
string

Fleet name to search for, can be a full or partial name. Searches are case-insensitive, and substrings will match. For example, a search for "labs" will match "Videon Labs, Inc.".

user_guid
string

GUID of a user to filter fleet results by. If present, org_guid is ignored. If org_guid/Org-Guid and user_guid are not present, defaults to your user GUID. Only fleets that the user is directly assigned to will be returned.

pagination_size
integer [ 1 .. 60 ]
Default: 50

The pagination size for the request. This is the maximum number of objects to return in the request.

pagination_token
string non-empty

Search results are paginated, up to 1MB of data or the client-defined amount (pagination_size), whichever is lower. If one of those limits is exceeded, the response will include a token to retrieve the next page. If you have a pagination token from a previous request, pass it in here (all other parameters the same) to get the next page. It may be necessary to repeat the call several times to obtain the full set of search results. When pagination_token is null or missing from the response, you have reached the end of the results.

header Parameters
Org-Guid
string

GUID of an organization to filter fleet results by. If both Org-Guid and org_guid are present, org_guid is used.

Responses

Response samples

Content type
application/json
{
  • "fleets": [
    ],
  • "pagination_token": "string"
}

Create Fleet

Create a fleet with the attributes specified.

header Parameters
Org-Guid
string

GUID of the organization creating the fleet. Either Org-Guid or org_guid must be present. If both are present, org_guid is used.

Request Body schema: application/json
fleet_name
required
string [ 2 .. 256 ] characters ^\S[^\n\r\t\v\f]*\S$

Fleet name

org_guid
string

GUID of the organization creating the fleet. Either Org-Guid or org_guid must be present. If both are present, org_guid is used.

Responses

Request samples

Content type
application/json
{
  • "fleet_name": "string",
  • "org_guid": "string"
}

Response samples

Content type
application/json
{
  • "message": "string",
  • "fleet_guid": "2dad2a19-f584-4d3f-86ed-41fce8327033"
}

Get Fleet Details

Search for a fleet based on the fleet's GUID.

path Parameters
fleet_guid
required
string

GUID of the fleet.

Responses

Response samples

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

Update Fleet Properties

Update a fleet with the attributes specified in the request body.

path Parameters
fleet_guid
required
string

GUID of the fleet.

Request Body schema: application/json
fleet_name
required
string [ 2 .. 256 ] characters ^\S[^\n\r\t\v\f]*\S$

Fleet name

Responses

Request samples

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

Delete Fleet

Delete a specific fleet. Note that you will be unable to access organizations that you are not a member of.

path Parameters
fleet_guid
required
string

GUID of the fleet.

Request Body schema: application/json
reason
required
string <= 2048 characters

Reason for deletion of fleet

Responses

Request samples

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

Get Fleet Devices

Get the devices for a specific fleet.

path Parameters
fleet_guid
required
string

GUID of the fleet.

query Parameters
pagination_size
integer [ 1 .. 60 ]
Default: 50

The pagination size for the request. This is the maximum number of objects to return in the request.

pagination_token
string non-empty

Search results are paginated, up to 1MB of data or the client-defined amount (pagination_size), whichever is lower. If one of those limits is exceeded, the response will include a token to retrieve the next page. If you have a pagination token from a previous request, pass it in here (all other parameters the same) to get the next page. It may be necessary to repeat the call several times to obtain the full set of search results. When pagination_token is null or missing from the response, you have reached the end of the results.

Responses

Response samples

Content type
application/json
{
  • "devices": [
    ],
  • "pagination_token": "string"
}

Add Fleet Devices

Add devices to a fleet.

path Parameters
fleet_guid
required
string

GUID of the fleet.

Request Body schema: application/json
devices
Array of strings

List of device GUIDs to add to the fleet.

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "message": "string",
  • "failed_devices": [
    ]
}

Delete Fleet Devices

Remove devices from a fleet.

path Parameters
fleet_guid
required
string

GUID of the fleet.

Request Body schema: application/json
devices
Array of strings

List of device GUIDs to remove from the fleet.

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "message": "string",
  • "failed_devices": [
    ]
}

Get Fleet Device Statuses

Get the statuses for devices in a specific fleet.

path Parameters
fleet_guid
required
string

GUID of the fleet.

query Parameters
online
boolean
Default: true

Whether to return devices that are currently online.

streaming
boolean
Default: true

Whether to return devices that are actively streaming.

Responses

Response samples

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

Get Fleet Events

Get fleet events based on the provided attributes. Events are deleted 30 days after they occur.

path Parameters
fleet_guid
required
string

GUID of the fleet.

query Parameters
event_types
Array of strings

Type of events to search for. If omitted, all event types are returned.

start_time
required
string <date-time>

Date and time of the earliest events to return in ISO 8601 format as specified by RFC 3339, Section 5.6.

end_time
string <date-time>

Date and time of the latest events to return in ISO 8601 format as specified by RFC 3339, Section 5.6.

pagination_size
integer [ 1 .. 60 ]
Default: 50

The pagination size for the request. This is the maximum number of objects to return in the request.

pagination_token
string non-empty

Search results are paginated, up to 1MB of data or the client-defined amount (pagination_size), whichever is lower. If one of those limits is exceeded, the response will include a token to retrieve the next page. If you have a pagination token from a previous request, pass it in here (all other parameters the same) to get the next page. It may be necessary to repeat the call several times to obtain the full set of search results. When pagination_token is null or missing from the response, you have reached the end of the results.

Responses

Response samples

Content type
application/json
{
  • "events": [
    ],
  • "pagination_token": "string"
}

Get Fleet Membership Details

Get the users for a specific fleet. Note that you will be unable to access fleets that you are not a member of.

path Parameters
fleet_guid
required
string

GUID of the fleet.

query Parameters
user_guid
string

GUID of a user to filter fleets results by.

pagination_size
integer [ 1 .. 60 ]
Default: 50

The pagination size for the request. This is the maximum number of objects to return in the request.

pagination_token
string non-empty

Search results are paginated, up to 1MB of data or the client-defined amount (pagination_size), whichever is lower. If one of those limits is exceeded, the response will include a token to retrieve the next page. If you have a pagination token from a previous request, pass it in here (all other parameters the same) to get the next page. It may be necessary to repeat the call several times to obtain the full set of search results. When pagination_token is null or missing from the response, you have reached the end of the results.

Responses

Response samples

Content type
application/json
{
  • "users": [
    ],
  • "pagination_token": "string"
}

Create or Add User to Fleet

Add a user to a fleet, or if the user doesn't exist, create and add the user.

path Parameters
fleet_guid
required
string

GUID of the fleet.

Request Body schema: application/json
user_guid
string

User GUID (if adding existing user)

name
string [ 1 .. 2048 ] characters

Full name of the user.

email
string <email> [ 1 .. 128 ] characters

Email address of the user.

password
string [ 6 .. 256 ] characters

Password for the user.

phone_number
string or null

Mobile phone number of the user (optional). Must start with + and country code. Can only contain plus sign and digits.

locale
string <= 2048 characters

User locale in BCP 47 (RFC 5646) format.

zoneinfo
string <= 2048 characters

User time zone in zoneinfo (tz database) format.

access
required
integer

If user_guid was provided, the access level of the requested user. Otherwise, the access level of the current user. (100 = reader, 200 = user, 300 = admin)

Responses

Request samples

Content type
application/json
{
  • "user_guid": "string",
  • "name": "string",
  • "email": "user@example.com",
  • "password": "string",
  • "phone_number": 18142351111,
  • "locale": "en_US",
  • "zoneinfo": "Europe/Paris",
  • "access": 100
}

Response samples

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

Update Fleet Users

Update user permissions within a fleet.

path Parameters
fleet_guid
required
string

GUID of the fleet.

Request Body schema: application/json
Array of objects

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "message": "string",
  • "failed_users": [
    ]
}

Delete Fleet Users

Remove users from a fleet.

path Parameters
fleet_guid
required
string

GUID of the fleet.

Request Body schema: application/json
users
Array of strings

List of user GUIDs to remove from the fleet.

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "message": "string",
  • "failed_users": [
    ]
}

invites

View and Manage Invitations

Find Invites

Search for invites based on the specified search parameters. If no GUID parameters are given, the results will return all invites associated with your user email. Mixing multiple types of GUIDs, e.g., fleet and org GUIDs, will result in an error.

query Parameters
org_guid
string

GUID of the organization to filter invites by.

fleet_guid
string

GUID of the fleet to filter invites by.

device_guid
string

GUID of the device to filter invites by.

pagination_size
integer [ 1 .. 60 ]
Default: 50

The pagination size for the request. This is the maximum number of objects to return in the request.

pagination_token
string non-empty

Search results are paginated, up to 1MB of data or the client-defined amount (pagination_size), whichever is lower. If one of those limits is exceeded, the response will include a token to retrieve the next page. If you have a pagination token from a previous request, pass it in here (all other parameters the same) to get the next page. It may be necessary to repeat the call several times to obtain the full set of search results. When pagination_token is null or missing from the response, you have reached the end of the results.

Responses

Response samples

Content type
application/json
{
  • "invites": [
    ],
  • "pagination_token": "string"
}

Send Invite

Send an invite with the attributes specified. Users can only be invited using one GUID at a time. Request body parameters take precedence over header parameters. Mixing multiple types of GUIDs in the request body, e.g., fleet and org GUIDs, will result in an error.

header Parameters
Org-Guid
string

GUID of the organization to invite the user to.

Request Body schema: application/json
org_guid
string

GUID of the organization to invite the user to.

fleet_guid
string

GUID of the fleet to invite the user to.

device_guid
string

GUID of the device to invite the user to.

target_email
required
string <email>

Email of the user to invite.

access
required
integer

Access level to give the user upon joining the organization.

Responses

Request samples

Content type
application/json
{
  • "org_guid": "string",
  • "fleet_guid": "string",
  • "device_guid": "string",
  • "target_email": "user@example.com",
  • "access": 100
}

Response samples

Content type
application/json
{
  • "message": "string",
  • "invite_guid": "string"
}

Get Invite Details

Get the details for a specific invite.

path Parameters
invite_guid
required
string

GUID of the invite. If you create a new invite, the GUID is returned in the response body. The GUID should be url-encoded to ensure the path is valid.

Responses

Response samples

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

Delete Pending Invite

Delete a pending invite with the attributes specified.

path Parameters
invite_guid
required
string

GUID of the invite. If you create a new invite, the GUID is returned in the response body.

Responses

Accept Invite

Accept an invite to join an organization.

Request Body schema: application/json
invite_guid
required
string

GUID of the invite request.

Responses

Request samples

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

Decline Invite

Decline an invite to join an organization.

Request Body schema: application/json
invite_guid
required
string

GUID of the invite request.

Responses

Request samples

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

organizations

View and Manage Organizations

Find Organizations

Search for organizations based on the specified attribute. Note that search results will exclude organizations that you do not have access to.

query Parameters
org_name
string

Organization name to search for, can be a full or partial name. Searches are case-insensitive, and substrings will match. For example, a search for "labs" will match "Videon Labs, Inc.".

user_guid
string

GUID of a user to filter organization results by.

pagination_size
integer [ 1 .. 60 ]
Default: 50

The pagination size for the request. This is the maximum number of objects to return in the request.

pagination_token
string non-empty

Search results are paginated, up to 1MB of data or the client-defined amount (pagination_size), whichever is lower. If one of those limits is exceeded, the response will include a token to retrieve the next page. If you have a pagination token from a previous request, pass it in here (all other parameters the same) to get the next page. It may be necessary to repeat the call several times to obtain the full set of search results. When pagination_token is null or missing from the response, you have reached the end of the results.

Responses

Response samples

Content type
application/json
{
  • "orgs": [
    ],
  • "pagination_token": "string"
}

Create an Organization

Create an organization with the attributes specified.

Request Body schema: application/json
org_name
required
string [ 2 .. 256 ] characters ^\S[^\n\r\t\v\f]*\S$

Name of the organization.

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "message": "string",
  • "org_guid": "fe2bb349-40d9-4b0f-9f7d-e7a36e968512"
}

Get Organization Details

Get the details for a specific organization. Note that you will be unable to access organizations that you are not a member of.

path Parameters
org_guid
required
string

GUID of the organization.

Responses

Response samples

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

Update Organization Properties

Update the properties of a organization.

path Parameters
org_guid
required
string

GUID of the organization.

Request Body schema: application/json
org_name
required
string [ 2 .. 256 ] characters ^\S[^\n\r\t\v\f]*\S$

Organization name

Responses

Request samples

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

Delete Organization

Selete a specific organization. Note that you will be unable to access organizations that you are not a member of.

path Parameters
org_guid
required
string

GUID of the organization.

Request Body schema: application/json
reason
required
string <= 2048 characters

Reason for deletion of organization

Responses

Request samples

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

Get Organization Events

Get organization events based on the provided attributes. Events are deleted 30 days after they occur.

path Parameters
org_guid
required
string

GUID of the organization.

query Parameters
event_types
Array of strings

Type of events to search for. If omitted, all event types are returned.

start_time
required
string <date-time>

Date and time of the earliest events to return in ISO 8601 format as specified by RFC 3339, Section 5.6.

end_time
string <date-time>

Date and time of the latest events to return in ISO 8601 format as specified by RFC 3339, Section 5.6.

pagination_size
integer [ 1 .. 60 ]
Default: 50

The pagination size for the request. This is the maximum number of objects to return in the request.

pagination_token
string non-empty

Search results are paginated, up to 1MB of data or the client-defined amount (pagination_size), whichever is lower. If one of those limits is exceeded, the response will include a token to retrieve the next page. If you have a pagination token from a previous request, pass it in here (all other parameters the same) to get the next page. It may be necessary to repeat the call several times to obtain the full set of search results. When pagination_token is null or missing from the response, you have reached the end of the results.

Responses

Response samples

Content type
application/json
{
  • "events": [
    ],
  • "pagination_token": "string"
}

Get Organization Device Metadata

Get metadata for all devices in the organization

path Parameters
org_guid
required
string

GUID of the organization.

query Parameters
pagination_size
integer [ 1 .. 60 ]
Default: 50

The pagination size for the request. This is the maximum number of objects to return in the request.

pagination_token
string non-empty

Search results are paginated, up to 1MB of data or the client-defined amount (pagination_size), whichever is lower. If one of those limits is exceeded, the response will include a token to retrieve the next page. If you have a pagination token from a previous request, pass it in here (all other parameters the same) to get the next page. It may be necessary to repeat the call several times to obtain the full set of search results. When pagination_token is null or missing from the response, you have reached the end of the results.

Responses

Response samples

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

Search Organization Device Metadata

Get metadata for all devices in the organization that matches a search term

path Parameters
org_guid
required
string

GUID of the organization.

query Parameters
pagination_size
integer [ 1 .. 60 ]
Default: 50

The pagination size for the request. This is the maximum number of objects to return in the request.

pagination_token
string non-empty

Search results are paginated, up to 1MB of data or the client-defined amount (pagination_size), whichever is lower. If one of those limits is exceeded, the response will include a token to retrieve the next page. If you have a pagination token from a previous request, pass it in here (all other parameters the same) to get the next page. It may be necessary to repeat the call several times to obtain the full set of search results. When pagination_token is null or missing from the response, you have reached the end of the results.

Request Body schema: application/json
search_keys
required
Array of strings

Responses

Request samples

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

Response samples

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

Get Organization Membership Details

Get the users for a specific organization. Note that you will be unable to access organizations that you are not a member of.

path Parameters
org_guid
required
string

GUID of the organization.

query Parameters
user_guid
string

GUID of a user to filter organization results by.

pagination_size
integer [ 1 .. 60 ]
Default: 50

The pagination size for the request. This is the maximum number of objects to return in the request.

pagination_token
string non-empty

Search results are paginated, up to 1MB of data or the client-defined amount (pagination_size), whichever is lower. If one of those limits is exceeded, the response will include a token to retrieve the next page. If you have a pagination token from a previous request, pass it in here (all other parameters the same) to get the next page. It may be necessary to repeat the call several times to obtain the full set of search results. When pagination_token is null or missing from the response, you have reached the end of the results.

Responses

Response samples

Content type
application/json
{
  • "users": [
    ],
  • "pagination_token": "string"
}

Create or add user to Organization

Add a user to an organization, or if the user doesn't exist, create and add the user.

path Parameters
org_guid
required
string

GUID of the organization.

Request Body schema: application/json
user_guid
string

User GUID (if adding existing user)

name
string [ 1 .. 2048 ] characters

Full name of the user.

email
string <email> [ 1 .. 128 ] characters

Email address of the user.

password
string [ 6 .. 256 ] characters

Password for the user.

phone_number
string or null

Mobile phone number of the user (optional). Must start with + and country code. Can only contain plus sign and digits.

locale
string <= 2048 characters

User locale in BCP 47 (RFC 5646) format.

zoneinfo
string <= 2048 characters

User time zone in zoneinfo (tz database) format.

access
required
integer

If user_guid was provided, the access level of the requested user. Otherwise, the access level of the current user. (100 = reader, 200 = user, 300 = admin)

Responses

Request samples

Content type
application/json
{
  • "user_guid": "string",
  • "name": "string",
  • "email": "user@example.com",
  • "password": "string",
  • "phone_number": 18142351111,
  • "locale": "en_US",
  • "zoneinfo": "Europe/Paris",
  • "access": 100
}

Response samples

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

Update Organization Users

Update user permissions within an organization.

path Parameters
org_guid
required
string

GUID of the organization.

Request Body schema: application/json
Array of objects

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "message": "string",
  • "failed_users": [
    ]
}

Delete Organization Users

Remove users from an organization.

path Parameters
org_guid
required
string

GUID of the organization.

Request Body schema: application/json
users
Array of strings

List of user GUIDs to remove from the organization.

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "message": "string",
  • "failed_users": [
    ]
}

users

View and Manage Users

Get User Details

Get the details for a specific user. Note that you will be unable to access users that are not a member of your organization/fleet. When looking up other users only their name, picture, and user_guid will be returned.

path Parameters
user_guid
required
string

GUID of the user. You can use 'me' in place of your own user GUID.

Responses

Response samples

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

Update User Properties

Update the properties of a user. Note that user accounts are largely self-managed, so the primary use-case is to edit your own properties.

path Parameters
user_guid
required
string

GUID of the user. You can use 'me' in place of your own user GUID.

Request Body schema: application/json
name
string

Full name of the user.

email
string <email>

Email address of the user.

phone_number
string

Mobile phone number of the user.

locale
string

User locale in BCP 47 (RFC 5646) format.

zoneinfo
string

User time zone in zoneinfo/tz format.

enabled
boolean

True if the user account is enabled.

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "email": "user@example.com",
  • "phone_number": "string",
  • "locale": "en_US",
  • "zoneinfo": "string",
  • "enabled": true
}

Response samples

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

Delete User

The presence of this endpoint allows us to comply with GDPR and similar privacy laws. Use this to handle “right to be forgotten” requests. Note that user accounts are largely self-managed, so the primary use-case is to delete your own account.

path Parameters
user_guid
required
string

GUID of the user. You can use 'me' in place of your own user GUID.

Request Body schema: application/json
reason
required
string <= 2048 characters

Reason for deletion of user

Responses

Request samples

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