Skip to main content
API docs by Redocly

Peridio Admin API (v1)

Download OpenAPI specification:Download

License: Peridio

Expanding Responses

Some endpoints are able to return more data than they normally do by expanding their response. When this is possible the endpoint will specify the expand field and will document which fields can be expanded. The expand field takes an array of string field names that identify which fields you wish to expand.

Expanding Fields

To expand a single field, you may specify it as part of the query.

For example:

/example-endpoint?expand[]=bar

This will cause the bar key and its value to be included in the response. If bar itself has expandable fields, see path expands.

Path Expands

If the field you wish to expand is not a top level key within the response, you may specify it using dot notation.

For example:

/example-endpoint?expand[]=foo.bar

If foo itself is not an expandable field, this will work like a normal field expand. The bar key and its value will be included in the response nested under the foo key.

If foo is an expandable field, see nested expands.

Expanding Multiple Fields

To expand more than one field, you may add additional expands to the query.

For example:

/example-endpoint?expand[]=bar&expand[]=baz

Nested Expands

If you are already expanding a field, foo, and it has its own expandable field(s), bar, you may additionally expand bar as follows.

/example-endpoint?expand[]=foo&expand[]=foo.bar

The foo key and its value will be included in the response. Additionally, The bar key and its value will be included in the response nested under the foo key.

If you wish to expand the bar key, but are not interested in the other keys on foo, see granular expands.

Granular Expands

If foo is an expandable field whose keys you are not interested in except for its own expandable field bar, you may do the following.

/example-endpoint?expand[]=foo.bar

The foo key will exist, but its value will only have the bar key, discluding all other sibling keys you did not explicitly ask for.

Search Query Language

Some endpoints specify a search parameter. The value of this parameter must be a string that contains a valid query as defined by this search query language.

IMPORTANT NOTICE

Every list-type endpoint that accepts a search parameter requires that the search parameter is supplied, and furthermore that an organization PRN clause is provided in the search like so: organization_prn:'value'.

Queries

A query consists of at least one and at most five clauses joined by the and keyword.

For example:

inserted_at>='2023-01-01T00:00:00Z' and description~'east blue'

Clauses

A clause consists of a key, an operator, and a value.

For example:

inserted_at>='2023-01-01T00:00:00Z'

Keys

When performing a search, the set of valid keys is defined by the relevant endpoint's search parameter's documentation.

Operators

Each key an endpoint specifies as searchable will be associated with a set of operators that are valid to use with it. Below are all possible operators and their associated operation:

Keyword Operation
: equals (case-sensitive)
- substring (case-insensitive)
~ substring (case-sensitive)
< less than
<= less than or equal to
> greater than
>= greater than or equal to

Values

Each key will specify which type of value it acepts.

String

You must use single quotes when supplying a string. You can escape single quotes inside of single quotes with a backslash (\).

For example:

summary~'zoro\'s three sword style'

Boolean

Boolean values are supplied either true or false without single quotes.

For example:

archived:true

Date-Time

You must use single quotes when supplying a date-time and you must use the following representation: '[YYYY]-[MM]-[DD]T[HH]:[MM]:[SS]Z'. The timezone is always UTC.

For example:

inserted_at:'2023-01-01T00:00:00Z'

Numeric

Numeric values are supplied as-is without single quotes.

For example:

berries:100000000

Organization Users

List organization users

Authorizations:
api_key
path Parameters
organization_name
required
string

Responses

Response samples

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

Add an organization user

Authorizations:
api_key
path Parameters
organization_name
required
string
Request Body schema: application/json
required
role
required
any (role-name)
Enum: "admin" "read" "read" "write"
username
required
string (user-username)

Responses

Request samples

Content type
application/json
{
  • "role": "admin",
  • "username": "string"
}

Response samples

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

Remove an organization user

Authorizations:
api_key
path Parameters
organization_name
required
string (organization-name)
user_username
required
string (user-username)

Responses

Retrieve an organization user

Authorizations:
api_key
path Parameters
organization_name
required
string (organization-name)
user_username
required
string (user-username)

Responses

Response samples

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

Update an organization user

Authorizations:
api_key
path Parameters
organization_name
required
string (organization-name)
user_username
required
string (user-username)
Request Body schema: application/json
required
role
required
any (role-name)
Enum: "admin" "read" "read" "write"

Responses

Request samples

Content type
application/json
{
  • "role": "admin"
}

Response samples

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

Product Users

List product users

Authorizations:
api_key
path Parameters
organization_name
required
string (organization-name)
product_name
required
string (product-name)

Uniquely identifies a product within an organization.

Responses

Response samples

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

Add a product user

Authorizations:
api_key
path Parameters
organization_name
required
string (organization-name)
product_name
required
string (product-name)

Uniquely identifies a product within an organization.

Request Body schema: application/json
required
role
required
any (role-name)
Enum: "admin" "read" "read" "write"
username
required
string (user-username)

Responses

Request samples

Content type
application/json
{
  • "role": "admin",
  • "username": "string"
}

Response samples

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

Remove a product user

Authorizations:
api_key
path Parameters
organization_name
required
string (organization-name)
product_name
required
string (product-name)

Uniquely identifies a product within an organization.

user_username
required
string (user-username)

Responses

Retrieve a product user

Authorizations:
api_key
path Parameters
organization_name
required
string (organization-name)
product_name
required
string (product-name)

Uniquely identifies a product within an organization.

user_username
required
string (user-username)

Responses

Response samples

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

Update a product user

Authorizations:
api_key
path Parameters
organization_name
required
string (organization-name)
product_name
required
string (product-name)

Uniquely identifies a product within an organization.

user_username
required
string (user-username)
Request Body schema: application/json
required
role
required
any (role-name)
Enum: "admin" "read" "read" "write"

Responses

Request samples

Content type
application/json
{
  • "role": "admin"
}

Response samples

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

Users

Authenticate a user

Authorizations:
api_key
Request Body schema: application/json
required
Any of
email
string <email> (email)
password
required
string (user-password)
username
required
string

Responses

Request samples

Content type
application/json
{
  • "email": "user@example.com",
  • "password": "string",
  • "username": "string"
}

Response samples

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

Login a user

Authorizations:
api_key
Request Body schema: application/json
required
One of
email
string <email> (email)
note
required
string
password
required
string (user-password)
username
required
string

Responses

Request samples

Content type
application/json
{
  • "email": "user@example.com",
  • "note": "string",
  • "password": "string",
  • "username": "string"
}

Response samples

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

Get user me

Authorizations:
api_key

Responses

Response samples

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

Register a user

Authorizations:
api_key
Request Body schema: application/json
required
email
required
string <email> (email)
password
required
string (user-password)
username
required
string (user-username)

Responses

Request samples

Content type
application/json
{
  • "email": "user@example.com",
  • "password": "string",
  • "username": "string"
}

Response samples

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

Artifacts

Create an artifact

Authorizations:
api_key
Request Body schema: application/json
required
description
string (artifact-description) [ 1 .. 256 ] characters
name
required
string (artifact-name) [ 1 .. 128 ] characters
organization_prn
required
string (prn)

Peridio Resource Names (PRNs) uniquely identify Peridio resources.

Responses

Request samples

Content type
application/json
{
  • "description": "string",
  • "name": "string",
  • "organization_prn": "string"
}

Response samples

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

List artifacts

Search

