Skip to main content
API docs by Redocly

Peridio Device API (1.0.0)

Download OpenAPI specification:Download

License: Peridio

The Peridio Device API is the primary way for devices to interact with Peridio.

Global Headers

The following headers may be supplied when requesting any endpoint.

key value description
peridio-release-prn A release PRN. See release resolution. Informs Peridio of what release is currently active on the device. The preference should always be to supply this header with a valid value. If you supply this header, you should not supply the peridio-release-version header.
peridio-release-version A release version. See release resolution. This header is only used in exceptional cases when you don't have a PRN to supply via peridio-release-prn. In that case, you may supply this header and you should not supply the peridio-release-prn header.
peridio-bundle-prn A bundle PRN. See release resolution. Informs Peridio of what bundle is currently active on the device. This header is used when the device has a bundle override, and therefore no release. If you supply this header, you should not supply the peridio-release-prn or peridio-release-version header.
x-peridio-architecture A firmware architecture. Legacy. See deployment eligibility. The architecture of the device's currently active firmware. When supplying any x-peridio header, you should supply all x-peridio headers.
x-peridio-platform A firmware platform. Legacy. See deployment eligibility. The platform of the device's currently active firmware. When supplying any x-peridio header, you should supply all x-peridio headers.
x-peridio-product A firmware product. Legacy. See deployment eligibility. The product of the device's currently active firmware. When supplying any x-peridio header, you should supply all x-peridio headers.
x-peridio-uuid A firmware UUID. Legacy. See deployment eligibility. The UUID of the device's currently active firmware. When supplying any x-peridio header, you should supply all x-peridio headers.
x-peridio-version A firmware version. Legacy. See deployment eligibility. The version of the device's currently active firmware. When supplying any x-peridio header, you should supply all x-peridio headers.

Devices

get device me

Returns information about the device identified by the request's authentication.

Expandable

This endpoint has an expandable response. See expanding responses.

Authorizations:
MutualTLS
query Parameters
expand
Array of strings

See expanding responses.

Expandable Fields

For more information on each field, reference the response.

  • cohort
  • manifest
    • artifact
    • artifact_version
    • binary_prn
    • custom_metadata
    • hash
    • signatures
    • size
    • target
    • url
header Parameters
peridio-release-prn
string (prn)
Examples: prn:1:a1ed0c4e-f222-4bb3-89dc-48320018875d:release:e4bf3021-b8d7-42d5-a1bd-52121427ebd0
peridio-release-version
string (release-version)
Example: 1.0.0

Responses

Response samples

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

get device update

This functionality has been superceded by get update.

Returns information regarding whether an update is available via a deployment.

If an update is available, additional information describing the update is returned including a presigned URL to acquire the update.

Authorizations:
MutualTLS
query Parameters
preflight
boolean
Default: false

When false

The request will count towards update attempts. firmware_url in the response will be set to a presigned URL.

When true

The request will not count towards update attempts. firmware_url in the response will be null.

For example, one may use true to check if an update is available when you don't yet intend to consume the update so that a device does not rack up a number of incomplete updates and eventually get quarantined (pending the failure configuration set on the relevant deployment).

header Parameters
x-peridio-uuid
required
string <uuid> (firmware-uuid)
peridio-release-prn
string (prn)
Examples: prn:1:a1ed0c4e-f222-4bb3-89dc-48320018875d:release:e4bf3021-b8d7-42d5-a1bd-52121427ebd0
peridio-release-version
string (release-version)
Example: 1.0.0

Responses

Response samples

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

get update

Returns information regarding whether an update is available via a release.

Expandable

This endpoint has an expandable response. By default, only the status field is returned. See expanding responses.

Authorizations:
MutualTLS
query Parameters
expand
Array of strings

See expanding responses.

Expandable Fields

For more information on each field, reference the response.

  • source_type
  • bundle
  • release
  • manifest
    • artifact
    • artifact_version
    • binary_prn
    • custom_metadata
    • hash
    • signatures
    • size
    • target
    • url
header Parameters
peridio-release-prn
string (prn)
Examples: prn:1:a1ed0c4e-f222-4bb3-89dc-48320018875d:release:e4bf3021-b8d7-42d5-a1bd-52121427ebd0
peridio-release-version
string (release-version)
Example: 1.0.0

Responses

Response samples

Content type
application/json
{
  • "status": "update",
  • "source_type": "release",
  • "release": {
    },
  • "bundle": {
    },
  • "custom_metadata": { },
  • "manifest": [
    ]
}

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.

List tunnels

This only returns :requested and :open tunnels.

Labs

For list options, we only support pagination params.

Authorizations:
MutualTLS
query Parameters
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
{
  • "tunnels": [
    ],
  • "next_page": "string"
}

Configure a tunnel

Configures a tunnel with device networking data.

Labs

If successful, the tunnel's state will be open. Only tunnels with a state of requested can be configured.

Authorizations:
MutualTLS
Request Body schema: application/json
required
tunnel_prn
required
string (tunnel-prn)

Peridio Resource Names (PRNs) uniquely identify Peridio resources.

cidr_blocks
required
Array of strings (cidrs)

A set of CIDR blocks that the device has available for use with remote access. The device's wireguard peer IP as well as wireguard interface IP will be choosen from this set so it must contain at least two distinct IPs.

port_ranges
required
Array of strings (port-ranges)

A set of port ranges that the device has available for use with remote access. The device can use this to constrain the pool of ports from which Peridio will choose the wireguard server listen port, that is, the port on which the server is listening for wireguard UDP traffic.

device_proxy_port
required
number

The port on which the device is listening for wireguard UDP traffic.

device_public_key
required
string

The device's public key for wireguard.

Responses

Request samples

Content type
application/json
{
  • "tunnel_prn": "prn:1:be4d30b4-de6b-47cd-85ea-a75e23fd63ef:tunnel:b3f1f699-3bc8-4c77-bda2-b974595d5e3f",
  • "cidr_blocks": [
    ],
  • "port_ranges": [
    ],
  • "device_proxy_port": 53000,
  • "device_public_key": "Y4nCIXdpb+f3WgPi0377FDPCAfP+st82s98lTRepHEk="
}

Response samples

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

Update a tunnel

Update a tunnel currently only allows changing a tunnel to a closed state.

Labs
Authorizations:
MutualTLS
path Parameters
tunnel_prn
required
string (tunnel-prn)
Example: prn:1:be4d30b4-de6b-47cd-85ea-a75e23fd63ef:tunnel:b3f1f699-3bc8-4c77-bda2-b974595d5e3f

Peridio Resource Names (PRNs) uniquely identify Peridio resources.

Request Body schema: application/json
required
state
string

The state we want the tunnel to be in. Only accepts "closed".

Responses

Request samples

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

Response samples

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