This resource has the following searchable fields.

Key Required Operators Value
description :, ~ string
inserted_at :, >, >=, <, <= date-time
name :, ~ string
organization_prn X : prn
prn : string
updated_at :, >, >=, <, <= date-time
Authorizations:
api_key
query Parameters
limit
integer [ 1 .. 100 ]
Default: 10

Specifies the max length of the returned results.

order
string
Enum: "asc" "desc"

Controls whether the order of results is ascending or descending by inserted_at.

search
required
string

A search query per the search query language.

page
string

A cursor for pagination across multiple pages of results. Don't include this parameter on the first call. Use the next_page value returned in a previous response to request subsequent results.

Responses

Response samples

Content type
application/json
{
  • "artifacts": [
    ],
  • "next_page": "string"
}

Retrieve an artifact

Authorizations:
api_key
path Parameters
artifact_prn
required
string (prn)

Peridio Resource Names (PRNs) uniquely identify Peridio resources.

Responses

Response samples

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

Update an artifact

Authorizations:
api_key
path Parameters
artifact_prn
required
string (prn)

Peridio Resource Names (PRNs) uniquely identify Peridio resources.

Request Body schema: application/json
required
description
string (artifact-description) [ 1 .. 256 ] characters
name
string (artifact-name) [ 1 .. 128 ] characters

Responses

Request samples

Content type
application/json
{
  • "description": "string",
  • "name": "string"
}

Response samples

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

Artifact Versions

Create an artifact version

Authorizations:
api_key
Request Body schema: application/json
required
artifact_prn
required
string (prn)

Peridio Resource Names (PRNs) uniquely identify Peridio resources.

description
string (artifact-version-description) [ 1 .. 256 ] characters
version
required
string (artifact-version-version) [ 1 .. 128 ] characters

Responses

Request samples

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

Response samples

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

List artifact versions

Search

This resource has the following searchable fields.

Key Required Operators Value
artifact_prn : string
description :, ~ string
inserted_at :, >, >=, <, <= date-time
name :, ~ string
organization_prn X : prn
prn : string
updated_at :, >, >=, <, <= date-time
Authorizations:
api_key
query Parameters
limit
integer [ 1 .. 100 ]
Default: 10

Specifies the max length of the returned results.

order
string
Enum: "asc" "desc"

Controls whether the order of results is ascending or descending by inserted_at.

search
required
string

A search query per the search query language.

page
string

A cursor for pagination across multiple pages of results. Don't include this parameter on the first call. Use the next_page value returned in a previous response to request subsequent results.

Responses

Response samples

Content type
application/json
{
  • "artifact_versions": [
    ],
  • "next_page": "string"
}

Retrieve artifact version

Authorizations:
api_key
path Parameters
artifact_version_prn
required
string (prn)

Peridio Resource Names (PRNs) uniquely identify Peridio resources.

Responses

Response samples

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

Update an artifact version

Authorizations:
api_key
path Parameters
artifact_version_prn
required
string (prn)

Peridio Resource Names (PRNs) uniquely identify Peridio resources.

Request Body schema: application/json
required
description
string (artifact-version-description) [ 1 .. 256 ] characters

Responses

Request samples

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

Response samples

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

Binaries

Create a binary

Create a binary record.

Authorizations:
api_key
Request Body schema: application/json
required
artifact_version_prn
required
string (prn)

Peridio Resource Names (PRNs) uniquely identify Peridio resources.

description
string (binary-description) [ 1 .. 256 ] characters
hash
required
string (binary-hash)

The base64 encoding of the SHA256 hash of the binary's data.

size
required
integer (binary-size) [ 0 .. 53687091200000 ]

The expected size in bytes of the binary.

target
required
string (target-triplet) [ 1 .. 128 ] characters

A target triplet string that specifies compaitibility between binaries and devices.

Responses

Request samples

Content type
application/json
{
  • "artifact_version_prn": "string",
  • "description": "string",
  • "hash": "string",
  • "size": 1800000,
  • "target": "arm-linux-androideabi"
}

Response samples

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

List binaries

Search

This resource has the following searchable fields.

Key Required Operators Value
artifact_version_prn : string
description :, ~ string
hash : string
inserted_at :, >, >=, <, <= date-time
organization_prn X : prn
prn : string
size :, >, >=, <, <= integer
target :, ~ string
updated_at :, >, >=, <, <= date-time
Authorizations:
api_key
query Parameters
limit
integer [ 1 .. 100 ]
Default: 10

Specifies the max length of the returned results.

order
string
Enum: "asc" "desc"

Controls whether the order of results is ascending or descending by inserted_at.

search
required
string

A search query per the search query language.

page
string

A cursor for pagination across multiple pages of results. Don't include this parameter on the first call. Use the next_page value returned in a previous response to request subsequent results.

Responses

Response samples

Content type
application/json
{
  • "binaries": [
    ],
  • "next_page": "string"
}

Retrieve a binary

Authorizations:
api_key
path Parameters
binary_prn
required
string (prn)

Peridio Resource Names (PRNs) uniquely identify Peridio resources.

Responses

Response samples

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

Update a binary

Authorizations:
api_key
path Parameters
binary_prn
required
string (prn)

Peridio Resource Names (PRNs) uniquely identify Peridio resources.

Request Body schema: application/json
required
description
string (binary-description) [ 1 .. 256 ] characters
state
string (binary-state)
Enum: "uploadable" "hashable" "hashing" "signable" "signed" "destroyed"

The binary state

Responses

Request samples

Content type
application/json
{
  • "description": "string",
  • "state": "uploadable"
}

Response samples

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

Binary Parts

Create a Binary Part

Create a binary part.

Authorizations:
api_key
path Parameters
binary_prn
required
string (prn)

Peridio Resource Names (PRNs) uniquely identify Peridio resources.

index
required
integer (binary-part-index)

The binary part index order

Request Body schema: application/json
required
expected_binary_size
required
integer (binary-part-size) [ 5242880 .. 5368709120 ]

The expected size in bytes of the binary part.

hash
required
string (binary-part-hash)

The base64 encoding of the SHA256 hash of the binary part's data.

size
required
integer (binary-part-size) [ 5242880 .. 5368709120 ]

The expected size in bytes of the binary part.

Responses

Request samples

Content type
application/json
{
  • "expected_binary_size": 1800000,
  • "hash": "string",
  • "size": 1800000
}

Response samples

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

List binary parts

Authorizations:
api_key
path Parameters
binary_prn
required
string (prn)

Peridio Resource Names (PRNs) uniquely identify Peridio resources.

Responses

Response samples

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

Binary Signatures

Create a binary signature

Attach a signature to a binary.

This endpoint must be used against a binary that is already uploaded completely. The request will fail if the signature is invalid.

Authorizations:
api_key
Request Body schema: application/json
required
binary_prn
required
string (prn)

Peridio Resource Names (PRNs) uniquely identify Peridio resources.

signing_key_prn
required
string (prn)

Peridio Resource Names (PRNs) uniquely identify Peridio resources.

signature
required
string (binary-signature-signature)

The uppercase hex encoding of the ed25519 signature of the base64 encoding of the SHA256 hash of the binary.

Responses

Request samples

Content type
application/json
{
  • "binary_prn": "string",
  • "signing_key_prn": "string",
  • "signature": "string"
}

Response samples

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

Delete a binary signature

Authorizations:
api_key
path Parameters
binary_signature_prn
required
string (prn)

Peridio Resource Names (PRNs) uniquely identify Peridio resources.

Responses

Keys

Use signing keys instead.

List keys Deprecated

Authorizations:
api_key
path Parameters
organization_name
required
string (organization-name)

Responses

Response samples

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

Create a key Deprecated

Authorizations:
api_key
path Parameters
organization_name
required
string (organization-name)
Request Body schema: application/json
required
key
required
string (key-key)
name
required
string (key-name)

Responses

Request samples

Content type
application/json
{
  • "key": "string",
  • "name": "string"
}

Response samples

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

Delete a key Deprecated

Authorizations:
api_key
path Parameters
organization_name
required
string (organization-name)
key_name
required
string (key-name)

Responses

Retrieve a key Deprecated

Authorizations:
api_key
path Parameters
organization_name
required
string (organization-name)
key_name
required
string (key-name)

Responses

Response samples

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

Signing Keys

Create a signing key

Authorizations:
api_key
Request Body schema: application/json
required
value
required
string (signing-key-value) [ 1 .. 256 ] characters
name
required
string (signing-key-name) [ 1 .. 128 ] characters
organization_prn
required
string (prn)

Peridio Resource Names (PRNs) uniquely identify Peridio resources.

Responses

Request samples

Content type
application/json
{
  • "value": "string",
  • "name": "string",
  • "organization_prn": "string"
}

Response samples

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

List signing keys

Search

This resource has the following searchable fields.

Key Required Operators Value
inserted_at :, >, >=, <, <= date-time
name :, ~ string
organization_prn X : prn
prn : string
updated_at :, >, >=, <, <= date-time
value : string
Authorizations:
api_key
query Parameters
limit
integer [ 1 .. 100 ]
Default: 10

Specifies the max length of the returned results.

order
string
Enum: "asc" "desc"

Controls whether the order of results is ascending or descending by inserted_at.

search
required
string

A search query per the search query language.

page
string

A cursor for pagination across multiple pages of results. Don't include this parameter on the first call. Use the next_page value returned in a previous response to request subsequent results.

Responses

Response samples

Content type
application/json
{
  • "signing_keys": [
    ],
  • "next_page": "string"
}

Retrieve a signing key

Authorizations:
api_key
path Parameters
signing_key_prn
required
string (prn)

Peridio Resource Names (PRNs) uniquely identify Peridio resources.

Responses

Response samples

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

Update a signing key

Authorizations:
api_key
path Parameters
signing_key_prn
required
string (prn)

Peridio Resource Names (PRNs) uniquely identify Peridio resources.

Request Body schema: application/json
required
value
string (signing-key-value) [ 1 .. 256 ] characters
name
string (signing-key-name) [ 1 .. 128 ] characters

Responses

Request samples

Content type
application/json
{
  • "value": "string",
  • "name": "string"
}

Response samples

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

Delete a signing key

Authorizations:
api_key
path Parameters
signing_key_prn
required
string (prn)

Peridio Resource Names (PRNs) uniquely identify Peridio resources.

Responses

Response samples

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

Firmware

Legacy

This functionality is only available to select organizations participating in the Peridio closed beta program.

Subject to breaking changes prior to general availability.

For more information, see content labels.

This functionality has been superceded by [artifacts](#artifacts), [artifact versions](#artifact-versions), and [binaries](#binaries).

List firmware

Authorizations:
api_key
path Parameters
organization_name
required
string (organization-name)
product_name
required
string (product-name)

Uniquely identifies a product within an organization.

Responses

Response samples

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

Create a firmware

Authorizations:
api_key
path Parameters
organization_name
required
string (organization-name)
product_name
required
string (product-name)

Uniquely identifies a product within an organization.

Request Body schema: multipart/form-data
firmware
required
string <binary>
ttl
integer

Responses

Response samples

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

Delete a firmware

Authorizations:
api_key
path Parameters
organization_name
required
string (organization-name)
product_name
required
string (product-name)

Uniquely identifies a product within an organization.

firmware_uuid
required
string <uuid> (firmware-uuid)

Uniquely identifies a firmware.

Responses

Response samples

Content type
application/json
{
  • "architecture": "string",
  • "author": "string",
  • "inserted_at": "2019-08-24T14:15:22Z",
  • "platform": "string",
  • "product": "string",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
  • "vcs_identifier": "d670460b4b4aece5915caf5c68d12f560a9fe3e4",
  • "version": "1.0.0-alpha.3"
}

Retrieve a firmware

Expandable

This endpoint has an expandable response. See expanding responses.

Authorizations:
api_key
path Parameters
organization_name
required
string (organization-name)
product_name
required
string (product-name)

Uniquely identifies a product within an organization.

firmware_uuid
required
string <uuid> (firmware-uuid)

Uniquely identifies a firmware.

query Parameters
expand
Array of strings

See expanding responses.

Expandable Fields

For more information on each field, reference the response.

  • url

Responses

Response samples

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

Tunnels

Labs

This functionality is only available to select organizations participating in the Peridio closed beta program.

Subject to breaking changes prior to general availability.

For more information, see content labels.

Create a tunnel

Create a tunnel to a device for remote access.

Labs

The tunnel is available via a public IP address and port for a configurable amount of time. Anyone can send data through the tunnel and it is your responsibility to enforce authentication and authorization if desired.

Authorizations:
api_key
Request Body schema: application/json
required
device_prn
string (device-prn)

Identifies which device to create a tunnel for.

ttl
integer [ 0 .. 3600 ]
Default: 3600

The amount of time in seconds that the tunnel is available for.

Responses

Request samples

Content type
application/json
{
  • "device_prn": "prn:1:be4d30b4-de6b-47cd-85ea-a75e23fd63ef:device:b3f1f699-3bc8-4c77-bda2-b974595d5e3f",
  • "ttl": 3600
}

Response samples

Content type
application/json
{
  • "device_proxy_ip_address": "10.0.1.1",
  • "device_proxy_port": 47539,
  • "device_public_key": "Y4nCIXdpb+f3WgPi0377FDPCAfP+st82s98lTRepHEk=",
  • "device_tunnel_port": 22,
  • "server_proxy_ip_address": "10.0.0.1",
  • "server_proxy_port": 49293,
  • "server_tunnel_ip_address": "3.82.23.99",
  • "server_tunnel_port": 47532,
  • "server_public_key": "2+h9vwIwg/1zTW9XLFzUmiTwCRRq7mzLgDnZfWEislY=",
  • "expires_at": "2019-08-24T14:15:22Z",
  • "prn": "prn:1:be4d30b4-de6b-47cd-85ea-a75e23fd63ef:tunnel:b3f1f699-3bc8-4c77-bda2-b974595d5e3f"
}

Web Console

Create a web console shell

Create a self-authenticating, one-time use, expiring URL to a device remote shell in the Peridio web console.

Once a request is made to the returned URL, it cannot be used again. For example, refreshing the page will fail.

You must supply either:

  • device_prn

Or:

  • device_identifier and organization_prn
Authorizations:
api_key
Request Body schema: application/json
required
device_identifier
string (device-identifier)

Identifies which device to create a web console shell for.

Mutually exclusive with device_prn.

device_prn
string (device-prn)

Identifies which device to create a web console shell for.

Mutually exclusive with device_identifier.

organization_prn
string (device-prn)

Identifies which organization the device belongs to if supplying device_identifier. This param is unnecessary if you supply the device_prn param.

Mutually exclusive with device_prn.

ttl
integer [ 0 .. 86400 ]
Default: 3600

The amount of time in seconds that the URL is valid for. Open connections are closed automatically upon expiration.

Responses

Request samples

Content type
application/json
{
  • "device_identifier": "sn1234",
  • "device_prn": "prn:1:be4d30b4-de6b-47cd-85ea-a75e23fd63ef:device:b3f1f699-3bc8-4c77-bda2-b974595d5e3f",
  • "organization_prn": "prn:1:be4d30b4-de6b-47cd-85ea-a75e23fd63ef:device:b3f1f699-3bc8-4c77-bda2-b974595d5e3f",
  • "ttl": 3600
}

CA Certificates

List CA certificates

Authorizations:
api_key
path Parameters
organization_name
required
string (organization-name)

Responses

Response samples

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

Create a CA certificate

Authorizations:
api_key
path Parameters
organization_name
required
string (organization-name)
Request Body schema: application/json
required
certificate
required
string

Base64 encoded CA certificate.

verification_certificate
required
string

Base64 encoded verification certificate. See: create-a-ca-verification-code

description
string
object (ca-jitp)

Responses

Request samples

Content type
application/json
{
  • "certificate": "string",
  • "verification_certificate": "string",
  • "description": "string",
  • "jitp": {
    }
}

Response samples

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

Delete a CA certificate

Authorizations:
api_key
path Parameters
organization_name
required
string (organization-name)
ca_certificate_serial
required
string (ca-certificate-serial)
Example: 522154175989108335861639249273408275957749326848

Responses

Retrieve a CA certificate

Authorizations:
api_key
path Parameters
organization_name
required
string (organization-name)
ca_certificate_serial
required
string (ca-certificate-serial)
Example: 522154175989108335861639249273408275957749326848

Responses

Response samples

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

Update CA certificate

Authorizations:
api_key
path Parameters
organization_name
required
string (organization-name)
ca_certificate_serial
required
string (ca-certificate-serial)
Example: 522154175989108335861639249273408275957749326848
Request Body schema: application/json
required
description
string
object (ca-jitp)

Responses

Request samples

Content type
application/json
{
  • "description": "string",
  • "jitp": {
    }
}

Response samples

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

Create a CA verification code

Authorizations:
api_key
path Parameters
organization_name
required
string (organization-name)

Responses

Response samples

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

Cohorts

Create a cohort

Authorizations:
api_key
Request Body schema: application/json
required
description
string (cohort-description) [ 1 .. 256 ] characters
name
required
string (cohort-name) [ 1 .. 128 ] characters
organization_prn
required
string (prn)

Peridio Resource Names (PRNs) uniquely identify Peridio resources.

product_prn
required
string (prn)

Peridio Resource Names (PRNs) uniquely identify Peridio resources.

Responses

Request samples

Content type
application/json
{
  • "description": "string",
  • "name": "string",
  • "organization_prn": "string",
  • "product_prn": "string"
}

Response samples

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

List cohorts

Search

This resource has the following searchable fields.

Key Required Operators Value
description :, ~ string
inserted_at :, >, >=, <, <= date-time
name :, ~ string
organization_prn X : prn
prn : string
updated_at :, >, >=, <, <= date-time
Authorizations:
api_key
query Parameters
limit
integer [ 1 .. 100 ]
Default: 10

Specifies the max length of the returned results.

order
string
Enum: "asc" "desc"

Controls whether the order of results is ascending or descending by inserted_at.

search
required
string

A search query per the search query language.

page
string

A cursor for pagination across multiple pages of results. Don't include this parameter on the first call. Use the next_page value returned in a previous response to request subsequent results.

Responses

Response samples

Content type
application/json
{
  • "cohorts": [
    ],
  • "next_page": "string"
}

Retrieve a cohort

Authorizations:
api_key
path Parameters
cohort_prn
required
string (prn)

Peridio Resource Names (PRNs) uniquely identify Peridio resources.

Responses

Response samples

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

Update a cohort

Authorizations:
api_key
path Parameters
cohort_prn
required
string (prn)

Peridio Resource Names (PRNs) uniquely identify Peridio resources.

Request Body schema: application/json
required
description
string (cohort-description) [ 1 .. 256 ] characters
name
string (cohort-name) [ 1 .. 128 ] characters

Responses

Request samples

Content type
application/json
{
  • "description": "string",
  • "name": "string"
}

Response samples

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

Device Certificates

List device certificates

Authorizations:
api_key
path Parameters
organization_name
required
string (organization-name)
product_name
required
string (product-name)

Uniquely identifies a product within an organization.

device_identifier
required
string (device-identifier)
Example: sn1234

Uniquely identifies a device within an organization.

Responses

Response samples

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

Create a device certificate

Authorizations:
api_key
path Parameters
organization_name
required
string (organization-name)
product_name
required
string (product-name)

Uniquely identifies a product within an organization.

device_identifier
required
string (device-identifier)
Example: sn1234

Uniquely identifies a device within an organization.

Request Body schema: application/json
required
cert
required
string (device-certificate-pem-base64)

Base64 encoded device certificate pem.

Responses

Request samples

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

Response samples

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

Retrieve a device certificate

Authorizations:
api_key
path Parameters
organization_name
required
string (organization-name)
product_name
required
string (product-name)

Uniquely identifies a product within an organization.

device_identifier
required
string (device-identifier)
Example: sn1234

Uniquely identifies a device within an organization.

certificate_serial
required
string (device-certificate-serial)
Example: 522154175989108335861639249273408275957749326848

Responses

Response samples

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

Delete a device certificate

Authorizations:
api_key
path Parameters
organization_name
required
string (organization-name)
product_name
required
string (product-name)

Uniquely identifies a product within an organization.

device_identifier
required
string (device-identifier)
Example: sn1234

Uniquely identifies a device within an organization.

certificate_serial
required
string (device-certificate-serial)
Example: 522154175989108335861639249273408275957749326848

Responses

Devices

List devices

Authorizations:
api_key
path Parameters
organization_name
required
string (organization-name)
product_name
required
string (product-name)

Uniquely identifies a product within an organization.

Responses

Response samples

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

Create a device

Authorizations:
api_key
path Parameters
organization_name
required
string (organization-name)
product_name
required
string (product-name)

Uniquely identifies a product within an organization.

Request Body schema: application/json
required
cohort_prn
string (device-cohort-prn)

Peridio Resource Names (PRNs) uniquely identify Peridio resources.

description
string (device-description)
healthy
boolean (device-healthy)
identifier
required
string (device-identifier)

Uniquely identifies a device within an organization.

last_communication
string <date-time> (device-last-communication)
tags
Array of strings (array-of-device-tags)
target
string (target-triplet) [ 1 .. 128 ] characters

A target triplet string that specifies compaitibility between binaries and devices.

Responses

Request samples

Content type
application/json
{
  • "cohort_prn": "string",
  • "description": "string",
  • "healthy": true,
  • "identifier": "sn1234",
  • "last_communication": "2019-08-24T14:15:22Z",
  • "tags": [
    ],
  • "target": "arm-linux-androideabi"
}

Response samples

Content type
application/json
{
  • "cohort_prn": "string",
  • "description": { },
  • "firmware_metadata": { },
  • "healthy": { },
  • "identifier": "sn1234",
  • "last_communication": "never",
  • "status": "offline",
  • "tags": { },
  • "version": "1.0.0-alpha.3"
}

Delete a device

Authorizations:
api_key
path Parameters
organization_name
required
string (organization-name)
product_name
required
string (product-name)

Uniquely identifies a product within an organization.

device_identifier
required
string (device-identifier)
Example: sn1234

Uniquely identifies a device within an organization.

Responses

Retrieve a device

Authorizations:
api_key
path Parameters
organization_name
required
string (organization-name)
product_name
required
string (product-name)

Uniquely identifies a product within an organization.

device_identifier
required
string (device-identifier)
Example: sn1234

Uniquely identifies a device within an organization.

Responses

Response samples

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

Update a device

Authorizations:
api_key
path Parameters
organization_name
required
string (organization-name)
product_name
required
string (product-name)

Uniquely identifies a product within an organization.

device_identifier
required
string (device-identifier)
Example: sn1234

Uniquely identifies a device within an organization.

Request Body schema: application/json
required
cohort_prn
string (device-cohort-prn)

Peridio Resource Names (PRNs) uniquely identify Peridio resources.

description
string (device-description)
healthy
boolean (device-healthy)
last_communication
string <date-time> (device-last-communication)
tags
Array of strings (array-of-device-tags)
target
string (target-triplet) [ 1 .. 128 ] characters

A target triplet string that specifies compaitibility between binaries and devices.

Responses

Request samples

Content type
application/json
{
  • "cohort_prn": "string",
  • "description": "string",
  • "healthy": true,
  • "last_communication": "2019-08-24T14:15:22Z",
  • "tags": [
    ],
  • "target": "arm-linux-androideabi"
}

Response samples

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

Authenticate device

Authorizations:
api_key
path Parameters
organization_name
required
string (organization-name)
product_name
required
string (product-name)

Uniquely identifies a product within an organization.

Request Body schema: application/json
required
certificate
required
string (device-certificate-pem-base64)

Base64 encoded device certificate pem.

Responses

Request samples

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

Response samples

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

Products

List products Deprecated

Authorizations:
api_key
path Parameters
organization_name
required
string (organization-name)

Responses

Response samples

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

Create a product Deprecated

Authorizations:
api_key
path Parameters
organization_name
required
string (organization-name)
Request Body schema: application/json
required
name
required
string (product-name)

Uniquely identifies a product within an organization.

Responses

Request samples

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

Response samples

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

Delete a product Deprecated

Authorizations:
api_key
path Parameters
organization_name
required
string (organization-name)
product_name
required
string (product-name)

Uniquely identifies a product within an organization.

Responses

Retrieve a product Deprecated

Authorizations:
api_key
path Parameters
organization_name
required
string (organization-name)
product_name
required
string (product-name)

Uniquely identifies a product within an organization.

Responses

Response samples

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

Update a product Deprecated

Authorizations:
api_key
path Parameters
organization_name
required
string (organization-name)
product_name
required
string (product-name)

Uniquely identifies a product within an organization.

Request Body schema: application/json
required
required
object
name
string (product-name)

Uniquely identifies a product within an organization.

Responses

Request samples

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

Response samples

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

List products v2

Search

This resource has the following searchable fields.

Key Required Operators Value
deleted_at :, >, >=, <, <= date-time
inserted_at :, >, >=, <, <= date-time
name :, ~ string
organization_prn X : prn
prn : string
updated_at :, >, >=, <, <= date-time
Authorizations:
api_key
query Parameters
limit
integer [ 1 .. 100 ]
Default: 10

Specifies the max length of the returned results.

order
string
Enum: "asc" "desc"

Controls whether the order of results is ascending or descending by inserted_at.

search
required
string

A search query per the search query language.

Searchable fields:

Field Type Operations
archived boolean :
inserted_at date-time :, >, >=, <, <=
name string :, ~
organization_prn string :
prn string :
updated_at date-time :, >, >=, <, <=
page
string

A cursor for pagination across multiple pages of results. Don't include this parameter on the first call. Use the next_page value returned in a previous response to request subsequent results.

Responses

Response samples

Content type
application/json
{
  • "products": [
    ],
  • "next_page": "string"
}

Create a product v2

Authorizations:
api_key
Request Body schema: application/json
required
archived
boolean (product-archived)
name
required
string (product-name)

Uniquely identifies a product within an organization.

organization_prn
required
string (prn)

Peridio Resource Names (PRNs) uniquely identify Peridio resources.

Responses

Request samples

Content type
application/json
{
  • "archived": false,
  • "name": "string",
  • "organization_prn": "string"
}

Response samples

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

Retrieve a product v2

Authorizations:
api_key
path Parameters
product_prn
required
string (prn)

Peridio Resource Names (PRNs) uniquely identify Peridio resources.

Responses

Response samples

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

Update a product v2

Authorizations:
api_key
path Parameters
product_prn
required
string (prn)

Peridio Resource Names (PRNs) uniquely identify Peridio resources.

Request Body schema: application/json
required
archived
boolean (product-archived)

A product cannot be archived if any of the following are true:

  • It is associated with any firmware.
  • It is associated with any unarchived devices.
name
string (product-name)

Uniquely identifies a product within an organization.

Responses

Request samples

Content type
application/json
{
  • "archived": false,
  • "name": "string"
}

Response samples

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

Webhooks

Create a webhook

Authorizations:
api_key
Request Body schema: application/json
required
description
string (webhook-description)
url
string (webhook-url)
enabled_events
Array of any (webhook-enabled-events)
Items Enum: "device.release_changed" "webhook.test_fire"
organization_prn
required
string (prn)

Peridio Resource Names (PRNs) uniquely identify Peridio resources.

Responses

Request samples

Content type
application/json
{
  • "description": "string",
  • "url": "string",
  • "enabled_events": [
    ],
  • "organization_prn": "string"
}

Response samples

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

List webhooks

Search

This resource has the following searchable fields.

Key Required Operators Value
description :, ~ string
inserted_at :, >, >=, <, <= date-time
organization_prn X : prn
prn : string
updated_at :, >, >=, <, <= date-time
Authorizations:
api_key
query Parameters
limit
integer [ 1 .. 100 ]
Default: 10

Specifies the max length of the returned results.

order
string
Enum: "asc" "desc"

Controls whether the order of results is ascending or descending by inserted_at.

search
required
string

A search query per the search query language.

page
string

A cursor for pagination across multiple pages of results. Don't include this parameter on the first call. Use the next_page value returned in a previous response to request subsequent results.

Responses

Response samples

Content type
application/json
{
  • "webhooks": [
    ],
  • "next_page": "string"
}

Retrieve a webhook

Authorizations:
api_key
path Parameters
webhook_prn
required
string (prn)

Peridio Resource Names (PRNs) uniquely identify Peridio resources.

Responses

Response samples

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

Update a webhook

Authorizations:
api_key
path Parameters
webhook_prn
required
string (webhook-prn)
Example: prn:1:be4d30b4-de6b-47cd-85ea-a75e23fd63ef:webhook:b3f1f699-3bc8-4c77-bda2-b974595d5e3f

Peridio Resource Names (PRNs) uniquely identify Peridio resources.

Request Body schema: application/json
required
description
string (webhook-description)
url
string (webhook-url)
enabled_events
Array of any (webhook-enabled-events)
Items Enum: "device.release_changed" "webhook.test_fire"
state
any (webhook-state)
Enum: "enabled" "disabled"

Responses

Request samples

Content type
application/json
{
  • "description": "string",
  • "url": "string",
  • "enabled_events": [
    ],
  • "state": "enabled"
}

Response samples

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

Delete a webhook

Authorizations:
api_key
path Parameters
webhook_prn
required
string (webhook-prn)
Example: prn:1:be4d30b4-de6b-47cd-85ea-a75e23fd63ef:webhook:b3f1f699-3bc8-4c77-bda2-b974595d5e3f

Peridio Resource Names (PRNs) uniquely identify Peridio resources.

Responses

Roll a webhook's secret

Authorizations:
api_key
path Parameters
webhook_prn
required
string (prn)

Peridio Resource Names (PRNs) uniquely identify Peridio resources.

Request Body schema: application/json
optional
webhook_ttl
integer (webhook-ttl)

The amount of time in seconds that the old secret and the new secret will co-exist. While they do, dual signature values will be provided with webhook executions. See the webhooks reference.

Responses

Request samples

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

Response samples

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

Test fire a webhook

Authorizations:
api_key
path Parameters
webhook_prn
required
string (prn)

Peridio Resource Names (PRNs) uniquely identify Peridio resources.

Responses

Response samples

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

Bundles

Create a bundle

Authorizations:
api_key
Request Body schema: application/json
required
organization_prn
required
string (prn)

Peridio Resource Names (PRNs) uniquely identify Peridio resources.

artifact_version_prns
required
Array of strings (array-of-artifact-version-prns)
null or string (bundle-name)

Responses

Request samples

Content type
application/json
{
  • "organization_prn": "string",
  • "artifact_version_prns": [
    ],
  • "name": { }
}

Response samples

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

list bundles

Search

This resource has the following searchable fields.

Key Required Operators Value
inserted_at :, >, >=, <, <= date-time
name :, ~, - string
organization_prn X : prn
prn : string
updated_at :, >, >=, <, <= date-time
Authorizations:
api_key
query Parameters
limit
integer [ 1 .. 100 ]
Default: 10

Specifies the max length of the returned results.

order
string
Enum: "asc" "desc"

Controls whether the order of results is ascending or descending by inserted_at.

search
required
string

A search query per the search query language.

page
string

A cursor for pagination across multiple pages of results. Don't include this parameter on the first call. Use the next_page value returned in a previous response to request subsequent results.

Responses

Response samples

Content type
application/json
{
  • "bundles": [
    ],
  • "next_page": "string"
}

Retrieve a bundle

Authorizations:
api_key
path Parameters
bundle_prn
required
string (prn)

Peridio Resource Names (PRNs) uniquely identify Peridio resources.

Responses

Response samples

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

Update a bundle

Authorizations:
api_key
path Parameters
bundle_prn
required
string (prn)

Peridio Resource Names (PRNs) uniquely identify Peridio resources.

Request Body schema: application/json
required
null or string (bundle-name)
One of
null

Responses

Request samples

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

Response samples

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

Deployments

This functionality has been superceded by bundles and releases.

List deployments

Authorizations:
api_key
path Parameters
organization_name
required
string (organization-name)
product_name
required
string (product-name)

Uniquely identifies a product within an organization.

Responses

Response samples

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

Create a deployment

Authorizations:
api_key
path Parameters
organization_name
required
string (organization-name)
product_name
required
string (product-name)

Uniquely identifies a product within an organization.

Request Body schema: application/json
required
required
object (deployment-conditions)
delta_updatable
boolean (delta-updatable)
Default: false
firmware
required
string <uuid> (firmware-uuid)

Uniquely identifies a firmware.

is_active
required
boolean (deployment-is-active)

Must be false.

name
required
string (deployment-name)

Responses

Request samples

Content type
application/json
{
  • "conditions": {
    },
  • "delta_updatable": true,
  • "firmware": "a3a072e2-291e-4454-88c4-f2689e9ad8c7",
  • "is_active": true,
  • "name": "string"
}

Response samples

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

Delete a deployment

Authorizations:
api_key
path Parameters
organization_name
required
string (organization-name)
product_name
required
string (product-name)

Uniquely identifies a product within an organization.

deployment_name
required
string (deployment-name)

Responses

Retrieve a deployment

Authorizations:
api_key
path Parameters
organization_name
required
string (organization-name)
product_name
required
string (product-name)

Uniquely identifies a product within an organization.

deployment_name
required
string (deployment-name)

Responses

Response samples

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

Update a deployment

Authorizations:
api_key
path Parameters
organization_name
required
string (organization-name)
product_name
required
string (product-name)

Uniquely identifies a product within an organization.

deployment_name
required
string (deployment-name)
Request Body schema: application/json
required
required
object
name
string (deployment-name)
object (deployment-conditions)
delta_updatable
boolean (delta-updatable)
firmware
string <uuid> (firmware-uuid)

Uniquely identifies a firmware.

is_active
boolean (deployment-is-active)

Responses

Request samples

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

Response samples

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

Releases

Create a release

Authorizations:
api_key
Request Body schema: application/json
required
bundle_prn
required
string (prn)

The bundle the release will distribute to devices.

phase_mode
string (release-phase-mode)
Default: "numeric"
Enum: "tags" "numeric"

Describes if this release is using tag or numeric based phasing. tags or phase value for resolution

  • tags - Phases rollout of the release according to the phase_tags field.
  • numeric - Phases rollout of the release according to the phase_value field.
phase_tags
Array of strings (release-phase-tags)

Limits by tags the devices that are allowed to update to this release.

Required if: phase_mode is tags.

When phase_mode is tags, this field only allows devices to update to this release if they have at least one of these tags.

phase_value
number (release-phase-value) [ 0 .. 1000000000 ]

Limits by percent or static count the number of devices that are allowed to update to this release.

Required if: phase_mode is numeric.

When phase_mode is numeric, this field only allows devices to update to this release if fewer than a certain number have already updated.

  • Decimals and integers in the range [0, 1] are treated as percents, e.g., to allow 20% of the cohort to update, you would specifiy a phase_value of 0.2.
  • Integers in the range [2, 1,000,000,000] are treated as absolute device counts, e.g., to allow 40 of the cohort's devices to update, you would specifiy a phase_value of 40.

NOTE: 1 is a special value in that it represents 100% and once a release is updated to this value, the phase value can never be changed again.

A release with a phase_value not equal to 1 is considered "phased".

NOTE: There can only ever be a single release that is phased at a time within a cohort. Because of this, if there is already a phased release, it must be "completed" by setting the phase to 1.

cohort_prn
required
string (prn)

The cohort to create the release within, and in turn the cohort it will distribute its bundle to.

string or null (release-description)
name
required
string (release-name)
next_release_prn
string (prn)

If omitted, the release will be created as latest within the cohort. If there is already at least one release in the cohort, then the latest release in that cohort would have its next_release_prn updated to this created release.

If supplied, the release will be created prior to the release identified by next_release_prn. If you wish to insert this release between two other releases, you may additionally supply previous_release_prn. If you supply neither field, it will create the release as the latest automatically.

previous_release_prn
string (prn)

If omitted, next_release_prn will dictate where to create this release within the cohort's release graph.

In order to insert a release between two other releases, next_release_prn is required to be supplied as well. If you supply neither field, it will create the release as the latest automatically.

organization_prn
required
string (prn)

The organization to create the release within.

required
required
boolean (release-required)

If true, this release must be passed through if encountered by a device.

If false, this release will be skipped over when possible (if there are releases configured after it).

schedule_date
required
string <date-time> (release-schedule-availability)

Before this date-time, the release will not be resolvable when checking for updates. You may use this to schedule a future release.

version
string (release-version)

The release version. If provided, it has to be a valid version. Used in dynamic release resolution.

version-requirement
string (release-version-requirement)

The release version requirement. If provided, it has to be a valid requirement. Used in dynamic release resolution.

Responses

Request samples

Content type
application/json
{
  • "bundle_prn": "string",
  • "phase_mode": "tags",
  • "phase_tags": [
    ],
  • "phase_value": 1000000000,
  • "cohort_prn": "string",
  • "description": null,
  • "name": "string",
  • "next_release_prn": "string",
  • "previous_release_prn": "string",
  • "organization_prn": "string",
  • "required": true,
  • "schedule_date": "2019-08-24T14:15:22Z",
  • "version": "1.0.0",
  • "version-requirement": "== 1.0.0"
}

Response samples

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

List Releases

Search

This resource has the following searchable fields.

Key Required Operators Value
cohort_prn : string
deleted_at :, >, >=, <, <= date-time
description :, ~ string
inserted_at :, >, >=, <, <= date-time
name :, ~ string
next_release_prn : string
organization_prn X : prn
prn : string
updated_at :, >, >=, <, <= date-time
version_requirement :, - string
version :, - string
Authorizations:
api_key
query Parameters
limit
integer [ 1 .. 100 ]
Default: 10

Specifies the max length of the returned results.

order
string
Enum: "asc" "desc"

Controls whether the order of results is ascending or descending by inserted_at.

search
required
string

A search query per the search query language.

page
string

A cursor for pagination across multiple pages of results. Don't include this parameter on the first call. Use the next_page value returned in a previous response to request subsequent results.

Responses

Response samples

Content type
application/json
{
  • "next_page": "string",
  • "releases": [
    ]
}

Retrieve a release

Authorizations:
api_key
path Parameters
release_prn
required
string (prn)

Peridio Resource Names (PRNs) uniquely identify Peridio resources.

Responses

Response samples

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

Update a release

Authorizations:
api_key
path Parameters
release_prn
required
string (prn)

Peridio Resource Names (PRNs) uniquely identify Peridio resources.

Request Body schema: application/json
required
string or null (release-description)
name
string (release-name)
next_release_prn
string (prn)

Update the release's next_release_prn. Changes that would result in an invalid release graph are rejected.

phase_mode
string (release-phase-mode)
Enum: "tags" "numeric"

Describes if this release is using tag or numeric based phasing. tags or phase value for resolution

  • tags - Phases rollout of the release according to the phase_tags field.
  • numeric - Phases rollout of the release according to the phase_value field.
phase_tags
Array of strings (release-phase-tags)

Limits by tags the devices that are allowed to update to this release.

Required if: phase_mode is tags.

When phase_mode is tags, this field only allows devices to update to this release if they have at least one of these tags.

phase_value
number (release-phase-value) [ 0 .. 1000000000 ]

Limits by percent or static count the number of devices that are allowed to update to this release.

Required if: phase_mode is numeric.

When phase_mode is numeric, this field only allows devices to update to this release if fewer than a certain number have already updated.

  • Decimals and integers in the range [0, 1] are treated as percents, e.g., to allow 20% of the cohort to update, you would specifiy a phase_value of 0.2.
  • Integers in the range [2, 1,000,000,000] are treated as absolute device counts, e.g., to allow 40 of the cohort's devices to update, you would specifiy a phase_value of 40.

NOTE: 1 is a special value in that it represents 100% and once a release is updated to this value, the phase value can never be changed again.

A release with a phase_value not equal to 1 is considered "phased".

NOTE: There can only ever be a single release that is phased at a time within a cohort. Because of this, if there is already a phased release, it must be "completed" by setting the phase to 1.

required
boolean (release-required)

If true, this release must be passed through if encountered by a device.

If false, this release will be skipped over when possible (if there are releases configured after it).

schedule_date
string <date-time> (release-schedule-availability)

Before this date-time, the release will not be resolvable when checking for updates. You may use this to schedule a future release.

version
string (release-version)

The release version. If provided, it has to be a valid version. Used in dynamic release resolution.

version-requirement
string (release-version-requirement)

The release version requirement. If provided, it has to be a valid requirement. Used in dynamic release resolution.

Responses

Request samples

Content type
application/json
{
  • "description": null,
  • "name": "string",
  • "next_release_prn": "string",
  • "phase_mode": "tags",
  • "phase_tags": [
    ],
  • "phase_value": 1000000000,
  • "required": true,
  • "schedule_date": "2019-08-24T14:15:22Z",
  • "version": "1.0.0",
  • "version-requirement": "== 1.0.0"
}

Response samples

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

Device Events

Events created due to device activity.

Checked for release Webhook

See the webhooks reference for a list of supported events.

This event is created when a device checks for an update with get-update.

header Parameters
peridio-signature
string
Examples:
  • FC825FCAA2E4C2688F075144105B75C2943D8B88AC4B5FAB134F2676A63FB6EF - One signature.
  • FC825FCAA2E4C2688F075144105B75C2943D8B88AC4B5FAB134F2676A63FB6EF,AC4B5FAB134F2676A63FB6EAAC825FCEA2E4C23B8F045134155B55C2943D8B51 - Two signatures while secrets are being rolled.

The webhook signature. See signature verification.

peridio-published-at
string <date-time>

The timestamp of when the event was published (not created). See signature verification.

Request Body schema: application/json
required
object

Data associated with the device event type.

inserted_at
string <date-time>
prn
string (event-prn)

Peridio Resource Names (PRNs) uniquely identify Peridio resources.

type
any
Value: "device"
version
integer
Value: 1

Responses

Request samples

Content type
application/json
{
  • "data": {
    },
  • "inserted_at": "2019-08-24T14:15:22Z",
  • "prn": "prn:1:be4d30b4-de6b-47cd-85ea-a75e23fd63ef:event:e0040f63-4e1c-43e7-880a-d6986a35c499",
  • "type": "device",
  • "version": 1
}

Claimed release Webhook

See the webhooks reference for a list of supported events.

This event is created when a device claims access to a phased release during a get-update.

header Parameters
peridio-signature
string
Examples:
  • FC825FCAA2E4C2688F075144105B75C2943D8B88AC4B5FAB134F2676A63FB6EF - One signature.
  • FC825FCAA2E4C2688F075144105B75C2943D8B88AC4B5FAB134F2676A63FB6EF,AC4B5FAB134F2676A63FB6EAAC825FCEA2E4C23B8F045134155B55C2943D8B51 - Two signatures while secrets are being rolled.

The webhook signature. See signature verification.

peridio-published-at
string <date-time>

The timestamp of when the event was published (not created). See signature verification.

Request Body schema: application/json
required
object

Data associated with the device event type.

inserted_at
string <date-time>
prn
string (event-prn)

Peridio Resource Names (PRNs) uniquely identify Peridio resources.

type
any
Value: "device"
version
integer
Value: 1

Responses

Request samples

Content type
application/json
{
  • "data": {
    },
  • "inserted_at": "2019-08-24T14:15:22Z",
  • "prn": "prn:1:be4d30b4-de6b-47cd-85ea-a75e23fd63ef:event:e0040f63-4e1c-43e7-880a-d6986a35c499",
  • "type": "device",
  • "version": 1
}

Connected Webhook

See the webhooks reference for a list of supported events.

This event is created when a device successfully completes a TLS handshake while connecting to the Peridio Device API.

header Parameters
peridio-signature
string
Examples:
  • FC825FCAA2E4C2688F075144105B75C2943D8B88AC4B5FAB134F2676A63FB6EF - One signature.
  • FC825FCAA2E4C2688F075144105B75C2943D8B88AC4B5FAB134F2676A63FB6EF,AC4B5FAB134F2676A63FB6EAAC825FCEA2E4C23B8F045134155B55C2943D8B51 - Two signatures while secrets are being rolled.

The webhook signature. See signature verification.

peridio-published-at
string <date-time>

The timestamp of when the event was published (not created). See signature verification.

Request Body schema: application/json
required
object

Data associated with the device event type.

inserted_at
string <date-time>
prn
string (event-prn)

Peridio Resource Names (PRNs) uniquely identify Peridio resources.

type
string
Value: "device"
version
integer
Value: 1

Responses

Request samples

Content type
application/json
{
  • "data": {
    },
  • "inserted_at": "2019-08-24T14:15:22Z",
  • "prn": "prn:1:be4d30b4-de6b-47cd-85ea-a75e23fd63ef:event:e0040f63-4e1c-43e7-880a-d6986a35c499",
  • "type": "device",
  • "version": 1
}

Release changed Webhook

See the webhooks reference for a list of supported events.

This event is created when a device informs Peridio of its current release via the peridio-release-prn header, and that release is different than the one Peridio currently had on record. For example, if Peridio thought the device was on release 1, but then the device informed Peridio it was on release 2, then this event would be created going from 1 to 2.

header Parameters
peridio-signature
string
Examples:
  • FC825FCAA2E4C2688F075144105B75C2943D8B88AC4B5FAB134F2676A63FB6EF - One signature.
  • FC825FCAA2E4C2688F075144105B75C2943D8B88AC4B5FAB134F2676A63FB6EF,AC4B5FAB134F2676A63FB6EAAC825FCEA2E4C23B8F045134155B55C2943D8B51 - Two signatures while secrets are being rolled.

The webhook signature. See signature verification.

peridio-published-at
string <date-time>

The timestamp of when the event was published (not created). See signature verification.

Request Body schema: application/json
required
object

Data associated with the device event type.

inserted_at
string <date-time>
prn
string (event-prn)

Peridio Resource Names (PRNs) uniquely identify Peridio resources.

type
string
Value: "device"
version
integer
Value: 1

Responses

Request samples

Content type
application/json
{
  • "data": {
    },
  • "inserted_at": "2019-08-24T14:15:22Z",
  • "prn": "prn:1:be4d30b4-de6b-47cd-85ea-a75e23fd63ef:event:e0040f63-4e1c-43e7-880a-d6986a35c499",
  • "type": "device",
  • "version": 1
}

Updated Webhook

See the webhooks reference for a list of supported events.

This event is created when a device database record is updated.

header Parameters
peridio-signature
string
Examples:
  • FC825FCAA2E4C2688F075144105B75C2943D8B88AC4B5FAB134F2676A63FB6EF - One signature.
  • FC825FCAA2E4C2688F075144105B75C2943D8B88AC4B5FAB134F2676A63FB6EF,AC4B5FAB134F2676A63FB6EAAC825FCEA2E4C23B8F045134155B55C2943D8B51 - Two signatures while secrets are being rolled.

The webhook signature. See signature verification.

peridio-published-at
string <date-time>

The timestamp of when the event was published (not created). See signature verification.

Request Body schema: application/json
required
object

Data associated with the device event type.

inserted_at
string <date-time>
prn
string (event-prn)

Peridio Resource Names (PRNs) uniquely identify Peridio resources.

type
any
Value: "device"
version
integer
Value: 1

Responses

Request samples

Content type
application/json
{
  • "data": {
    },
  • "inserted_at": "2019-08-24T14:15:22Z",
  • "prn": "prn:1:be4d30b4-de6b-47cd-85ea-a75e23fd63ef:event:e0040f63-4e1c-43e7-880a-d6986a35c499",
  • "type": "device",
  • "version": 1
}

Webhook Events

Events created due to webhook activity.

Request failed Webhook

See the webhooks reference for a list of supported events.

This event is created when an attempt to publish an event via a webhook fails.

header Parameters
peridio-signature
string
Examples:
  • FC825FCAA2E4C2688F075144105B75C2943D8B88AC4B5FAB134F2676A63FB6EF - One signature.
  • FC825FCAA2E4C2688F075144105B75C2943D8B88AC4B5FAB134F2676A63FB6EF,AC4B5FAB134F2676A63FB6EAAC825FCEA2E4C23B8F045134155B55C2943D8B51 - Two signatures while secrets are being rolled.

The webhook signature. See signature verification.

peridio-published-at
string <date-time>

The timestamp of when the event was published (not created). See signature verification.

Request Body schema: application/json
required
object

Data associated with the webhook event type.

inserted_at
string <date-time>
prn
string (event-prn)

Peridio Resource Names (PRNs) uniquely identify Peridio resources.

type
string
Value: "webhook"
version
integer
Value: 1

Responses

Request samples

Content type
application/json
{
  • "data": {
    },
  • "inserted_at": "2019-08-24T14:15:22Z",
  • "prn": "prn:1:be4d30b4-de6b-47cd-85ea-a75e23fd63ef:event:e0040f63-4e1c-43e7-880a-d6986a35c499",
  • "type": "webhook",
  • "version": 1
}

Test fire Webhook

See the webhooks reference for a list of supported events.

This event is created by the Peridio API test-fire-webhook endpoint as well as during URL verification.

header Parameters
peridio-signature
string
Examples:
  • FC825FCAA2E4C2688F075144105B75C2943D8B88AC4B5FAB134F2676A63FB6EF - One signature.
  • FC825FCAA2E4C2688F075144105B75C2943D8B88AC4B5FAB134F2676A63FB6EF,AC4B5FAB134F2676A63FB6EAAC825FCEA2E4C23B8F045134155B55C2943D8B51 - Two signatures while secrets are being rolled.

The webhook signature. See signature verification.

peridio-published-at
string <date-time>

The timestamp of when the event was published (not created). See signature verification.

Request Body schema: application/json
required
object

Data associated with the webhook event type.

inserted_at
string <date-time>
prn
string (event-prn)

Peridio Resource Names (PRNs) uniquely identify Peridio resources.

type
string
Value: "webhook"
version
integer
Value: 1

Responses

Request samples

Content type
application/json
{
  • "data": {
    },
  • "inserted_at": "2019-08-24T14:15:22Z",
  • "prn": "prn:1:be4d30b4-de6b-47cd-85ea-a75e23fd63ef:event:e0040f63-4e1c-43e7-880a-d6986a35c499",
  • "type": "webhook",
  • "version": 1
}